Skip to content

[Flink 39717][docs] Document SET/RESET key handling for ALTER TABLE, CATALOG, MODEL and DATABASE #28211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
raminqaf wants to merge 4 commits into
base: master
Choose a base branch
from
+132 −0
Open

[Flink 39717][docs] Document SET/RESET key handling for ALTER TABLE, CATALOG, MODEL and DATABASE #28211

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
029d996
[FLINK-39717][docs] Document ALTER TABLE SET/RESET key handling
raminqaf May 20, 2026
20dccf2
[FLINK-39717][docs] Document ALTER CATALOG SET/RESET key handling
raminqaf May 20, 2026
aaaa622
[FLINK-39717][docs] Document ALTER MODEL SET/RESET key handling
raminqaf May 20, 2026
ee1a17f
[FLINK-39717][docs] Document ALTER DATABASE SET key handling
raminqaf May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs/content.zh/docs/sql/reference/ddl/alter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
Expand Down Expand Up @@ -538,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.

Comment on lines +562 to +563
Copy link
Copy Markdown
Contributor

@gustavodemorais gustavodemorais May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit

Suggested change
- An empty option list `SET ()` is accepted and treated as a no-op.
- 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
Expand Down Expand Up @@ -585,22 +616,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
Expand Down Expand Up @@ -632,22 +681,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
Expand Down
66 changes: 66 additions & 0 deletions docs/content/docs/sql/reference/ddl/alter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
Expand Down Expand Up @@ -536,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
Expand Down Expand Up @@ -583,22 +614,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
Expand Down Expand Up @@ -627,11 +676,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**
Expand All @@ -642,11 +699,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
Expand Down