From 029d99653ad1a3bc7309a49abc2f458fdea2291b Mon Sep 17 00:00:00 2001 From: Ramin Gharib Date: Wed, 20 May 2026 09:09:15 +0200 Subject: [PATCH 1/4] [FLINK-39717][docs] Document ALTER TABLE SET/RESET key handling Spell out the behavior for duplicate keys (last value wins for SET, de-duplicated for RESET), unknown keys (silently ignored on RESET), the empty list (accepted as no-op for SET, rejected for RESET), and the reserved `connector` key (rejected for RESET). Add examples. --- .../content.zh/docs/sql/reference/ddl/alter.md | 18 ++++++++++++++++++ docs/content/docs/sql/reference/ddl/alter.md | 18 ++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md b/docs/content.zh/docs/sql/reference/ddl/alter.md index 1f089e28241d0..aaed0eef21a85 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 >}} diff --git a/docs/content/docs/sql/reference/ddl/alter.md b/docs/content/docs/sql/reference/ddl/alter.md index 3671b422181c6..c7c7cbea47bbb 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 >}} From 20dccf244a1badd370241c33abca597081bb1e1d Mon Sep 17 00:00:00 2001 From: Ramin Gharib Date: Wed, 20 May 2026 09:11:50 +0200 Subject: [PATCH 2/4] [FLINK-39717][docs] Document ALTER CATALOG SET/RESET key handling Spell out the behavior for duplicate keys (last value wins for SET, de-duplicated for RESET), unknown keys (silently ignored on RESET), the empty list (accepted as no-op for SET, rejected for RESET), and the reserved `type` key (rejected for RESET). Add examples. --- .../content.zh/docs/sql/reference/ddl/alter.md | 18 ++++++++++++++++++ docs/content/docs/sql/reference/ddl/alter.md | 18 ++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md b/docs/content.zh/docs/sql/reference/ddl/alter.md index aaed0eef21a85..85ac2f62062d1 100644 --- a/docs/content.zh/docs/sql/reference/ddl/alter.md +++ b/docs/content.zh/docs/sql/reference/ddl/alter.md @@ -603,22 +603,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 diff --git a/docs/content/docs/sql/reference/ddl/alter.md b/docs/content/docs/sql/reference/ddl/alter.md index c7c7cbea47bbb..ffec10247e0b9 100644 --- a/docs/content/docs/sql/reference/ddl/alter.md +++ b/docs/content/docs/sql/reference/ddl/alter.md @@ -601,22 +601,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 From aaaa622adeed8d02bb47baef1ccbc8c7db8de98f Mon Sep 17 00:00:00 2001 From: Ramin Gharib Date: Wed, 20 May 2026 09:14:12 +0200 Subject: [PATCH 3/4] [FLINK-39717][docs] Document ALTER MODEL SET/RESET key handling Spell out the behavior for duplicate keys (last value wins for SET, de-duplicated for RESET), unknown keys (silently ignored on RESET), and the empty list (rejected for both SET and RESET, unlike ALTER TABLE/CATALOG SET which accept empty as a no-op). Add examples. --- docs/content.zh/docs/sql/reference/ddl/alter.md | 17 +++++++++++++++++ docs/content/docs/sql/reference/ddl/alter.md | 17 +++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md b/docs/content.zh/docs/sql/reference/ddl/alter.md index 85ac2f62062d1..b02d2e89ebe76 100644 --- a/docs/content.zh/docs/sql/reference/ddl/alter.md +++ b/docs/content.zh/docs/sql/reference/ddl/alter.md @@ -668,22 +668,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 ffec10247e0b9..824d10403120c 100644 --- a/docs/content/docs/sql/reference/ddl/alter.md +++ b/docs/content/docs/sql/reference/ddl/alter.md @@ -663,11 +663,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** @@ -678,11 +686,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 From ee1a17f7b172dd8b88356282dc3524158e620b84 Mon Sep 17 00:00:00 2001 From: Ramin Gharib Date: Wed, 20 May 2026 09:16:16 +0200 Subject: [PATCH 4/4] [FLINK-39717][docs] Document ALTER DATABASE SET key handling Spell out the behavior for duplicate keys (last value wins, warning logged) and the empty list (accepted as no-op). Add an example. ALTER DATABASE only supports SET; there is no RESET form. --- docs/content.zh/docs/sql/reference/ddl/alter.md | 13 +++++++++++++ docs/content/docs/sql/reference/ddl/alter.md | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md b/docs/content.zh/docs/sql/reference/ddl/alter.md index b02d2e89ebe76..0ada07d647b60 100644 --- a/docs/content.zh/docs/sql/reference/ddl/alter.md +++ b/docs/content.zh/docs/sql/reference/ddl/alter.md @@ -556,6 +556,19 @@ 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. + +```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 diff --git a/docs/content/docs/sql/reference/ddl/alter.md b/docs/content/docs/sql/reference/ddl/alter.md index 824d10403120c..56a1f9346687f 100644 --- a/docs/content/docs/sql/reference/ddl/alter.md +++ b/docs/content/docs/sql/reference/ddl/alter.md @@ -554,6 +554,19 @@ 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. + +```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