This is an automated email from the ASF dual-hosted git repository.
jshao 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 daaf252671 [MINOR]: doc(iceberg): add warehouse document for REST
catalog backend for Iceberg (#9811)
daaf252671 is described below
commit daaf252671df02fe43c65b91d89411375840b430
Author: FANNG <[email protected]>
AuthorDate: Thu Jan 29 02:04:48 2026 +0900
[MINOR]: doc(iceberg): add warehouse document for REST catalog backend for
Iceberg (#9811)
### 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
---
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
+:::
