This is an automated email from the ASF dual-hosted git repository.
roryqi 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 c10d51ab76 [MINOR] docs: Add hierarchical schema documentation and
OpenAPI (#11203)
c10d51ab76 is described below
commit c10d51ab766976e5e68af70e079c1aa90b989195
Author: roryqi <[email protected]>
AuthorDate: Mon May 25 11:50:38 2026 +0800
[MINOR] docs: Add hierarchical schema documentation and OpenAPI (#11203)
### What changes were proposed in this pull request?
Add user-facing documentation and OpenAPI for the hierarchical
(multi-level) schema feature:
- **OpenAPI** (`docs/open-api/schemas.yaml`): add the optional
`parentSchema` query parameter to `listSchemas`, and note that a schema
name may encode a nested path joined by the configured separator.
- **Server config** (`docs/gravitino-server-config.md`): new Schema
configuration subsection documenting `gravitino.schema.separator`
(default `:`, since 1.3.0).
- **Schema management guide**
(`docs/manage-relational-metadata-using-gravitino.md`):
- **Iceberg docs** (`docs/iceberg-rest-service.md`,
`docs/lakehouse-iceberg-catalog.md`):
capability notes linking to the new section.
new "Hierarchical schema" subsection with Shell/Java/Python examples for
creating nested schemas and listing children via `parentSchema`.
### Why are the changes needed?
The hierarchical schema feature (#11118 for Iceberg REST, #11175 for
Gravitino REST) was merged without user-facing documentation ("Will add
the document later"). This PR fills that gap.
### Does this PR introduce _any_ user-facing change?
Documentation only. It documents the new `gravitino.schema.separator`
server config and the new `parentSchema` query parameter on `GET
.../schemas`.
### How was this patch tested?
`./gradlew :docs:build` passes (the OpenAPI spec validates).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 <[email protected]>
---
docs/gravitino-server-config.md | 6 +++
docs/iceberg-rest-service.md | 1 +
docs/lakehouse-iceberg-catalog.md | 89 +++++++++++++++++++++++++++++++++++++++
docs/open-api/schemas.yaml | 24 ++++++++++-
4 files changed, 119 insertions(+), 1 deletion(-)
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index f957514b48..65d549d0a5 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -146,6 +146,12 @@ Gravitino server uses tree lock to ensure the consistency
of the data. The tree
| `gravitino.catalog.cache.evictionIntervalMs` | The interval in milliseconds
to evict the catalog cache; default 3600000ms(1h).
| `3600000` | No | 0.1.0 |
| `gravitino.catalog.classloader.isolated` | Whether to use an isolated
classloader for catalog. If `true`, an isolated classloader loads all
catalog-related libraries and configurations, not the AppClassLoader. The
default value is `true`. | `true` | No | 0.1.0 |
+### Schema configuration
+
+| Configuration item | Description
| Default value | Required | Since version |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|----------|---------------|
+| `gravitino.schema.separator` | The separator used to represent a
hierarchical (multi-level) schema in schema names at the API boundary, e.g. `:`
for `A:B:C`. It only takes effect for catalogs that support hierarchical
schemas (currently the Iceberg catalog). The value must not be blank and must
not contain `.` or the internal physical separator (ASCII-1, `\u0001`). See
[Hierarchical schema](./lakehouse-iceberg-catalog.md#hierarchical-schema). |
`:` | No | 1.3.0 |
+
### Auxiliary service configuration
| Configuration item | Description
| Default value | Since Version |
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index 9844bc7c69..03289cbee8 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -23,6 +23,7 @@ There are some key difference between Gravitino Iceberg REST
server and Gravitin
- multi table transaction
- pagination
- register view
+- Supports hierarchical (multi-level) namespaces.
- Works as a catalog proxy, supporting `Hive` and `JDBC` as catalog backend.
- Supports credential vending for `S3`、`GCS`、`OSS` and `ADLS`.
- Supports different storages like `S3`, `HDFS`, `OSS`, `GCS`, `ADLS` and
provides the capability to support other storages.
diff --git a/docs/lakehouse-iceberg-catalog.md
b/docs/lakehouse-iceberg-catalog.md
index 28c500f29d..adf142e74a 100644
--- a/docs/lakehouse-iceberg-catalog.md
+++ b/docs/lakehouse-iceberg-catalog.md
@@ -235,6 +235,7 @@ Please refer to [Manage Relational Metadata Using
Gravitino](./manage-relational
### Schema capabilities
- doesn't support cascade drop schema.
+- supports hierarchical (multi-level) schemas, mapping each level to an
Iceberg namespace level. See [Hierarchical schema](#hierarchical-schema).
### Schema properties
@@ -244,6 +245,94 @@ You could put properties except `comment`.
Please refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metadata-using-gravitino.md#schema-operations)
for more details.
+### Hierarchical schema
+
+The Iceberg catalog supports a hierarchical (multi-level) schema, where a
schema can be nested under
+another schema, mapping each level to an Iceberg multi-level namespace.
+
+A hierarchical schema name is a path whose levels are joined by the configured
separator
+`gravitino.schema.separator` (default `:`, see [Gravitino server
configuration](./gravitino-server-config.md#schema-configuration)).
+For example, with the default separator the name `a:b:c` denotes a schema `c`
nested under `a:b`,
+which in turn is nested under `a`. The separator is only used at the API
boundary; Gravitino stores
+the name internally using a physical separator that never collides with user
input.
+
+To create a hierarchical schema, just supply its full hierarchical name. Any
missing ancestor schemas are
+created automatically, so creating `a:b:c` also creates `a` and `a:b` if they
don't already exist.
+The following example creates the schema `a:b:c`:
+
+<Tabs groupId="language" queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "name": "a:b:c",
+ "comment": "a hierarchical schema",
+ "properties": {}
+}'
http://localhost:8090/api/metalakes/metalake/catalogs/iceberg_catalog/schemas
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+
+SupportsSchemas supportsSchemas = catalog.asSchemas();
+// missing ancestors `a` and `a:b` are created automatically
+Schema schema = supportsSchemas.createSchema("a:b:c", "a hierarchical schema",
Collections.emptyMap());
+```
+
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+gravitino_client: GravitinoClient =
GravitinoClient(uri="http://127.0.0.1:8090";, metalake_name="metalake")
+catalog: Catalog = gravitino_client.load_catalog(name="iceberg_catalog")
+# missing ancestors `a` and `a:b` are created automatically
+catalog.as_schemas().create_schema(name="a:b:c", comment="a hierarchical
schema", properties={})
+```
+
+</TabItem>
+</Tabs>
+
+To list the schemas directly under a parent schema, pass the parent schema
name. Over REST this is
+the optional `parentSchema` query parameter; in the clients it is an argument
to the list-schemas
+method. Given the schemas `a`, `a:b` and `a:b:c`, listing the children of
`a:b` returns `[a:b:c]`.
+When the parent is omitted, only the top-level schemas under the catalog are
returned (the direct
+children of the catalog root, e.g. `a`), not the nested ones.
+
+<Tabs groupId="language" queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" \
+"http://localhost:8090/api/metalakes/metalake/catalogs/iceberg_catalog/schemas?parentSchema=a:b";
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+SupportsSchemas supportsSchemas = catalog.asSchemas();
+String[] children = supportsSchemas.listSchemas("a:b");
+```
+
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+gravitino_client: GravitinoClient =
GravitinoClient(uri="http://127.0.0.1:8090";, metalake_name="metalake")
+catalog: Catalog = gravitino_client.load_catalog(name="iceberg_catalog")
+children: List[str] = catalog.as_schemas().list_schemas(parent_schema="a:b")
+```
+
+</TabItem>
+</Tabs>
+
## Table
### Table capabilities
diff --git a/docs/open-api/schemas.yaml b/docs/open-api/schemas.yaml
index b6fed43992..06f90f5056 100644
--- a/docs/open-api/schemas.yaml
+++ b/docs/open-api/schemas.yaml
@@ -29,6 +29,8 @@ paths:
- schema
summary: List schemas
operationId: listSchemas
+ parameters:
+ - $ref: "#/components/parameters/parentSchema"
responses:
"200":
$ref: "./openapi.yaml#/components/responses/EntityListResponse"
@@ -151,6 +153,22 @@ paths:
components:
+ parameters:
+ parentSchema:
+ name: parentSchema
+ in: query
+ description: >
+ The parent schema whose direct child schemas are listed. Only
meaningful for catalogs that
+ support hierarchical (multi-level) schemas, such as an Iceberg catalog
accessed through the
+ Gravitino REST server with a configured schema separator
(`gravitino.schema.separator`,
+ default `:`). For example, when the schemas `a`, `a:b` and `a:b:c`
exist, listing with
+ `parentSchema=a:b` returns `[a:b:c]`. When omitted, only the top-level
schemas under the
+ catalog are returned (the direct children of the catalog root, e.g.
`a`), not the nested
+ ones.
+ required: false
+ schema:
+ type: string
+
schemas:
SchemaCreateRequest:
@@ -160,7 +178,11 @@ components:
properties:
name:
type: string
- description: The name of the schema
+ description: >
+ The name of the schema. For catalogs that support hierarchical
(multi-level) schemas,
+ the name may encode a nested path joined by the configured schema
separator
+ (`gravitino.schema.separator`, default `:`), e.g. `a:b:c` creates
schema `c` under the
+ existing parent schema `a:b`.
comment:
type: string
description: A comment describing the schema
