This is an automated email from the ASF dual-hosted git repository.
yuqi1129 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new c93a0ea646 [MINOR] docs(clickhouse): document engine properties and
index expression limits (#13143)
c93a0ea646 is described below
commit c93a0ea6464579b7db63e32dc20a13fe2d4068d7
Author: StormSpirit <[email protected]>
AuthorDate: Mon Sep 14 21:24:46 2026 +0800
[MINOR] docs(clickhouse): document engine properties and index expression
limits (#13143)
### What changes were proposed in this pull request?
Document the existing ClickHouse catalog contracts for engine-specific
table properties and data-skipping index expressions.
- Add `graphite.config` to the table property reference and document its
conditional requirement for `GraphiteMergeTree`.
- Add `engine_parameters` to the table property reference and document
its supported engines, load-time restoration, and parameter format.
- Document that data-skipping indexes with expressions that cannot be
represented as Gravitino field names are skipped with a warning during
table loading and are not recreated.
- Keep the property table columns aligned for readability.
This pull request changes documentation only. It does not modify runtime
behavior, public APIs, dependencies, or tests.
### Why are the changes needed?
The ClickHouse catalog already supports `graphite.config` and
`engine_parameters`, and already skips unsupported index expressions
during metadata loading. These existing behaviors were not fully
described in the ClickHouse catalog documentation, making the supported
scope and round-trip limitations unclear to users.
Fix: N/A (documentation-only correction)
### Does this PR introduce _any_ user-facing change?
Yes. Users can now find the existing ClickHouse engine property
contracts and the limitation on expression-based data-skipping indexes
in the catalog documentation. No runtime behavior or public API changes
are introduced.
### How was this patch tested?
- `./gradlew :docs:build --no-daemon --console=plain` — passed,
including the repository's OpenAPI lint tasks.
- `git diff --check` — passed.
- Cross-checked the documented behavior against the ClickHouse catalog
implementation and merged pull requests
[#12274](https://github.com/apache/gravitino/pull/12274) and
[#12917](https://github.com/apache/gravitino/pull/12917).
Signed-off-by: jiangxt2 <[email protected]>
---
docs/jdbc-clickhouse-catalog.md | 25 ++++++++++++++++---------
1 file changed, 16 insertions(+), 9 deletions(-)
diff --git a/docs/jdbc-clickhouse-catalog.md b/docs/jdbc-clickhouse-catalog.md
index 90af2cc5b2..468d80909d 100644
--- a/docs/jdbc-clickhouse-catalog.md
+++ b/docs/jdbc-clickhouse-catalog.md
@@ -223,18 +223,23 @@ If you need Gravitino to manage an existing cluster
database or table, recreate
**Memory engine data volatility**: Tables created with `engine=Memory` store
data in RAM only. After a ClickHouse server restart the table definition
persists (Gravitino's `loadTable` succeeds), but all data is permanently lost.
Gravitino metadata and ClickHouse remain consistent at the schema level, but
users are responsible for repopulating data after restarts. Consider using
`TinyLog`, `StripeLog`, or a MergeTree-family engine if data durability is
required.
:::
-| Property Name | Description
| Default Value |
Required | Reserved | Immutable |
-|---------------------------|----------------------------------------------------------------------------------------------------------|---------------|----------|----------|-----------|
-| `engine` | Table engine (for example `MergeTree`,
`ReplacingMergeTree`, `Distributed`, `Memory`, etc.) | `MergeTree`
| No | No | Yes |
-| `cluster-name` | Cluster name used with `ON CLUSTER` and
Distributed engine | (none)
| No\* | No | No |
-| `on-cluster` | Use `ON CLUSTER` when creating the table
| (none) | No
| No | No |
-| `cluster-remote-database` | Remote database for `Distributed` engine
| (none) |
No\*\* | No | No |
-| `cluster-remote-table` | Remote table for `Distributed` engine
| (none) |
No\*\* | No | No |
-| `cluster-sharding-key` | Sharding key for `Distributed` engine
(expression allowed; referenced columns must be non-null integral) | (none)
| No\*\* | No | No |
-| `settings.<name>` | ClickHouse engine setting forwarded as `SETTINGS
<name>=<value>` | (none) | No
| No | No |
+| Property Name | Description
| Default Value |
Required | Reserved | Immutable |
+|---------------------------|----------------------------------------------------------------------------------------------------------|---------------|------------|----------|-----------|
+| `engine` | Table engine (for example `MergeTree`,
`ReplacingMergeTree`, `Distributed`, `Memory`, etc.) | `MergeTree`
| No | No | Yes |
+| `graphite.config` | Name of the `<graphite_rollup>` configuration
element used by `GraphiteMergeTree` | (none) |
No\*\*\* | No | No |
+| `engine_parameters` | Parameters for supported parameterized MergeTree
engines | (none) | No
| No | No |
+| `cluster-name` | Cluster name used with `ON CLUSTER` and
Distributed engine | (none)
| No\* | No | No |
+| `on-cluster` | Use `ON CLUSTER` when creating the table
| (none) | No
| No | No |
+| `cluster-remote-database` | Remote database for `Distributed` engine
| (none) |
No\*\* | No | No |
+| `cluster-remote-table` | Remote table for `Distributed` engine
| (none) |
No\*\* | No | No |
+| `cluster-sharding-key` | Sharding key for `Distributed` engine
(expression allowed; referenced columns must be non-null integral) | (none)
| No\*\* | No | No |
+| `settings.<name>` | ClickHouse engine setting forwarded as `SETTINGS
<name>=<value>` | (none) | No
| No | No |
\* Required when `on-cluster=true` or `engine=Distributed`.
\*\* Required when `engine=Distributed`.
+\*\*\* Required when `engine=GraphiteMergeTree`.
+
+The `engine_parameters` property applies to `ReplacingMergeTree`,
`SummingMergeTree`, `CollapsingMergeTree`, and `VersionedCollapsingMergeTree`.
Values are restored when loading these tables and must be provided without
outer parentheses. For `GraphiteMergeTree`, use `graphite.config` instead.
### Table Indexes
@@ -250,6 +255,8 @@ If you need Gravitino to manage an existing cluster
database or table, recreate
On ClickHouse versions without `system.data_skipping_indices.type_full`,
Gravitino falls back to the legacy metadata query. If the legacy `type` value
does not include the bloom-filter parameters, the index type and fields are
preserved but the required parameter properties cannot be reconstructed;
provide the properties explicitly before recreating the table.
+ ClickHouse data-skipping indexes whose field expressions cannot be
represented as Gravitino field names, such as `lower(name)` or `name + 1`, are
skipped with a warning when the table is loaded and are not recreated. Direct
column references and tuples containing only column references remain supported.
+
### Partitioning, Sorting, and Distribution
- `ORDER BY`: required for MergeTree-family engines and only columns identity
are supported;
