roryqi commented on code in PR #11203:
URL: https://github.com/apache/gravitino/pull/11203#discussion_r3289192747
##########
docs/lakehouse-iceberg-catalog.md:
##########
@@ -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 nested 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 nested 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 nested schema",
Collections.emptyMap());
Review Comment:
Renamed 3 places.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
