This is an automated email from the ASF dual-hosted git repository.
davidzollo pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 85f15bec61 [Docs] Clarify JDBC primary key placeholder behavior
(#11295)
85f15bec61 is described below
commit 85f15bec610a6464b01e7e9c7c8302ea33454f73
Author: Shivraj Solanki <[email protected]>
AuthorDate: Sun Jul 5 15:24:05 2026 +0530
[Docs] Clarify JDBC primary key placeholder behavior (#11295)
---
.../configuration/sink-options-placeholders.md | 33 +++++++++++++++++++++
.../configuration/sink-options-placeholders.md | 34 ++++++++++++++++++++++
2 files changed, 67 insertions(+)
diff --git a/docs/en/introduction/configuration/sink-options-placeholders.md
b/docs/en/introduction/configuration/sink-options-placeholders.md
index ad817b14c7..ed939e0fea 100644
--- a/docs/en/introduction/configuration/sink-options-placeholders.md
+++ b/docs/en/introduction/configuration/sink-options-placeholders.md
@@ -106,6 +106,39 @@ sink {
}
}
```
+## Primary Key Placeholder Behavior
+
+The `${primary_key}` placeholder expands to all primary key columns defined in
the upstream table metadata.
+
+For example, if the upstream table primary key is:
+
+```text
+(f1, f2)
+```
+
+then:
+
+```hocon
+primary_keys = ["${primary_key}"]
+```
+
+will be expanded to:
+
+```hocon
+primary_keys = ["f1", "f2"]
+```
+
+Mixing `${primary_key}` with static column names is currently not supported.
+
+For example, the following configuration is **not supported**:
+
+```hocon
+primary_keys = ["${primary_key}", "tenant_id"]
+```
+
+The placeholder replacement for list values is only applied when
`${primary_key}` is the only element in the list.
+
+The behavior is the same for both single-table and multi-table jobs.
We will complete the placeholder replacement before the connector is started,
ensuring that the sink options is ready before use.
If the variable is not replaced, it may be that the upstream table metadata is
missing this option, for example:
diff --git a/docs/zh/introduction/configuration/sink-options-placeholders.md
b/docs/zh/introduction/configuration/sink-options-placeholders.md
index 18d663cd6d..9cd3821e58 100644
--- a/docs/zh/introduction/configuration/sink-options-placeholders.md
+++ b/docs/zh/introduction/configuration/sink-options-placeholders.md
@@ -107,6 +107,40 @@ sink {
}
```
+## Primary Key 占位符行为
+
+`${primary_key}` 占位符会展开为上游表元数据中定义的所有主键列。
+
+例如，如果上游表的主键为：
+
+```text
+(f1, f2)
+```
+
+那么：
+
+```hocon
+primary_keys = ["${primary_key}"]
+```
+
+会被展开为：
+
+```hocon
+primary_keys = ["f1", "f2"]
+```
+
+当前不支持将 `${primary_key}` 与静态列名混合使用。
+
+例如，以下配置 **不受支持**：
+
+```hocon
+primary_keys = ["${primary_key}", "tenant_id"]
+```
+
+只有当 `${primary_key}` 是列表中的唯一元素时，才会执行列表占位符替换。
+
+单表任务和多表任务中的行为保持一致。
+
占位符的替换将在连接器启动之前完成，确保 Sink 参数在使用前已准备就绪。
若该占位符变量没有被替换，则可能是上游表元数据缺少该选项，例如：
- `mysql` source 连接器不包含 `${schema_name}` 元数据
