Skip to content

[MINOR]: doc(iceberg): add warehouse document for REST catalog backend for Iceberg #9811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jerryshao merged 4 commits into from
Jan 28, 2026
Merged

[MINOR]: doc(iceberg): add warehouse document for REST catalog backend for Iceberg #9811

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e37f0fa
add warehouse document for REST catalog backend for Iceberg
Jan 27, 2026
ef1aa10
add warehouse document for REST catalog backend for Iceberg
Jan 27, 2026
8d171d1
polish
Jan 28, 2026
c3ed472
polish
Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions docs/lakehouse-iceberg-catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@ Builds with Apache Iceberg `1.10.0`. The Apache Iceberg table format version is

### Catalog properties

| Property name | Description | Default value | Required | Since Version |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|----------|---------------|
| `catalog-backend` | Catalog backend of Gravitino Iceberg catalog. Supports `hive` or `jdbc` or `rest`. | (none) | Yes | 0.2.0 |
| `uri` | The URI configuration of the Iceberg catalog. `thrift://127.0.0.1:9083` or `jdbc:postgresql://127.0.0.1:5432/db_name` or `jdbc:mysql://127.0.0.1:3306/metastore_db` or `http://127.0.0.1:9001`. | (none) | Yes | 0.2.0 |
| `warehouse` | Warehouse directory of catalog. `file:///user/hive/warehouse-hive/` for local fs or `hdfs://namespace/hdfs/path` for HDFS. | (none) | Yes | 0.2.0 |
| `catalog-backend-name` | The catalog name passed to underlying Iceberg catalog backend. Catalog name in JDBC backend is used to isolate namespace and tables. | The property value of `catalog-backend`, like `jdbc` for JDBC catalog backend. | No | 0.5.2 |
| Property name | Description | Default value | Required | Since Version |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------------|---------------|
| `catalog-backend` | Catalog backend of Gravitino Iceberg catalog. Supports `hive` or `jdbc` or `rest`. | (none) | Yes | 0.2.0 |
| `uri` | The URI configuration of the Iceberg catalog. `thrift://127.0.0.1:9083` or `jdbc:postgresql://127.0.0.1:5432/db_name` or `jdbc:mysql://127.0.0.1:3306/metastore_db` or `http://127.0.0.1:9001/iceberg`. | (none) | Yes | 0.2.0 |
| `warehouse` | Warehouse location of catalog. Use a physical S3 or HDFS location for `hive` or `jdbc` catalog backend, use catalog name for REST catalog backend. | (none) | Yes for `hive` and `jdbc` catalog backend | 0.2.0 |
| `catalog-backend-name` | The catalog name passed to underlying Iceberg catalog backend. Catalog name in JDBC backend is used to isolate namespace and tables. | The property value of `catalog-backend`, like `jdbc` for JDBC catalog backend. | No | 0.5.2 |


Any property not defined by Gravitino with `gravitino.bypass.` prefix will pass to Iceberg catalog properties and HDFS configuration. For example, if specify `gravitino.bypass.list-all-tables`, `list-all-tables` will pass to Iceberg catalog properties.
Expand Down Expand Up @@ -67,6 +67,28 @@ You must download the corresponding JDBC driver and place it to the `catalogs/la
If you are using multiple JDBC catalog backends, setting `jdbc-initialize` to true may not take effect for RDMS like `Mysql`, you should create Iceberg meta tables explicitly.
:::

#### REST catalog backend

For the REST catalog backend, `warehouse` identifies the catalog in the Iceberg REST spec. In the Gravitino Iceberg REST server, `warehouse` maps to the catalog name. An empty value means the default catalog.

Example: create an Iceberg catalog with the REST backend. This targets the default catalog and uses a REST path like `http://127.0.0.1:9001/iceberg/v1/namespaces/db/tables/table`.

```shell
curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
-d '{
"name": "iceberg_rest",
"type": "RELATIONAL",
"comment": "Iceberg REST catalog",
"provider": "lakehouse-iceberg",
"properties": {
"catalog-backend": "rest",
"uri": "http://localhost:9001/iceberg"
}
}' http://localhost:8090/api/metalakes/metalake/catalogs
```

To access a non-default catalog, set `warehouse` to the catalog name. This uses a REST path like `http://127.0.0.1:9001/iceberg/v1/catalog/namespaces/db/tables/table`. See [Multi catalog](./iceberg-rest-service.md#multiple-catalog-backend-support) for details.

@jerryshao jerryshao Jan 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please give an example?

@FANNG1 FANNG1 Jan 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated

#### S3

Supports using static access-key-id and secret-access-key to access S3 data.
Expand Down Expand Up @@ -352,4 +374,4 @@ You can place `core-site.xml` and `hdfs-site.xml` in the `catalogs/lakehouse-ice
:::info
Builds with Hadoop 2.10.x, there may be compatibility issues when accessing Hadoop 3.x clusters.
When writing to HDFS, the Gravitino Iceberg REST server can only operate as the specified HDFS user and doesn't support proxying to other HDFS users. See [How to access Apache Hadoop](gravitino-server-config.md) for more details.
:::
:::