This is an automated email from the ASF dual-hosted git repository.
yuqi4733 pushed a commit to branch branch-1.1
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-1.1 by this push:
new 0d3a8a1f02 [MINOR]: doc(iceberg): add warehouse document for REST
catalog backend for Iceberg (#9823)
0d3a8a1f02 is described below
commit 0d3a8a1f02668afd3d5fab2d0d16c419cab0c59a
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Thu Jan 29 10:06:39 2026 +0800
[MINOR]: doc(iceberg): add warehouse document for REST catalog backend for
Iceberg (#9823)
### What changes were proposed in this pull request?
add warehouse document for REST catalog backend for Iceberg
### Why are the changes needed?
warehouse for REST catalog backend is different for other catalog
backend
### Does this PR introduce _any_ user-facing change?
no
### How was this patch tested?
just document
Co-authored-by: FANNG <[email protected]>
---
docs/lakehouse-iceberg-catalog.md | 36 +++++++++++++++++++++++++++++-------
1 file changed, 29 insertions(+), 7 deletions(-)
diff --git a/docs/lakehouse-iceberg-catalog.md
b/docs/lakehouse-iceberg-catalog.md
index 90729ecdb4..b65a003467 100644
--- a/docs/lakehouse-iceberg-catalog.md
+++ b/docs/lakehouse-iceberg-catalog.md
@@ -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.
@@ -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.
+
#### S3
Supports using static access-key-id and secret-access-key to access S3 data.
@@ -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.
-:::
\ No newline at end of file
+:::
