This is an automated email from the ASF dual-hosted git repository.
yuqi4733 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 d6cb41d1f3 [#10074] docs(catalog-jdbc-hologres): Add Hologres JDBC
catalog documentation (#10069)
d6cb41d1f3 is described below
commit d6cb41d1f32af7dce7db224b7c3caa446d4dc848
Author: Ye Ding <[email protected]>
AuthorDate: Wed Mar 11 09:19:37 2026 +0800
[#10074] docs(catalog-jdbc-hologres): Add Hologres JDBC catalog
documentation (#10069)
### What changes were proposed in this pull request?
Add documentation for the Hologres JDBC catalog:
- `docs/jdbc-hologres-catalog.md`: Full documentation covering
requirements, catalog properties, schema operations, table operations,
column types, and table properties
- Updated `docs/index.md`: Added Hologres catalog entry to the
documentation index
- Updated `docs/manage-relational-metadata-using-gravitino.md`: Added
Hologres to the supported catalogs list
### Why are the changes needed?
Users need documentation to understand how to configure and use the
Hologres JDBC catalog.
Fix: https://github.com/apache/gravitino/issues/10074
### Does this PR introduce _any_ user-facing change?
Yes. Adds new user-facing documentation for the Hologres JDBC catalog.
### How was this patch tested?
Documentation review. No code changes.
---
docs/index.md | 2 +
docs/jdbc-hologres-catalog.md | 274 +++++++++++++++++++++
docs/manage-relational-metadata-using-gravitino.md | 10 +-
docs/webui.md | 14 +-
4 files changed, 297 insertions(+), 3 deletions(-)
diff --git a/docs/index.md b/docs/index.md
index d07e892512..d0c02e174a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -79,6 +79,7 @@ Gravitino currently supports the following catalogs:
**Relational catalogs:**
* [**Doris catalog**](./jdbc-doris-catalog.md)
+* [**Hologres catalog**](./jdbc-hologres-catalog.md)
* [**Hudi catalog**](./lakehouse-hudi-catalog.md)
* [**Hive catalog**](./apache-hive-catalog.md)
* [**Iceberg catalog**](./lakehouse-iceberg-catalog.md)
@@ -132,6 +133,7 @@ complete environment. To experience all the features, see
Gravitino supports different catalogs to manage the metadata in different
sources. Please see:
* [Doris catalog](./jdbc-doris-catalog.md): a complete guide to using
Gravitino to manage Doris data.
+* [Hologres catalog](./jdbc-hologres-catalog.md): a complete guide to using
Gravitino to manage Hologres data.
* [StarRocks catalog](./jdbc-starrocks-catalog.md): a complete guide to using
Gravitino to manage StarRocks data.
* [Fileset catalog](./fileset-catalog.md): a complete guide to using Gravitino
to manage fileset
using Hadoop Compatible File System (HCFS).
diff --git a/docs/jdbc-hologres-catalog.md b/docs/jdbc-hologres-catalog.md
new file mode 100644
index 0000000000..5124bd648d
--- /dev/null
+++ b/docs/jdbc-hologres-catalog.md
@@ -0,0 +1,274 @@
+---
+title: "Hologres catalog"
+slug: /jdbc-hologres-catalog
+keywords:
+- jdbc
+- Hologres
+- metadata
+license: "This software is licensed under the Apache License version 2."
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Introduction
+
+Apache Gravitino provides the ability to manage
[Hologres](https://help.aliyun.com/zh/hologres) metadata.
+
+Hologres is a real-time data warehouse service provided by Alibaba Cloud,
designed for high-concurrency and low-latency online analytical processing
(OLAP). Hologres is fully compatible with the PostgreSQL protocol and uses the
PostgreSQL JDBC Driver for connections.
+
+:::caution
+Gravitino saves some system information in schema and table comment, like
`(From Gravitino, DO NOT EDIT: gravitino.v1.uid1078334182909406185)`, please
don't change or remove this message.
+:::
+
+## Catalog
+
+### Catalog capabilities
+
+- Gravitino catalog corresponds to a Hologres database instance.
+- Supports metadata management of Hologres.
+- Supports DDL operation for Hologres schemas and tables.
+- Supports table index (PRIMARY KEY in CREATE TABLE).
+- Supports [column default
value](./manage-relational-metadata-using-gravitino.md#table-column-default-value).
+- Supports LIST partitioning (physical and logical partition tables).
+- Supports Hologres-specific table properties via `WITH` clause (orientation,
clustering_key, distribution_key, etc.).
+- Does not support
[auto-increment](./manage-relational-metadata-using-gravitino.md#table-column-auto-increment).
+
+### Catalog properties
+
+You can pass to a Hologres data source any property that isn't defined by
Gravitino by adding `gravitino.bypass.` prefix as a catalog property. For
example, catalog property `gravitino.bypass.maxWaitMillis` will pass
`maxWaitMillis` to the data source property.
+
+Check the relevant data source configuration in [data source
properties](https://commons.apache.org/proper/commons-dbcp/configuration.html)
+
+If you use a JDBC catalog, you must provide `jdbc-url`, `jdbc-driver`,
`jdbc-database`, `jdbc-user` and `jdbc-password` to catalog properties.
+Besides the [common catalog
properties](./gravitino-server-config.md#apache-gravitino-catalog-properties-configuration),
the Hologres catalog has the following properties:
+
+| Configuration item | Description
| Default value | Required | Since Version
|
+|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|----------|------------------|
+| `jdbc-url` | JDBC URL for connecting to the database. For
example,
`jdbc:postgresql://hgprecn-cn-xxx.hologres.aliyuncs.com:80/my_database`
| (none) | Yes | 1.3.0 |
+| `jdbc-driver` | The driver of the JDBC connection. Must be
`org.postgresql.Driver`.
| (none) | Yes | 1.3.0 |
+| `jdbc-database` | The database name. This is mandatory for Hologres.
| (none) | Yes | 1.3.0 |
+| `jdbc-user` | The JDBC user name (AccessKey ID or database
username).
| (none) | Yes | 1.3.0 |
+| `jdbc-password` | The JDBC password (AccessKey Secret or database
password).
| (none) | Yes | 1.3.0 |
+| `jdbc.pool.min-size` | The minimum number of connections in the pool. `2`
by default.
| `2` | No | 1.3.0 |
+| `jdbc.pool.max-size` | The maximum number of connections in the pool.
`10` by default.
| `10` | No | 1.3.0 |
+
+:::caution
+Hologres uses the PostgreSQL JDBC Driver (version 42.3.2 or later
recommended). You need to download the PostgreSQL JDBC Driver and place it in
the `catalogs/jdbc-hologres/libs` directory under the Gravitino distribution
(e.g., `distribution/package/catalogs/jdbc-hologres/libs` or
`distribution/package-all/catalogs/jdbc-hologres/libs`).
+:::
+
+### Catalog operations
+
+Refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metadata-using-gravitino.md#catalog-operations)
for more details.
+
+## Schema
+
+### Schema capabilities
+
+- Gravitino's schema concept corresponds to the Hologres (PostgreSQL) schema.
+- Supports creating schema with comment.
+- Supports dropping schema.
+- System schemas are automatically filtered: `pg_toast`, `pg_catalog`,
`information_schema`, `hologres`, `hg_internal`, `hg_recyclebin`,
`hologres_object_table`, `hologres_sample`, `hologres_streaming_mv`,
`hologres_statistic`.
+
+### Schema properties
+
+- Doesn't support any schema property settings.
+
+### Schema operations
+
+Refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metadata-using-gravitino.md#schema-operations)
for more details.
+
+## Table
+
+### Table capabilities
+
+- Gravitino's table concept corresponds to the Hologres table.
+- Supports DDL operation for Hologres tables.
+- Supports PRIMARY KEY index in CREATE TABLE.
+- Supports [column default
value](./manage-relational-metadata-using-gravitino.md#table-column-default-value).
+- Supports expression columns via DEFAULT expressions (note: Gravitino maps
these as column default values, not as true generated/computed columns in the
Hologres sense).
+- Supports LIST partitioning (physical and logical).
+- Does not support
[auto-increment](./manage-relational-metadata-using-gravitino.md#table-column-auto-increment).
Creating auto-increment columns is rejected in both CREATE TABLE and ALTER
TABLE.
+
+### Table properties
+
+Hologres-specific table properties are set via the `WITH` clause during CREATE
TABLE and read from the `hologres.hg_table_properties` system table. The
following user-relevant properties are supported:
+
+| Property Key | Description |
Example Value |
+|-------------------------------------|-----------------------------------|--------------------------------|
+| `orientation` | Storage format |
`column`, `row`, `row,column` |
+| `clustering_key` | Clustering key columns |
`id:asc` |
+| `segment_key` | Event time column (segment key) |
`create_time` |
+| `bitmap_columns` | Bitmap index columns |
`status,category` |
+| `dictionary_encoding_columns` | Dictionary encoding columns |
`city,province` |
+| `time_to_live_in_seconds` | Data TTL setting |
`2592000` |
+| `table_group` | Table group name |
`my_table_group` |
+| `storage_format` | Internal storage format |
`orc`, `sst` |
+| `binlog_level` | Binlog level |
`replica`, `none` |
+| `binlog_ttl` | Binlog TTL |
`86400` |
+
+:::info
+- Modifying table properties via ALTER TABLE `SetProperty` / `RemoveProperty`
is not yet supported by Gravitino (Hologres natively supports property
modification via the `CALL HG_UPDATE_TABLE_PROPERTY` or rebuild commands, but
this is not yet implemented in Gravitino).
+- The properties `distribution_key`, `is_logical_partitioned_table`, and
`primary_key` are managed via their dedicated parameters (Distribution,
Partitioning, Indexes) and should not be set directly in table properties.
+:::
+
+### Table column types
+
+| Gravitino Type | Hologres Type | Notes
|
+|-----------------------------|----------------------------|----------------------------------------------------|
+| `Boolean` | `bool` |
|
+| `Short` | `int2` (SMALLINT) |
|
+| `Integer` | `int4` (INTEGER) |
|
+| `Long` | `int8` (BIGINT) |
|
+| `Float` | `float4` (REAL) |
|
+| `Double` | `float8` (DOUBLE PRECISION)|
|
+| `Decimal(p,s)` | `numeric(p,s)` |
|
+| `VarChar(n)` | `varchar(n)` | `varchar` without
length maps to `String` |
+| `FixedChar(n)` | `bpchar(n)` (CHAR) |
|
+| `String` | `text` |
|
+| `Binary` | `bytea` |
|
+| `Date` | `date` |
|
+| `Time` | `time` | With optional
precision |
+| `Timestamp` | `timestamp` | Always emitted
without precision suffix |
+| `Timestamp_tz` | `timestamptz` | Always emitted
without precision suffix |
+| `List(IntegerType, false)` | `int4[]` (`_int4`) | Array types via
`_` prefix |
+| `List(LongType, false)` | `int8[]` (`_int8`) |
|
+| `List(FloatType, false)` | `float4[]` (`_float4`) |
|
+| `List(DoubleType, false)` | `float8[]` (`_float8`) |
|
+| `List(BooleanType, false)` | `bool[]` (`_bool`) |
|
+| `List(StringType, false)` | `text[]` (`_text`) |
|
+
+:::info
+- Hologres does not support precision syntax for `TIMESTAMP`/`TIMESTAMPTZ`
(e.g., `timestamptz(6)` is invalid), so the type converter always emits the
base type without precision.
+- Array element types must be non-nullable (Hologres limitation).
Multidimensional arrays are not supported.
+- Types like `json`, `jsonb`, `uuid`, `inet`, `money`, `roaringbitmap` are
mapped to Gravitino **[External
Type](./manage-relational-metadata-using-gravitino.md#external-type)** with the
original type name preserved.
+:::
+
+### Table distribution
+
+Hologres supports HASH distribution via the `distribution_key` property in the
`WITH` clause.
+
+<Tabs groupId='language' queryString>
+<TabItem value="json" label="Json">
+
+```json
+{
+ "distribution": {
+ "strategy": "hash",
+ "number": 0,
+ "funcArgs": [
+ {
+ "type": "field",
+ "fieldName": ["id"]
+ }
+ ]
+ }
+}
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+Distribution distribution = Distributions.hash(0, NamedReference.field("id"));
+```
+
+</TabItem>
+</Tabs>
+
+### Table partitioning
+
+Hologres supports LIST partitioning with two variants:
+
+- **Physical partition tables**: `PARTITION BY LIST(column)` — supports
exactly 1 partition column.
+- **Logical partition tables** (Hologres V3.1+): `LOGICAL PARTITION BY
LIST(col1[, col2])` — supports 1–2 partition columns. Enabled by setting
property `is_logical_partitioned_table` to `true`.
+
+<Tabs groupId='language' queryString>
+<TabItem value="json" label="Json">
+
+```json
+{
+ "partitioning": [
+ {
+ "strategy": "list",
+ "fieldNames": [["ds"]]
+ }
+ ]
+}
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+Transform[] partitioning = new Transform[] {
+ Transforms.list(new String[][] {{"ds"}})
+};
+```
+
+</TabItem>
+</Tabs>
+
+:::note
+Creating partition child tables (e.g., `CREATE TABLE child PARTITION OF parent
FOR VALUES IN ('value')`) is not yet supported through Gravitino.
+:::
+
+### Table indexes
+
+- Supports PRIMARY_KEY in CREATE TABLE.
+- Adding or deleting indexes via ALTER TABLE is not yet supported by Gravitino
(Hologres natively supports index modification via rebuild commands, but this
is not yet implemented in Gravitino).
+
+<Tabs groupId='language' queryString>
+<TabItem value="json" label="Json">
+
+```json
+{
+ "indexes": [
+ {
+ "indexType": "primary_key",
+ "name": "pk_id",
+ "fieldNames": [["id"]]
+ }
+ ]
+}
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+Index[] indexes = new Index[] {
+ Indexes.of(IndexType.PRIMARY_KEY, "pk_id", new String[][]{{"id"}}),
+};
+```
+
+</TabItem>
+</Tabs>
+
+### Table operations
+
+Refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metadata-using-gravitino.md#table-operations)
for more details.
+
+#### Alter table operations
+
+Gravitino supports these table alteration operations for Hologres:
+
+- `RenameTable`
+- `UpdateComment`
+- `AddColumn` (type and comment only; NOT NULL, default value, and
auto-increment are not supported)
+- `DeleteColumn`
+- `RenameColumn`
+- `UpdateColumnComment`
+
+:::info
+The following ALTER TABLE operations are **not supported** and will throw
`IllegalArgumentException`:
+- `UpdateColumnType`
+- `UpdateColumnDefaultValue`
+- `UpdateColumnNullability`
+- `UpdateColumnPosition`
+- `UpdateColumnAutoIncrement`
+- `AddIndex`
+- `DeleteIndex`
+- `SetProperty`
+- `RemoveProperty`
+:::
diff --git a/docs/manage-relational-metadata-using-gravitino.md
b/docs/manage-relational-metadata-using-gravitino.md
index 3c5888197e..bc68a4db57 100644
--- a/docs/manage-relational-metadata-using-gravitino.md
+++ b/docs/manage-relational-metadata-using-gravitino.md
@@ -25,6 +25,7 @@ For more details, please refer to the related doc.
- [**StarRocks**](./jdbc-starrocks-catalog.md)
- [**OceanBase**](./jdbc-oceanbase-catalog.md)
- [**ClickHouse**](./jdbc-clickhouse-catalog.md)
+- [**Hologres**](./jdbc-hologres-catalog.md)
- [**Apache Iceberg**](./lakehouse-iceberg-catalog.md)
- [**Apache Paimon**](./lakehouse-paimon-catalog.md)
- [**Apache Hudi**](./lakehouse-hudi-catalog.md)
@@ -129,7 +130,8 @@ Currently, Gravitino supports the following catalog
providers:
| `jdbc-doris` | [Doris catalog
property](./jdbc-doris-catalog.md#catalog-properties) |
| `jdbc-oceanbase` | [OceanBase catalog
property](./jdbc-oceanbase-catalog.md#catalog-properties) |
| `jdbc-starrocks` | [StarRocks catalog
property](./jdbc-starrocks-catalog.md#catalog-properties) |
-| `jdbc-clickhouse` | [ClickHouse catalog
property](./jdbc-clickhouse-catalog.md#catalog-properties) |
+| `jdbc-clickhouse` | [ClickHouse catalog
property](./jdbc-clickhouse-catalog.md#catalog-properties) |
+| `jdbc-hologres` | [Hologres catalog
property](./jdbc-hologres-catalog.md#catalog-properties) |
| `lakehouse-generic` | [Lakehouse generic catalog
property](./lakehouse-generic-catalog.md#catalog-properties) |
### Load a catalog
@@ -516,6 +518,7 @@ Currently, Gravitino supports the following schema property:
| `jdbc-oceanbase` | [OceanBase schema
property](./jdbc-oceanbase-catalog.md#schema-properties) |
| `jdbc-starrocks` | [StarRocks schema
property](./jdbc-starrocks-catalog.md#schema-properties) |
| `jdbc-clickhouse` | [ClickHouse schema
property](./jdbc-clickhouse-catalog.md#schema-properties) |
+| `jdbc-hologres` | [Hologres schema
property](./jdbc-hologres-catalog.md#schema-properties) |
| `lakehouse-generic` | [Lakehouse generic schema
property](./lakehouse-generic-catalog.md#schema-properties) |
### Load a schema
@@ -997,6 +1000,7 @@ The following is a table of the column default value that
Gravitino supports for
| `jdbc-oceanbase` | ✔ |
| `jdbc-starrocks` | ✔ |
| `jdbc-clickhouse` | ✔ |
+| `jdbc-hologres` | ✔ |
| `lakehouse-generic` | ✘ |
#### Table column auto-increment
@@ -1015,7 +1019,8 @@ The following table shows the column auto-increment that
Gravitino supports for
| `jdbc-doris` | ✘
|
| `jdbc-oceanbase` |
✔([limitations](./jdbc-oceanbase-catalog.md#table-column-auto-increment))
|
| `jdbc-starrocks` | ✔
|
-| `jdbc-clickhouse` | ✘
|
+| `jdbc-clickhouse` | ✘
|
+| `jdbc-hologres` | ✘
|
| `lakehouse-generic` | ✘
|
#### Table property and type mapping
@@ -1034,6 +1039,7 @@ The following is the table property that Gravitino
supports:
| `jdbc-oceanbase` | [OceanBase table
property](./jdbc-oceanbase-catalog.md#table-properties)
| [OceanBase type
mapping](./jdbc-oceanbase-catalog.md#table-column-types)
|
| `jdbc-starrocks` | [StarRocks table
property](./jdbc-starrocks-catalog.md#table-properties)
| [StarRocks type
mapping](./jdbc-starrocks-catalog.md#table-column-types)
|
| `jdbc-clickhouse` | [ClickHouse table
property](./jdbc-clickhouse-catalog.md#table-properties)
| [ClickHouse type
mapping](./jdbc-clickhouse-catalog.md#table-column-types)
|
+| `jdbc-hologres` | [Hologres table
property](./jdbc-hologres-catalog.md#table-properties)
| [Hologres type
mapping](./jdbc-hologres-catalog.md#table-column-types)
|
| `lakehouse-generic` | Lakehouse generic table property depends on specific
table implementation, for Lance table, please refer to
[doc](./lakehouse-generic-lance-table.md#table-properties), other table format,
please refer to related docs. | Lakehouse generic type mapping. Similar to
table properties, for Lance table, please refer to
[docs](./lakehouse-generic-lance-table.md#data-type-mappings) |
#### Table partitioning, distribution, sort ordering and indexes
diff --git a/docs/webui.md b/docs/webui.md
index 88d6a0f498..c0960d792b 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -162,7 +162,7 @@ Creating a catalog requires these fields:
1. **Catalog name**(**_required_**): the name of the catalog
2. **Type**(**_required_**): `relational`/`fileset`/`messaging`/`model`, the
default value is `relational`
3. **Provider**(**_required_**):
- 1. Type `relational` -
`hive`/`iceberg`/`mysql`/`postgresql`/`doris`/`paimon`/`hudi`/`oceanbase`
+ 1. Type `relational` -
`hive`/`iceberg`/`mysql`/`postgresql`/`doris`/`paimon`/`hudi`/`oceanbase`/`hologres`
2. Type `fileset` has no provider
3. Type `messaging` - `kafka`
4. Type `model` has no provider
@@ -349,6 +349,18 @@ Creating a catalog requires these fields:
|jdbc-password|The JDBC password
|
</TabItem>
+ <TabItem value='Hologres' label='Hologres'>
+ Follow the [jdbc-hologres-catalog](./jdbc-hologres-catalog.md) document.
+
+ |Key |Description
|
+
|-------------|--------------------------------------------------------------------------------------------------|
+ |jdbc-driver |e.g. `org.postgresql.Driver`
|
+ |jdbc-url |e.g.
`jdbc:postgresql://hgprecn-cn-xxx.hologres.aliyuncs.com:80/my_database`
|
+ |jdbc-user |The JDBC user name (AccessKey ID or database username)
|
+ |jdbc-password|The JDBC password (AccessKey Secret or database password)
|
+ |jdbc-database|e.g. `my_database`
|
+
+ </TabItem>
</Tabs>
###### 2. Type `fileset`
