Skip to content

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

Open
raminqaf wants to merge 4 commits into
apache:masterfrom
raminqaf:FLINK-39717
Open

[Flink 39717][docs] Document SET/RESET key handling for ALTER TABLE, CATALOG, MODEL and DATABASE#28211
raminqaf wants to merge 4 commits into
apache:masterfrom
raminqaf:FLINK-39717

Conversation

@raminqaf
Copy link
Copy Markdown
Contributor

What is the purpose of the change

The reference docs for ALTER TABLE, ALTER CATALOG, ALTER MODEL, and ALTER DATABASE describe SET/RESET only as "override the old value with the new one". The actual converter behavior handles several edge cases (duplicate keys, unknown keys, empty lists, reserved keys) that are not documented and differ across the four DDLs. This PR documents that behavior so users can predict the outcome without reading the converter source.

Docs-only change. No code changes. Aligns with the per-DDL behavior already documented for ALTER MATERIALIZED TABLE in FLINK-39662 / FLINK-39663.

Brief change log

  • docs/content/docs/sql/reference/ddl/alter.md: spell out behavior for ALTER TABLE, ALTER CATALOG, ALTER MODEL, ALTER DATABASE under SET and RESET.
  • docs/content.zh/docs/sql/reference/ddl/alter.md: mirror in the Chinese docs.

Summary

DDL SET empty SET dupes SET reserved RESET empty RESET unknown RESET reserved
TABLE no-op last-wins+warn reject no-op connector
CATALOG no-op last-wins+warn reject no-op type
MODEL reject last-wins+warn reject no-op
DATABASE no-op last-wins+warn n/a n/a n/a

Verifying this change

Docs-only update. No tests added. Documented behavior is covered by existing parser/converter tests for each DDL.

Does this pull request potentially affect one of the following parts:

  • Dependencies (does it add or upgrade a dependency): no
  • The public API, i.e., is any changed class annotated with @Public(Evolving): no
  • The serializers: no
  • The runtime per-record code paths (performance sensitive): no
  • Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
  • The S3 file system connector: no

Documentation

  • Does this pull request introduce a new feature? no
  • If yes, how is the feature documented? docs (this PR is the documentation)

Was generative AI tooling used to co-author this PR?
  • Yes (please specify the tool below)

Opus: 4.7

raminqaf added 4 commits May 20, 2026 09:32
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.
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.
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.
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.
@flinkbot
Copy link
Copy Markdown
Collaborator

flinkbot commented May 20, 2026

CI report:

Bot commands The @flinkbot bot supports the following commands:
  • @flinkbot run azure re-run the last Azure build

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants