This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch branch-1.3
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-1.3 by this push:
new dd6b053835 [Cherry-pick to branch-1.3] [#11640] docs: Improve view
support documentation for catalogs and connectors (#11641) (#11691)
dd6b053835 is described below
commit dd6b05383587501f1a93d6eefeb534da452c5da1
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Wed Jun 17 09:45:00 2026 +0800
[Cherry-pick to branch-1.3] [#11640] docs: Improve view support
documentation for catalogs and connectors (#11641) (#11691)
**Cherry-pick Information:**
- Original commit: c66f0d43fa2593e57641ce8ac364be2b4a416dc3
- Target branch: `branch-1.3`
- Status: ✅ Clean cherry-pick (no conflicts)
Co-authored-by: Yuhui <[email protected]>
---
docs/apache-hive-catalog.md | 8 +++++---
docs/flink-connector/flink-catalog-hive.md | 26 +++++++++++++++++++++++++-
docs/flink-connector/flink-catalog-iceberg.md | 25 ++++++++++++++++++++++++-
docs/flink-connector/flink-catalog-paimon.md | 25 ++++++++++++++++++++++++-
docs/lakehouse-iceberg-catalog.md | 12 +++++++++---
docs/lakehouse-paimon-catalog.md | 8 ++++++--
docs/manage-view-metadata-using-gravitino.md | 4 ++--
docs/spark-connector/spark-catalog-hive.md | 17 +++++++++++++++--
8 files changed, 110 insertions(+), 15 deletions(-)
diff --git a/docs/apache-hive-catalog.md b/docs/apache-hive-catalog.md
index 8bef06cf60..8b509ab445 100644
--- a/docs/apache-hive-catalog.md
+++ b/docs/apache-hive-catalog.md
@@ -237,9 +237,11 @@ Support for altering partitions is under development.
- 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`.
+- Supports creating views with the `hive`, `flink`, or `spark` dialect.
+- When loading an existing HMS view, Gravitino automatically detects whether
the view uses the `hive`, `flink`, `spark`, or `trino` dialect.
+- For the `hive` and `flink` dialects, `defaultCatalog` and `defaultSchema`
must be `null`.
+- The `flink` dialect requires at least one view property with the prefix
`flink.` to be set. The Flink connector automatically sets
`flink.schema.num-columns`; when using the REST API directly, set at least one
`flink.*` property explicitly.
+- The `spark` dialect requires the view property `spark.sql.create.version` to
be set; without it the view round-trips as the `hive` dialect on reload.
### View Operations
diff --git a/docs/flink-connector/flink-catalog-hive.md
b/docs/flink-connector/flink-catalog-hive.md
index 2be6074628..9ba41f4c81 100644
--- a/docs/flink-connector/flink-catalog-hive.md
+++ b/docs/flink-connector/flink-catalog-hive.md
@@ -15,7 +15,6 @@ Supports most DDL and DML operations in Flink SQL, except
such operations:
- Function operations
- Partition operations
-- View operations
- Querying UDF
- `LOAD` clause
- `UNLOAD` clause
@@ -99,6 +98,31 @@ INSERT INTO employees VALUES (1, 'John Doe', 20240101), (2,
'Jane Smith', 202401
SELECT * FROM employees WHERE dt = 20240101;
```
+## View
+
+### View Capabilities
+
+- Supports `CREATE VIEW`, `DROP VIEW`, `ALTER VIEW` (rename and replace view
definition), list, load, and rename views stored in the Hive Metastore Service.
+- When creating a view, the connector stores the SQL with the `flink` dialect
and automatically records the `flink.schema.num-columns` property, which acts
as the dialect marker required by the Hive catalog.
+- When loading a view, the connector tries the `flink` dialect first, then
falls back to the `hive` dialect.
+- Views created by other engines (e.g. Spark) with a different dialect marker
are visible in `SHOW VIEWS` but cannot be loaded by the Flink connector.
+- `defaultCatalog` and `defaultSchema` are always stored as `null` for
Flink-created views.
+
+### View SQL Example
+
+```sql
+USE CATALOG hive_a;
+USE mydatabase;
+
+CREATE VIEW employee_view AS SELECT id, name FROM employees WHERE dt =
20240101;
+
+SHOW VIEWS;
+
+SELECT * FROM employee_view;
+
+DROP VIEW employee_view;
+```
+
## Catalog Properties
The configuration of Flink Hive Connector is the same with the original Flink
Hive connector.
diff --git a/docs/flink-connector/flink-catalog-iceberg.md
b/docs/flink-connector/flink-catalog-iceberg.md
index 42b03c7326..75e4a3772d 100644
--- a/docs/flink-connector/flink-catalog-iceberg.md
+++ b/docs/flink-connector/flink-catalog-iceberg.md
@@ -25,7 +25,6 @@ To enable the Flink connector, you must download the Iceberg
Flink runtime JAR a
### Unsupported Operations
- Partition operations
-- View operations
- Metadata tables, like:
- `{iceberg_catalog}.{iceberg_database}.{iceberg_table}&snapshots`
- Query UDF
@@ -77,6 +76,30 @@ SELECT * FROM sample WHERE data = 'B';
```
+## View
+
+### View Capabilities
+
+- Supports `CREATE VIEW`, `DROP VIEW`, `ALTER VIEW` (rename and replace view
definition), list, load, and rename views managed by the underlying Iceberg
backend.
+- When creating a view, the connector stores the SQL with the `flink` dialect.
+- When loading a view, the connector tries the `flink` dialect first, then
falls back to the `hive` dialect.
+- Multiple SQL representations per view (e.g. also a `spark` dialect) can
coexist and are preserved through Gravitino.
+
+### View SQL Example
+
+```sql
+USE CATALOG iceberg_a;
+USE mydb;
+
+CREATE VIEW order_view AS SELECT id, amount FROM orders WHERE status =
'completed';
+
+SHOW VIEWS;
+
+SELECT * FROM order_view;
+
+DROP VIEW order_view;
+```
+
## Catalog Properties
The Gravitino Flink connector transforms the following properties in a catalog
to Flink connector configuration.
diff --git a/docs/flink-connector/flink-catalog-paimon.md
b/docs/flink-connector/flink-catalog-paimon.md
index 4f46cd081f..a643747971 100644
--- a/docs/flink-connector/flink-catalog-paimon.md
+++ b/docs/flink-connector/flink-catalog-paimon.md
@@ -28,7 +28,6 @@ Supports most DDL and DML operations in Flink SQL, except
such operations:
- Function operations
- Partition operations
-- View operations
- Querying UDF
- `LOAD` clause
- `UNLOAD` clause
@@ -126,6 +125,30 @@ CREATE TABLE paimon_bucketed_table (
);
```
+## View
+
+### View Capabilities
+
+- Supports `CREATE VIEW`, `DROP VIEW`, `ALTER VIEW` (rename and replace view
definition), list, load, and rename views stored in the Paimon catalog.
+- When creating a view, the connector stores two SQL representations: one with
the `flink` dialect and one with the `query` dialect (Paimon's canonical
dialect), both using the same expanded SQL text.
+- When loading a view, the connector tries dialects in order: `flink` → `hive`
→ `query`. The first available representation wins.
+- View support depends on the selected Paimon backend; not all backends
implement the Paimon view API.
+
+### View SQL Example
+
+```sql
+USE CATALOG paimon_a;
+USE mydb;
+
+CREATE VIEW summary_view AS SELECT category, SUM(amount) AS total FROM orders
GROUP BY category;
+
+SHOW VIEWS;
+
+SELECT * FROM summary_view;
+
+DROP VIEW summary_view;
+```
+
## Catalog Properties
Gravitino Flink connector will transform below property names which are
defined in catalog properties to Flink Paimon connector configuration.
diff --git a/docs/lakehouse-iceberg-catalog.md
b/docs/lakehouse-iceberg-catalog.md
index 93981824f9..68931a3672 100644
--- a/docs/lakehouse-iceberg-catalog.md
+++ b/docs/lakehouse-iceberg-catalog.md
@@ -494,9 +494,15 @@ If you update a nullability column to non nullability,
there may be compatibilit
### 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.
+- Supports list, create, load, alter, and drop for views managed by the
underlying Iceberg backend.
+- Accepts any dialect name (e.g. `trino`, `spark`, `flink`, `hive`). No
restriction on which dialects are used.
+- Can preserve multiple SQL representations for the same logical view; the
full set of representations round-trips through Gravitino.
+- `defaultCatalog` and `defaultSchema` are stored and returned as-is by the
backend.
+- View support depends on the Iceberg catalog backend: REST and Hive backends
generally support views; JDBC backend support is in continuous validation.
+
+:::note
+Rename cannot be combined with other changes in a single `alterView` call.
Submit rename as a standalone request.
+:::
### View Operations
diff --git a/docs/lakehouse-paimon-catalog.md b/docs/lakehouse-paimon-catalog.md
index 329330f3e2..fed8d2a2e1 100644
--- a/docs/lakehouse-paimon-catalog.md
+++ b/docs/lakehouse-paimon-catalog.md
@@ -237,11 +237,15 @@ Refer to [Manage Relational Metadata Using
Gravitino](./manage-relational-metada
### 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.
+- Each view must include exactly one SQL representation with dialect `query`,
which serves as the canonical view definition. At most one representation per
dialect is allowed.
+- Additional dialect-specific SQL representations (for example, `flink`,
`spark`) 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.
+:::note
+Rename cannot be combined with other changes in a single `alterView` call.
Submit rename as a standalone request.
+:::
+
### View Operations
Refer to [Manage view metadata using
Gravitino](./manage-view-metadata-using-gravitino.md) for more details.
diff --git a/docs/manage-view-metadata-using-gravitino.md
b/docs/manage-view-metadata-using-gravitino.md
index 034334e982..0c4e0a37fc 100644
--- a/docs/manage-view-metadata-using-gravitino.md
+++ b/docs/manage-view-metadata-using-gravitino.md
@@ -133,8 +133,8 @@ Use the following fields when creating a view:
`Representation` model, but 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`.
+ text are resolved for dialects that use them. For the `hive` and `flink`
dialects 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
diff --git a/docs/spark-connector/spark-catalog-hive.md
b/docs/spark-connector/spark-catalog-hive.md
index 74df514c70..ccc6c991b6 100644
--- a/docs/spark-connector/spark-catalog-hive.md
+++ b/docs/spark-connector/spark-catalog-hive.md
@@ -15,10 +15,10 @@ Supports most DDL and DML operations in SparkSQL, except
such operations:
- Function operations (Gravitino UDFs are supported, see [Spark connector -
User-defined functions](spark-connector-udf.md))
- Partition operations
-- View operations
+- View DDL operations (`CREATE VIEW`, `DROP VIEW`, `ALTER VIEW`)
- `LOAD` clause
- `CREATE TABLE LIKE` clause
-- `TRUCATE TABLE` clause
+- `TRUNCATE TABLE` clause
:::info
@@ -58,6 +58,19 @@ SELECT * FROM employees WHERE department = 'Engineering';
```
+## View
+
+Spark DDL view operations (`CREATE VIEW`, `DROP VIEW`, `ALTER VIEW`) are not
supported. However, existing views stored in the Hive Metastore can be read
with `SELECT`. When `SELECT` references a view name, the connector loads the
view's SQL definition from Gravitino, resolves the query, and executes it.
+
+:::caution
+The current implementation materializes all view results on the Spark driver
using `LocalScan`. This is suitable only for small or bounded views. Querying a
large or unbounded view may exhaust driver memory and cause an OOM error.
+:::
+
+```sql
+-- Assumes a view was created via Gravitino API, Flink, or Hive directly
+SELECT * FROM employee_view;
+```
+
## Catalog Properties
Gravitino spark connector will transform below property names which are
defined in catalog properties to Spark Hive connector configuration.
