apache / apache/gravitino

[FEATURE] Support altering ClickHouse table settings

Open
#12,768 0 comments 0 reactions 0 assignees View on GitHub
feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.