This is an automated email from the ASF dual-hosted git repository.
gustavodemorais pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new f952a922ed3 [FLINK-39717][docs] Document SET/RESET key handling for
ALTER TABLE, CATALOG, MODEL and DATABASE
f952a922ed3 is described below
commit f952a922ed33d899af8acb303ee82557b6998a81
Author: Ramin Gharib <[email protected]>
AuthorDate: Mon Jun 1 11:02:54 2026 +0200
[FLINK-39717][docs] Document SET/RESET key handling for ALTER TABLE,
CATALOG, MODEL and DATABASE
This closes #28211.
---
docs/content.zh/docs/sql/reference/ddl/alter.md | 68 +++++++++++++++++++++++++
docs/content/docs/sql/reference/ddl/alter.md | 68 +++++++++++++++++++++++++
2 files changed, 136 insertions(+)
diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md
b/docs/content.zh/docs/sql/reference/ddl/alter.md
index 1f089e28241..92a3a1c9c92 100644
--- a/docs/content.zh/docs/sql/reference/ddl/alter.md
+++ b/docs/content.zh/docs/sql/reference/ddl/alter.md
@@ -491,22 +491,40 @@ ALTER TABLE MyTable RENAME TO MyTable2;
为指定的表设置一个或多个属性。若个别属性已经存在于表中，则使用新值覆盖旧值。
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
`SET` 语句示例如下。
```sql
-- set 'rows-per-second'
ALTER TABLE DataGenSource SET ('rows-per-second' = '10');
+
+-- duplicate keys: the last value wins. After this statement,
'rows-per-second' is '20'.
+ALTER TABLE DataGenSource SET ('rows-per-second' = '10', 'rows-per-second' =
'20');
```
### RESET
为指定的表重置一个或多个属性。
+**Key handling:**
+- Keys that are not currently set on the table are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+- The `connector` key is reserved and cannot be reset. Attempting to do so is
rejected with a validation error.
+
`RESET` 语句示例如下。
```sql
-- reset 'rows-per-second' to the default value
ALTER TABLE DataGenSource RESET ('rows-per-second');
+
+-- 'invalid-key' is not currently set on the table: this is a no-op for that
key,
+-- 'rows-per-second' is still reset and the statement succeeds.
+ALTER TABLE DataGenSource RESET ('rows-per-second', 'invalid-key');
```
{{< top >}}
@@ -538,6 +556,21 @@ ALTER DATABASE [catalog_name.]db_name SET (key1=val1,
key2=val2, ...)
在数据库中设置一个或多个属性。若个别属性已经在数据库中设定，将会使用新值覆盖旧值。
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
+The following examples illustrate the usage of the `SET` statements.
+
+```sql
+-- set a database property
+ALTER DATABASE my_db SET ('k1' = 'v1');
+
+-- duplicate keys: the last value wins. After this statement, 'k1' is 'v2'.
+ALTER DATABASE my_db SET ('k1' = 'v1', 'k1' = 'v2');
+```
+
{{< top >}}
## ALTER FUNCTION
@@ -585,22 +618,40 @@ ALTER CATALOG catalog_name
为指定的 catalog 设置一个或多个属性。若个别属性已经存在，则使用新值覆盖旧值。
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
`SET` 语句示例如下。
```sql
-- set 'default-database'
ALTER CATALOG cat2 SET ('default-database'='db');
+
+-- duplicate keys: the last value wins. After this statement,
'default-database' is 'db2'.
+ALTER CATALOG cat2 SET ('default-database'='db', 'default-database'='db2');
```
### RESET
为指定的 catalog 重置一个或多个属性。
+**Key handling:**
+- Keys that are not currently set on the catalog are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+- The `type` key is reserved and cannot be reset. Attempting to do so is
rejected with a validation error.
+
`RESET` 语句示例如下。
```sql
-- reset 'default-database'
ALTER CATALOG cat2 RESET ('default-database');
+
+-- 'unknown-key' is not currently set on the catalog: this is a no-op for that
key,
+-- 'default-database' is still reset and the statement succeeds.
+ALTER CATALOG cat2 RESET ('default-database', 'unknown-key');
```
### COMMENT
@@ -632,22 +683,39 @@ ALTER MODEL [IF EXISTS]
[catalog_name.][db_name.]model_name
为指定的模型设置一个或多个属性。若个别属性已经存在，则使用新值覆盖旧值。
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- The empty option list `SET ()` is rejected with a validation error.
+
`SET` 语句示例如下。
```sql
-- 设置模型的属性
ALTER MODEL MyModel SET ('model-type'='linear', 'version'='2.0');
+
+-- duplicate keys: the last value wins. After this statement, 'version' is
'2.0'.
+ALTER MODEL MyModel SET ('version'='1.0', 'version'='2.0');
```
### RESET
为指定的模型重置一个或多个属性。
+**Key handling:**
+- Keys that are not currently set on the model are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+
`RESET` 语句示例如下。
```sql
-- 重置模型的属性
ALTER MODEL MyModel RESET ('model-type', 'version');
+
+-- 'unknown-key' is not currently set on the model: this is a no-op for that
key,
+-- 'model-type' is still reset and the statement succeeds.
+ALTER MODEL MyModel RESET ('model-type', 'unknown-key');
```
### RENAME TO
diff --git a/docs/content/docs/sql/reference/ddl/alter.md
b/docs/content/docs/sql/reference/ddl/alter.md
index 3671b422181..d99e9186ac5 100644
--- a/docs/content/docs/sql/reference/ddl/alter.md
+++ b/docs/content/docs/sql/reference/ddl/alter.md
@@ -489,22 +489,40 @@ ALTER TABLE MyTable RENAME TO MyTable2;
Set one or more properties in the specified table. If a particular property is
already set in the table, override the old value with the new one.
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
The following examples illustrate the usage of the `SET` statements.
```sql
-- set 'rows-per-second'
ALTER TABLE DataGenSource SET ('rows-per-second' = '10');
+
+-- duplicate keys: the last value wins. After this statement,
'rows-per-second' is '20'.
+ALTER TABLE DataGenSource SET ('rows-per-second' = '10', 'rows-per-second' =
'20');
```
### RESET
Reset one or more properties to its default value.
+**Key handling:**
+- Keys that are not currently set on the table are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+- The `connector` key is reserved and cannot be reset. Attempting to do so is
rejected with a validation error.
+
The following examples illustrate the usage of the `RESET` statements.
```sql
-- reset 'rows-per-second' to the default value
ALTER TABLE DataGenSource RESET ('rows-per-second');
+
+-- 'invalid-key' is not currently set on the table: this is a no-op for that
key,
+-- 'rows-per-second' is still reset and the statement succeeds.
+ALTER TABLE DataGenSource RESET ('rows-per-second', 'invalid-key');
```
{{< top >}}
@@ -536,6 +554,21 @@ ALTER DATABASE [catalog_name.]db_name SET (key1=val1,
key2=val2, ...)
Set one or more properties in the specified database. If a particular property
is already set in the database, override the old value with the new one.
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
+The following examples illustrate the usage of the `SET` statements.
+
+```sql
+-- set a database property
+ALTER DATABASE my_db SET ('k1' = 'v1');
+
+-- duplicate keys: the last value wins. After this statement, 'k1' is 'v2'.
+ALTER DATABASE my_db SET ('k1' = 'v1', 'k1' = 'v2');
+```
+
{{< top >}}
## ALTER FUNCTION
@@ -583,22 +616,40 @@ ALTER CATALOG catalog_name
Set one or more properties in the specified catalog. If a particular property
is already set in the catalog, override the old value with the new one.
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- An empty option list `SET ()` is accepted and treated as a no-op.
+
The following examples illustrate the usage of the `SET` statements.
```sql
-- set 'default-database'
ALTER CATALOG cat2 SET ('default-database'='db');
+
+-- duplicate keys: the last value wins. After this statement,
'default-database' is 'db2'.
+ALTER CATALOG cat2 SET ('default-database'='db', 'default-database'='db2');
```
### RESET
Reset one or more properties to its default value in the specified catalog.
+**Key handling:**
+- Keys that are not currently set on the catalog are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+- The `type` key is reserved and cannot be reset. Attempting to do so is
rejected with a validation error.
+
The following examples illustrate the usage of the `RESET` statements.
```sql
-- reset 'default-database'
ALTER CATALOG cat2 RESET ('default-database');
+
+-- 'unknown-key' is not currently set on the catalog: this is a no-op for that
key,
+-- 'default-database' is still reset and the statement succeeds.
+ALTER CATALOG cat2 RESET ('default-database', 'unknown-key');
```
### COMMENT
@@ -627,11 +678,19 @@ ALTER MODEL [IF EXISTS]
[catalog_name.][db_name.]model_name
Set one or more properties in the specified model. If a particular property is
already set in the model, override the old value with the new one.
+**Key handling:**
+- Properties not listed in the statement are preserved.
+- If the same key appears multiple times in the list, the last value wins and
a warning is logged.
+- The empty option list `SET ()` is rejected with a validation error.
+
The following examples illustrate the usage of the `SET` statements.
```sql
-- set model properties
ALTER MODEL MyModel SET ('model-version'='2.0', 'batch-size'='32');
+
+-- duplicate keys: the last value wins. After this statement, 'batch-size' is
'64'.
+ALTER MODEL MyModel SET ('batch-size'='32', 'batch-size'='64');
```
**IF EXISTS**
@@ -642,11 +701,20 @@ If the model does not exist, nothing happens.
Reset one or more properties to its default value in the specified model.
+**Key handling:**
+- Keys that are not currently set on the model are silently ignored. The
statement still succeeds.
+- Duplicate keys in the key list are de-duplicated and treated as a single
reset for that key.
+- The empty key list `RESET ()` is rejected with a validation error.
+
The following examples illustrate the usage of the `RESET` statements.
```sql
-- reset model properties
ALTER MODEL MyModel RESET ('model-version', 'batch-size');
+
+-- 'unknown-key' is not currently set on the model: this is a no-op for that
key,
+-- 'model-version' is still reset and the statement succeeds.
+ALTER MODEL MyModel RESET ('model-version', 'unknown-key');
```
### RENAME TO
