[FEATURE] Support altering ClickHouse table settings
- Dominant language
- Java
- Stars
- 3.2k
- Forks
- 935
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 298
Description
### Describe the feature
The ClickHouse JDBC catalog exposes table-level MergeTree settings as table properties with the `settings.` prefix and preserves them through CREATE and load operations, but ALTER currently rejects both `TableChange.SetProperty` and `TableChange.RemoveProperty`. Add support for modifying and resetting these existing table properties without recreating the table.
### Motivation
ClickHouse operators commonly adjust table settings such as `merge_with_ttl_timeout` after table creation. The current catalog can read and create these settings but cannot alter them, leaving an asymmetric lifecycle and forcing users to bypass Gravitino or recreate tables.
### Describe the solution
- Map `SetProperty("settings.", )` to `ALTER TABLE ... MODIFY SETTING = `.
- Map `RemoveProperty("settings.")` to `ALTER TABLE ... RESET SETTING `.
- Keep engine, cluster metadata, distributed-table properties, and every other non-`settings.*` property immutable through this path.
- Accept settings-only requests containing either set operations or remove operations. Reject requests that mix set and remove operations, or settings with schema, comment, or index changes, before opening a JDBC connection.
- Validate setting names and scalar literal syntax locally, but let ClickHouse remain authoritative for read-only, unknown, range, and permission errors. Do not maintain a client-side mutable-setting whitelist.
- Reuse trusted cluster metadata so Gravitino-managed cluster tables emit `ON CLUSTER`.
- Avoid logging setting values; diagnostic logs should contain only validated setting names.
### Additional context
- Native ClickHouse 24.8.14.39 validation confirmed that individual `MODIFY SETTING` and `RESET SETTING` commands succeed for `merge_with_ttl_timeout`, while a single ALTER mixing MODIFY and RESET is rejected with code 62 `SYNTAX_ERROR` without a partial metadata change.
- `index_granularity` is a read-only negative example and returns `READONLY_SETTING`; it should not be advertised as mutable.
- The proposed scope is limited to table-level settings. Column-level SETTINGS, quoted-comma SETTINGS load/recreate parsing, automatic rollback/retry, and new ReplicatedMergeTree compatibility claims are excluded.
- Verification should include direct unit coverage, ClickHouse 24.8 standalone modify/reset/load and error paths, and a trusted-cluster test that inspects `system.query_log` for the emitted `ON CLUSTER` SQL.
Contributor guide
Research direction
Start at the ClickHouse JDBC catalog ALTER path and its existing table-property handling, then review the direct unit coverage and ClickHouse 24.8 integration scenarios described in the issue. Done means settings-only set or remove requests generate the appropriate MODIFY or RESET statements, validate locally, preserve cluster behavior, reject unsupported mixes before connecting, and cover standalone, error, and trusted-cluster query-log cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- clickhouse, java
- Domain
- databases
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100