You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by gi...@apache.org on 2026/08/26 14:31:35 UTC
(seatunnel) 01/01: [Improve][Connector-V2][Iceberg]Migrate config validation to declarative OptionRule (#11921)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-11921-8725e1e1372c65f871830eb5f8ca2a0551d73504
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit 4f0b735de7da66775e1bb7cc035f46f3a21517ef
Author: Claire <cl...@163.com>
AuthorDate: Wed Aug 26 14:31:24 2026 +0000
[Improve][Connector-V2][Iceberg]Migrate config validation to declarative OptionRule (#11921)
---
docs/en/connectors/source/Iceberg.md | 2 +-
docs/zh/connectors/source/Iceberg.md | 2 +-
.../iceberg/config/IcebergSinkConfig.java | 15 -----
.../iceberg/config/IcebergSinkOptions.java | 5 +-
.../seatunnel/iceberg/sink/IcebergSinkFactory.java | 9 +++
.../iceberg/source/IcebergSourceFactory.java | 6 +-
.../seatunnel/iceberg/IcebergFactoryTest.java | 76 ++++++++++++++++++++++
.../seatunnel/iceberg/utils/SchemaUtilsTest.java | 28 --------
.../e2e/connector/iceberg/IcebergValidationIT.java | 58 +++++++++++++++++
...eberg-validation-nonpositive-scan-interval.conf | 44 +++++++++++++
.../iceberg-validation-upsert-without-pk.conf | 52 +++++++++++++++
11 files changed, 250 insertions(+), 47 deletions(-)
diff --git a/docs/en/connectors/source/Iceberg.md b/docs/en/connectors/source/Iceberg.md
index 338bbe1936..0023ca635f 100644
--- a/docs/en/connectors/source/Iceberg.md
+++ b/docs/en/connectors/source/Iceberg.md
@@ -90,7 +90,7 @@ libfb303-xxx.jar
| use_snapshot_id | long | no | - | Instructs this scan to look for use the given snapshot ID. [...]
| use_snapshot_timestamp | long | no | - | Instructs this scan to look for use the most recent snapshot as of the given time in milliseconds. timestamp – the timestamp in millis since the Unix epoch [...]
| stream_scan_strategy | enum | no | FROM_LATEST_SNAPSHOT | Starting strategy for stream mode execution, Default to use `FROM_LATEST_SNAPSHOT` if don't specify any value,The optional values are:<br/>TABLE_SCAN_THEN_INCREMENTAL: Do a regular table scan then switch to the incremental mode.<br/>FROM_LATEST_SNAPSHOT: Start incremental mode from the latest snapshot inclusive.<br/>FROM_EARLIEST_SNAPSHOT: Start incremental mode from the earliest snapshot inclusive.<br/>FROM_SNAPSHO [...]
-| increment.scan-interval | long | no | 2000 | The interval of increment scan(mills) [...]
+| increment.scan-interval | long | no | 2000 | The interval of increment scan(mills). Must be a positive value. [...]
| common-options | | no | - | Source plugin common parameters, please refer to [Source Common Options](../common-options/source-common-options.md) for details. [...]
| query | String | no | - | The select DML used to filter or project Iceberg data. Use the literal placeholder table name `table`, and do not use table aliases. For example: `select * from table where f1 > 100`, `select fn from table where f1 > 100`. The current LIKE support is limited: the LIKE pattern should not start with `%`; for example, `select f1 from table where f2 like 'tom%'` is supported. [...]
| krb5_path | string | no | /etc/krb5.conf | The path to the `krb5.conf` file for Kerberos authentication. |
diff --git a/docs/zh/connectors/source/Iceberg.md b/docs/zh/connectors/source/Iceberg.md
index 11797afc85..482882648b 100644
--- a/docs/zh/connectors/source/Iceberg.md
+++ b/docs/zh/connectors/source/Iceberg.md
@@ -90,7 +90,7 @@ libfb303-xxx.jar
| use_snapshot_id | long | 否 | - | 指示此扫描使用给定的快照 ID。 [...]
| use_snapshot_timestamp | long | 否 | - | 指示此扫描使用给定时间(毫秒)的最新快照。timestamp – 自 Unix 纪元以来的时间戳(毫秒) |
| stream_scan_strategy | enum | 否 | FROM_LATEST_SNAPSHOT | 流模式执行的启动策略,如果不指定任何值,默认使用 `FROM_LATEST_SNAPSHOT`,可选值为:<br/>TABLE_SCAN_THEN_INCREMENTAL:执行常规表扫描,然后切换到增量模式。<br/>FROM_LATEST_SNAPSHOT:从最新快照(包含)开始增量模式。<br/>FROM_EARLIEST_SNAPSHOT:从最早快照(包含)开始增量模式。<br/>FROM_SNAPSHOT_ID:从具有特定 id(包含)的快照开始增量模式。<br/>FROM_SNAPSHOT_TIMESTAMP:从具有特定时间戳(包含)的快照开始增量模式。 |
-| increment.scan-interval | long | 否 | 2000 | 增量扫描的间隔(毫秒) [...]
+| increment.scan-interval | long | 否 | 2000 | 增量扫描的间隔(毫秒),必须为正数 [...]
| common-options | | 否 | - | 源插件通用参数,请参考 [源通用选项](../common-options/source-common-options.md) 详见。 [...]
| query | String | 否 | - | 用于过滤或投影 Iceberg 数据的 select DML。这里使用固定占位表名 `table`,不要写真实表名,也不支持表别名。例如:`select * from table where f1 > 100`、`select fn from table where f1 > 100`。当前对 LIKE 语法的支持有限:LIKE 模式不应以 `%` 开头,例如 `select f1 from table where f2 like 'tom%'`。 [...]
| krb5_path | string | no | /etc/krb5.conf | `krb5.conf` 文件的路径,用于 Kerberos 认证。 |
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
index 4fa9806eeb..6567208e4e 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
@@ -81,21 +81,6 @@ public class IcebergSinkConfig extends IcebergCommonConfig {
this.dataSaveMode = readonlyConfig.get(IcebergSinkOptions.DATA_SAVE_MODE);
this.dataSaveModeSQL = readonlyConfig.get(IcebergSinkOptions.DATA_SAVE_MODE_CUSTOM_SQL);
this.commitBranch = readonlyConfig.get(IcebergSinkOptions.TABLES_DEFAULT_COMMIT_BRANCH);
- if (this.upsertModeEnabled
- && readonlyConfig
- .getOptional(IcebergSinkOptions.TABLE_PRIMARY_KEYS)
- .map(String::trim)
- .map(String::isEmpty)
- .orElse(true)) {
- throw new IllegalArgumentException(
- String.format(
- "'%s' is enabled but '%s' is not explicitly configured. "
- + "Upsert mode requires an explicit primary-key list. "
- + "The source table primary key is no longer inherited "
- + "automatically (see: apache/seatunnel#10747).",
- IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP.key(),
- IcebergSinkOptions.TABLE_PRIMARY_KEYS.key()));
- }
}
@VisibleForTesting
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
index 8557b90374..38204b042b 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
@@ -55,7 +55,10 @@ public class IcebergSinkOptions extends IcebergCommonOptions {
.stringType()
.noDefaultValue()
.withDescription(
- "Default comma-separated list of columns that identify a row in tables (primary key)");
+ "Default comma-separated list of columns that identify a row in tables (primary key). "
+ + "Required and must be non-blank when 'iceberg.table.upsert-mode-enabled' is true: "
+ + "upsert mode needs an explicit primary-key list because the source table primary key "
+ + "is no longer inherited automatically (see: apache/seatunnel#10747)");
public static final Option<String> TABLE_DEFAULT_PARTITION_KEYS =
Options.key("iceberg.table.partition-keys")
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
index f71aa440db..1eb1e4c8dd 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
@@ -20,6 +20,7 @@ package org.apache.seatunnel.connectors.seatunnel.iceberg.sink;
import org.apache.seatunnel.shade.org.apache.commons.lang3.StringUtils;
import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.configuration.util.Conditions;
import org.apache.seatunnel.api.configuration.util.OptionRule;
import org.apache.seatunnel.api.options.SinkConnectorCommonOptions;
import org.apache.seatunnel.api.sink.DataSaveMode;
@@ -71,6 +72,14 @@ public class IcebergSinkFactory implements TableSinkFactory {
IcebergSinkOptions.DATA_SAVE_MODE,
DataSaveMode.CUSTOM_PROCESSING,
IcebergSinkOptions.DATA_SAVE_MODE_CUSTOM_SQL)
+ .conditional(
+ IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP,
+ true,
+ IcebergSinkOptions.TABLE_PRIMARY_KEYS)
+ .conditional(
+ IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP,
+ true,
+ Conditions.notBlank(IcebergSinkOptions.TABLE_PRIMARY_KEYS))
.build();
}
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
index 49538f6905..029bc313f3 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
@@ -18,6 +18,7 @@
package org.apache.seatunnel.connectors.seatunnel.iceberg.source;
import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.configuration.util.Conditions;
import org.apache.seatunnel.api.configuration.util.OptionRule;
import org.apache.seatunnel.api.options.ConnectorCommonOptions;
import org.apache.seatunnel.api.source.SeaTunnelSource;
@@ -70,12 +71,15 @@ public class IcebergSourceFactory implements TableSourceFactory {
IcebergSourceOptions.KEY_USE_SNAPSHOT_ID,
IcebergSourceOptions.KEY_USE_SNAPSHOT_TIMESTAMP,
IcebergSourceOptions.KEY_STREAM_SCAN_STRATEGY,
- IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL,
IcebergCommonOptions.HADOOP_PROPS,
IcebergSourceOptions.HADOOP_CONF_PATH_PROP,
IcebergCommonOptions.KERBEROS_PRINCIPAL,
IcebergCommonOptions.KERBEROS_KEYTAB_PATH,
IcebergCommonOptions.KRB5_PATH)
+ .optional(
+ IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL,
+ Conditions.greaterThan(
+ IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL, 0L))
.build();
}
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
index 939dbb9c44..ef201bdffb 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
@@ -31,6 +31,8 @@ import org.apache.seatunnel.connectors.seatunnel.iceberg.source.IcebergSourceFac
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
import java.util.Arrays;
import java.util.Collections;
@@ -99,6 +101,31 @@ class IcebergFactoryTest {
absolutelyRequiredOptions(SINK_RULE).contains(IcebergSinkOptions.CATALOG_PROPS));
}
+ @Test
+ void sinkUpsertConditionallyRequiresPrimaryKeys() {
+ boolean hasConditional =
+ SINK_RULE.getRequiredOptions().stream()
+ .filter(o -> o instanceof RequiredOption.ConditionalRequiredOptions)
+ .anyMatch(
+ o ->
+ o.getOptions()
+ .contains(IcebergSinkOptions.TABLE_PRIMARY_KEYS));
+ Assertions.assertTrue(hasConditional);
+ }
+
+ @Test
+ void sourceScanIntervalHasValueConstraint() {
+ boolean hasConstraint =
+ SOURCE_RULE.getValueConstraints().stream()
+ .anyMatch(
+ c ->
+ c.getOption()
+ .equals(
+ IcebergSourceOptions
+ .KEY_INCREMENT_SCAN_INTERVAL));
+ Assertions.assertTrue(hasConstraint);
+ }
+
// accepted configs
@Test
@@ -132,6 +159,30 @@ class IcebergFactoryTest {
Assertions.assertDoesNotThrow(() -> validateSink(config));
}
+ @Test
+ void sinkUpsertWithPrimaryKeysValid() {
+ Map<String, Object> config = new HashMap<>();
+ config.put("iceberg.catalog.config", catalogProps());
+ config.put("iceberg.table.upsert-mode-enabled", true);
+ config.put("iceberg.table.primary-keys", "id");
+ Assertions.assertDoesNotThrow(() -> validateSink(config));
+ }
+
+ @Test
+ void sinkNoUpsertWithoutPrimaryKeysValid() {
+ Map<String, Object> config = new HashMap<>();
+ config.put("iceberg.catalog.config", catalogProps());
+ config.put("iceberg.table.upsert-mode-enabled", false);
+ Assertions.assertDoesNotThrow(() -> validateSink(config));
+ }
+
+ @Test
+ void sourcePositiveScanIntervalValid() {
+ Map<String, Object> config = sourceConfigWithTable();
+ config.put("increment.scan-interval", 2000L);
+ Assertions.assertDoesNotThrow(() -> validateSource(config));
+ }
+
// rejected configs
@Test
@@ -163,6 +214,31 @@ class IcebergFactoryTest {
Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
}
+ @Test
+ void sinkUpsertWithoutPrimaryKeysRejected() {
+ Map<String, Object> config = new HashMap<>();
+ config.put("iceberg.catalog.config", catalogProps());
+ config.put("iceberg.table.upsert-mode-enabled", true);
+ Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
+ }
+
+ @Test
+ void sinkUpsertWithBlankPrimaryKeysRejected() {
+ Map<String, Object> config = new HashMap<>();
+ config.put("iceberg.catalog.config", catalogProps());
+ config.put("iceberg.table.upsert-mode-enabled", true);
+ config.put("iceberg.table.primary-keys", " ");
+ Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
+ }
+
+ @ParameterizedTest
+ @ValueSource(longs = {0L, -1L})
+ void sourceNonPositiveScanIntervalRejected(long interval) {
+ Map<String, Object> config = sourceConfigWithTable();
+ config.put("increment.scan-interval", interval);
+ Assertions.assertThrows(OptionValidationException.class, () -> validateSource(config));
+ }
+
// helpers
/**
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
index 030e2fc66d..274d53047e 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
@@ -172,34 +172,6 @@ class SchemaUtilsTest {
+ "and causes positional deletes in append-only CDC pipelines.");
}
- /**
- * Guard against the regression introduced by the SchemaUtils PK-fallback fix: when {@code
- * iceberg.table.upsert-mode-enabled=true} is set without an explicit {@code
- * iceberg.table.primary-keys}, the sink must fail fast with a clear error rather than silently
- * creating a delta writer with an empty identifier-field set (which would produce broken upsert
- * semantics).
- */
- @Test
- void testIcebergSinkConfigThrowsWhenUpsertModeEnabledWithoutPrimaryKeys() {
- ReadonlyConfig config =
- ReadonlyConfig.fromMap(
- new HashMap<String, Object>() {
- {
- put(IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP.key(), true);
- // iceberg.table.primary-keys deliberately absent
- }
- });
- IllegalArgumentException ex =
- Assertions.assertThrows(
- IllegalArgumentException.class,
- () -> new IcebergSinkConfig(config),
- "IcebergSinkConfig must reject upsert-mode-enabled=true without an "
- + "explicit iceberg.table.primary-keys configuration");
- Assertions.assertTrue(
- ex.getMessage().contains(IcebergSinkOptions.TABLE_PRIMARY_KEYS.key()),
- "Error message should name the missing config key");
- }
-
/**
* Regression test for the catalog-path CatalogTable PK fallback.
*
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java
new file mode 100644
index 0000000000..c29ab67ba1
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java
@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.seatunnel.e2e.connector.iceberg;
+
+import org.apache.seatunnel.e2e.common.TestSuiteBase;
+import org.apache.seatunnel.e2e.common.container.TestContainer;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.TestTemplate;
+import org.testcontainers.containers.Container;
+
+import lombok.extern.slf4j.Slf4j;
+
+import java.io.IOException;
+
+@Slf4j
+public class IcebergValidationIT extends TestSuiteBase {
+
+ @TestTemplate
+ public void testSinkUpsertWithoutPrimaryKeysRejected(TestContainer container)
+ throws IOException, InterruptedException {
+ Container.ExecResult execResult =
+ container.executeJob("/iceberg/iceberg-validation-upsert-without-pk.conf");
+ Assertions.assertNotEquals(0, execResult.getExitCode());
+ String stderr = execResult.getStderr();
+ Assertions.assertNotNull(stderr, "stderr should not be null");
+ Assertions.assertTrue(
+ stderr.contains("Option validation failed") && stderr.contains("primary-keys"),
+ "stderr should report the failed primary-keys validation, but was: " + stderr);
+ }
+
+ @TestTemplate
+ public void testSourceNonPositiveScanIntervalRejected(TestContainer container)
+ throws IOException, InterruptedException {
+ Container.ExecResult execResult =
+ container.executeJob("/iceberg/iceberg-validation-nonpositive-scan-interval.conf");
+ Assertions.assertNotEquals(0, execResult.getExitCode());
+ String stderr = execResult.getStderr();
+ Assertions.assertNotNull(stderr, "stderr should not be null");
+ Assertions.assertTrue(
+ stderr.contains("Option validation failed") && stderr.contains("scan-interval"),
+ "stderr should report the failed scan-interval validation, but was: " + stderr);
+ }
+}
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf
new file mode 100644
index 0000000000..82db5a5582
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf
@@ -0,0 +1,44 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Negative case for declarative validation (#11007): `increment.scan-interval` must be
+# a positive number of milliseconds, so a value of 0 must be rejected at submission time
+# by IcebergSourceFactory.optionRule() before any catalog is touched. No Iceberg
+# environment is required.
+
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ Iceberg {
+ catalog_name = "seatunnel_test"
+ iceberg.catalog.config = {
+ "type" = "hadoop"
+ "warehouse" = "file:///tmp/seatunnel_mnt/iceberg/hadoop-source/"
+ }
+ namespace = "seatunnel_namespace"
+ table = "iceberg_source_table"
+ increment.scan-interval = 0
+ }
+}
+
+sink {
+ Console {
+ }
+}
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf
new file mode 100644
index 0000000000..4b53c6f278
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf
@@ -0,0 +1,52 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Negative case for declarative validation (#11007): `iceberg.table.upsert-mode-enabled`
+# is true but `iceberg.table.primary-keys` is not configured, so the job must be rejected
+# at submission time by IcebergSinkFactory.optionRule() before any catalog is touched.
+# No Iceberg environment is required.
+
+env {
+ parallelism = 1
+ job.mode = "BATCH"
+}
+
+source {
+ FakeSource {
+ row.num = 10
+ schema = {
+ fields {
+ id = int
+ name = string
+ }
+ }
+ plugin_output = "fake"
+ }
+}
+
+sink {
+ Iceberg {
+ catalog_name = "seatunnel_test"
+ iceberg.catalog.config = {
+ "type" = "hadoop"
+ "warehouse" = "file:///tmp/seatunnel_mnt/iceberg/hadoop-sink/"
+ }
+ namespace = "seatunnel_namespace"
+ table = "iceberg_sink_table"
+ iceberg.table.upsert-mode-enabled = true
+ }
+}