This is an automated email from the ASF dual-hosted git repository.
jerryshao 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 297f69eb2d [#11005] docs(view): improve view management documentation
(#11129)
297f69eb2d is described below
commit 297f69eb2dc510ee2f216bd5a6358a65c556e38e
Author: mchades <[email protected]>
AuthorDate: Wed May 20 20:02:40 2026 +0800
[#11005] docs(view): improve view management documentation (#11129)
### What changes were proposed in this pull request?
This PR improves the user documentation for view management in
Gravitino.
The changes include:
- Add a dedicated view management guide.
- Clarify supported capabilities and interoperability.
- Update related documentation links.
### Why are the changes needed?
Issue #11005 asks for user documentation for table view management.
A dedicated view document makes the feature easier to discover and
maintain, and avoids overloading the relational metadata guide. The
updated content also clarifies an important behavior of the feature:
views created through Gravitino are persisted as native views in the
underlying catalog, while existing native views in supported catalogs
can be discovered and loaded through Gravitino without an extra import
step.
Fix: #11005
### Does this PR introduce _any_ user-facing change?
Yes.
- Adds a dedicated user documentation page for view management.
- Clarifies supported view capabilities for Hive and Iceberg catalogs.
- Documents view interoperability with underlying catalogs.
- No user-facing API or configuration key changes.
### How was this patch tested?
- `./gradlew :docs:build`
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Claude Opus 4.7 <[email protected]>
---
docs/apache-hive-catalog.md | 14 +
docs/index.md | 2 +
docs/lakehouse-iceberg-catalog.md | 12 +
docs/lakehouse-paimon-catalog.md | 14 +
docs/manage-relational-metadata-using-gravitino.md | 9 +-
docs/manage-view-metadata-using-gravitino.md | 288 +++++++++++++++++++++
6 files changed, 338 insertions(+), 1 deletion(-)
diff --git a/docs/apache-hive-catalog.md b/docs/apache-hive-catalog.md
index 14facc6760..89ed09c1a3 100644
--- a/docs/apache-hive-catalog.md
+++ b/docs/apache-hive-catalog.md
@@ -208,6 +208,20 @@ As Gravitino has a separate interface for updating the
comment of a table, the H
Support for altering partitions is under development.
:::
+## View
+
+### View capabilities
+
+- Supports list, create, load, alter, and drop for views stored in the Hive
Metastore Service as `VIRTUAL_VIEW`.
+- Each view must contain exactly one SQL representation.
+- Supports the `hive`, `trino`, and `spark` dialects.
+- When loading an existing HMS view, Gravitino automatically detects whether
the view uses the `hive`, `trino`, or `spark` dialect.
+- For the `hive` dialect, `defaultCatalog` and `defaultSchema` must be `null`.
+
+### View operations
+
+Refer to [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md) for more details.
+
## Hive catalog with S3 storage
To create a Hive catalog with S3 storage, you can refer to the [Hive catalog
with S3](./hive-catalog-with-s3.md) documentation. No special configurations
are required for the Hive catalog to work with S3 storage.
diff --git a/docs/index.md b/docs/index.md
index 70320cb19f..bd48ce4924 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -55,6 +55,8 @@ You can use either to manage metadata. See
metalakes.
* [Manage relational metadata using
Gravitino](./manage-relational-metadata-using-gravitino.md)
to learn how to manage relational metadata.
+* [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md)
+ to learn how to manage view metadata.
* [Manage fileset metadata using
Gravitino](./manage-fileset-metadata-using-gravitino.md) to learn
how to manage fileset metadata.
* [Manage messaging metadata using
Gravitino](./manage-messaging-metadata-using-gravitino.md) to learn how to
manage
diff --git a/docs/lakehouse-iceberg-catalog.md
b/docs/lakehouse-iceberg-catalog.md
index dfd476d7bf..252fd7d34f 100644
--- a/docs/lakehouse-iceberg-catalog.md
+++ b/docs/lakehouse-iceberg-catalog.md
@@ -377,6 +377,18 @@ The default column position is `LAST` when you add a
column. If you add a non nu
If you update a nullability column to non nullability, there may be
compatibility issues.
:::
+## View
+
+### View capabilities
+
+- Supports list, create, load, alter, and drop for views managed by the
underlying Iceberg REST, JDBC, or Hive backend.
+- Supports dialects such as `trino`, `spark`, and `hive`.
+- Can preserve multiple SQL representations for the same logical view.
+
+### View operations
+
+Refer to [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md) for more details.
+
## HDFS configuration
You can place `core-site.xml` and `hdfs-site.xml` in the
`catalogs/lakehouse-iceberg/conf` directory to automatically load as the
default HDFS configuration.
diff --git a/docs/lakehouse-paimon-catalog.md b/docs/lakehouse-paimon-catalog.md
index 3c15486f41..3de913e2c5 100644
--- a/docs/lakehouse-paimon-catalog.md
+++ b/docs/lakehouse-paimon-catalog.md
@@ -232,6 +232,20 @@ Bucket settings are defined via Gravitino table
distribution (HASH strategy). Th
Please refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metadata-using-gravitino.md#table-operations)
for more details.
+## View
+
+### View capabilities
+
+- Supports list, create, load, alter, and drop for views stored in the Paimon
catalog.
+- Each view must include exactly one SQL representation with dialect `query`,
which serves as the canonical view definition.
+- Additional dialect-specific SQL representations (for example, `spark` or
`trino`) can be provided alongside the required `query` representation.
+- The `defaultCatalog` and `defaultSchema` fields are stored as Paimon view
options and can be used to resolve unqualified identifiers in the SQL text.
+- View support depends on the selected Paimon backend and requires backend
view API support.
+
+### View operations
+
+Refer to [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md) for more details.
+
## HDFS configuration
You can place `core-site.xml` and `hdfs-site.xml` in the
`catalogs/lakehouse-paimon/conf` directory to automatically load as the default
HDFS configuration.
diff --git a/docs/manage-relational-metadata-using-gravitino.md
b/docs/manage-relational-metadata-using-gravitino.md
index af014aa52c..ed82918449 100644
--- a/docs/manage-relational-metadata-using-gravitino.md
+++ b/docs/manage-relational-metadata-using-gravitino.md
@@ -10,9 +10,11 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This page introduces how to manage relational metadata by Apache Gravitino,
relational metadata refers
-to relational catalog, schema, table and partitions. Through Gravitino, you
can create, edit, and
+to relational catalog, schema, table, partitions, and views. Through
Gravitino, you can create, edit, and
delete relational metadata via unified REST APIs or Java client.
+For dedicated view examples and APIs, see [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md).
+
In this document, Gravitino uses Apache Hive catalog as an example to show how
to manage
relational metadata by Gravitino. Other relational catalogs are similar to
Hive catalog,
but they may have some differences, especially in catalog property, table
property, and column type.
@@ -1229,3 +1231,8 @@ NameIdentifier[] identifiers =
</TabItem>
</Tabs>
+
+## View operations
+
+View metadata is documented separately in [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md),
+including create, load, alter, drop, and list examples for the REST API and
Java client.
diff --git a/docs/manage-view-metadata-using-gravitino.md
b/docs/manage-view-metadata-using-gravitino.md
new file mode 100644
index 0000000000..5df3a635c4
--- /dev/null
+++ b/docs/manage-view-metadata-using-gravitino.md
@@ -0,0 +1,288 @@
+---
+title: "Manage view metadata using Apache Gravitino"
+slug: /manage-view-metadata-using-gravitino
+date: 2026-5-17
+keyword: Gravitino view metadata manage
+license: This software is licensed under the Apache License version 2.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page introduces how to manage view metadata by Apache Gravitino. A view
stores a logical
+query definition rather than physical data. Through Gravitino, you can create,
load, alter,
+drop, and list views in supported catalogs via unified REST APIs or the Java
client.
+
+When a catalog implements view management, Gravitino operates on the
provider's native view
+metadata rather than a separate Gravitino-only view type. View capabilities
are implemented by
+each catalog provider and may differ in operation coverage and SQL dialect
behavior. For detailed
+support, see:
+
+- [Hive view capabilities](./apache-hive-catalog.md#view-capabilities)
+- [Iceberg view capabilities](./lakehouse-iceberg-catalog.md#view-capabilities)
+- [Paimon view capabilities](./lakehouse-paimon-catalog.md#view-capabilities)
+
+Unlike tables, views define query output and one or more representations, but
do not manage
+partitions, sort orders, indexes, or physical storage locations. The
representation model is
+extensible, but currently only SQL representations are supported.
+
+To use view management, please make sure that:
+
+ - Gravitino server has started, and the host and port are
[http://localhost:8090](http://localhost:8090).
+ - A metalake has been created and
[enabled](./manage-metalake-using-gravitino.md#enable-a-metalake).
+ - A relational catalog has been created within the metalake.
+ - A schema has been created within the catalog.
+
+## View operations
+
+:::tip
+Users should create a metalake, a catalog, and a schema, and ensure that the
metalake and
+catalog are enabled before operating views.
+:::
+
+### Create a view
+
+You can create a view by sending a `POST` request to the
+`/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views` endpoint
or just use the
+Gravitino Java client. The following is an example of creating a view:
+
+<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": "example_view",
+ "comment": "This is an example view",
+ "columns": [
+ {
+ "name": "id",
+ "type": "long",
+ "comment": "id column",
+ "nullable": true
+ }
+ ],
+ "representations": [
+ {
+ "type": "sql",
+ "dialect": "trino",
+ "sql": "SELECT id FROM example_table"
+ },
+ {
+ "type": "sql",
+ "dialect": "spark",
+ "sql": "SELECT id FROM example_table"
+ }
+ ],
+ "defaultCatalog": "iceberg_catalog",
+ "defaultSchema": "schema",
+ "properties": {
+ "key": "value"
+ }
+}'
http://localhost:8090/api/metalakes/metalake/catalogs/iceberg_catalog/schemas/schema/views
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+ViewCatalog viewCatalog = catalog.asViewCatalog();
+
+View view = viewCatalog.createView(
+ NameIdentifier.of("schema", "example_view"),
+ "This is an example view",
+ new Column[] {
+ Column.of("id", Types.LongType.get(), "id column")
+ },
+ new Representation[] {
+ SQLRepresentation.builder()
+ .withSql("SELECT id FROM example_table")
+ .withDialect("trino")
+ .build(),
+ SQLRepresentation.builder()
+ .withSql("SELECT id FROM example_table")
+ .withDialect("spark")
+ .build()
+ },
+ "iceberg_catalog",
+ "schema",
+ ImmutableMap.of("key", "value")
+);
+// ...
+```
+
+</TabItem>
+</Tabs>
+
+:::caution
+The provided example uses an Iceberg catalog and includes `trino` and `spark`
SQL
+representations for the same logical view. Supported dialects, representation
counts, and
+default-resolution fields depend on the catalog provider.
+:::
+
+#### Create request fields
+
+Use the following fields when creating a view:
+
+- `columns`: Defines the output schema of the view.
+- `representations`: Provides one or more SQL definitions. The API uses the
extensible
+ `Representation` model, but currently only the `sql` type is supported,
which maps to
+ `SQLRepresentation` in Java.
+- `defaultCatalog` and `defaultSchema`: Optionally define how unqualified
identifiers in the SQL
+ text are resolved for dialects that use them. For the `hive` dialect in Hive
catalogs, both
+ fields must be `null`.
+- `properties`: Carries provider-specific metadata.
+
+Column types use the same Gravitino type system as table columns. For the full
type list and the
+behavior of special types such as external and unparsed types, refer to
[Apache Gravitino table column
type](./manage-relational-metadata-using-gravitino.md#apache-gravitino-table-column-type).
+
+### Load a view
+
+You can load a view by sending a `GET` request to the
+`/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views/{view}`
endpoint or just use
+the Gravitino Java client. The following is an example of loading a view:
+
+<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/schema/views/example_view
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+ViewCatalog viewCatalog = catalog.asViewCatalog();
+View view = viewCatalog.loadView(NameIdentifier.of("schema", "example_view"));
+// ...
+```
+
+</TabItem>
+</Tabs>
+
+:::note
+- Loading a view returns the metadata exposed by the underlying catalog,
including output columns,
+stored representations, default catalog, default schema, comment, and
properties.
+- If the provider already exposes a native view through its metadata API,
Gravitino can load it
+directly without a separate import step.
+:::
+
+### Alter a view
+
+You can modify a view by sending a `PUT` request to the
+`/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views/{view}`
endpoint or just use
+the Gravitino Java client. The following is an example of modifying a view:
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "updates": [
+ {
+ "@type": "rename",
+ "newName": "new_view_name"
+ }
+ ]
+}'
http://localhost:8090/api/metalakes/metalake/catalogs/iceberg_catalog/schemas/schema/views/example_view
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+ViewCatalog viewCatalog = catalog.asViewCatalog();
+View view = viewCatalog.alterView(
+ NameIdentifier.of("schema", "example_view"),
+ ViewChange.rename("new_view_name"),
+ ViewChange.setProperty("key", "value")
+);
+// ...
+```
+
+</TabItem>
+</Tabs>
+
+Currently, Gravitino supports the following changes to a view:
+
+| Supported modification | REST / JSON
| Java
|
+|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| Rename view |
`{"@type":"rename","newName":"new_view_name"}`
| `ViewChange.rename("new_view_name")`
|
+| Set a view property |
`{"@type":"setProperty","property":"key","value":"value"}`
| `ViewChange.setProperty("key", "value")`
|
+| Remove a view property |
`{"@type":"removeProperty","property":"key"}`
| `ViewChange.removeProperty("key")`
|
+| Replace view definition (columns/representations/etc.) | Replace columns,
representations, default catalog, default schema, and comment in one update
request. | `ViewChange.replaceView(columns, representations,
defaultCatalog, defaultSchema, comment)` |
+
+`ViewChange.replaceView(...)` performs a full replacement of the view body. If
you only want to
+change one part of the body, load the current view first and pass the
unchanged fields back in the
+replacement request.
+
+### Drop a view
+
+You can remove a view by sending a `DELETE` request to the
+`/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views/{view}`
endpoint or just use
+the Gravitino Java client. The following is an example of dropping a view:
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" \
+http://localhost:8090/api/metalakes/metalake/catalogs/iceberg_catalog/schemas/schema/views/example_view
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+ViewCatalog viewCatalog = catalog.asViewCatalog();
+viewCatalog.dropView(NameIdentifier.of("schema", "example_view"));
+// ...
+```
+
+</TabItem>
+</Tabs>
+
+Dropping a view removes the view metadata definition only. It does not remove
underlying table
+data because a view does not own storage.
+
+### List all views under a schema
+
+You can list all views in a schema by sending a `GET` request to the
+`/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views` endpoint
or just use the
+Gravitino Java client. The following is an example of listing all the views in
a schema:
+
+<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/schema/views
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+// Assuming you have just created an Iceberg catalog named `iceberg_catalog`
+Catalog catalog = gravitinoClient.loadCatalog("iceberg_catalog");
+ViewCatalog viewCatalog = catalog.asViewCatalog();
+NameIdentifier[] identifiers = viewCatalog.listViews(Namespace.of("schema"));
+// ...
+```
+
+</TabItem>
+</Tabs>
\ No newline at end of file
