Skip to main content

Tables and views

Overview​

A table is the object a relational catalog holds, and a view is a stored query over one or more tables. Both live in a schema, and both are reached the same way no matter which system stores them.

Gravitino does not hold a copy of either. A table registered through a Hive, Iceberg, MySQL, or Paimon catalog stays in that system, and Gravitino keeps the reference plus anything attached to it. Creating a table through Gravitino creates it in the source system, and listing tables asks the source at request time, so a table created directly in Hive appears the next time Gravitino is asked.

What Gravitino adds is a single shape across all of them. The same call describes a Hive table and an Iceberg table, columns carry the same type system, and tags, policies, ownership, and statistics attach the same way regardless of the system underneath.

Quick start​

  1. Open a catalog. Tables live in a schema inside a relational catalog. See Catalogs and Schemas for connecting one.

  2. Browse or create. A connected catalog surfaces the tables already there. Creating a table through Gravitino creates it in the source system, with the columns, partitioning, and properties you specify.

  3. Classify what matters. Tables and their columns both carry tags and policies, which is how a classification set once reaches every engine that reads through Gravitino.

The table model​

Columns​

A column has a name and a type, and can carry a comment, nullability, an auto-increment flag, and a default value. Types are Gravitino types rather than any one system's, so the same definition works across catalogs and each provider maps them to its own.

Where a provider cannot represent a type, the provider's own page says so. Type mapping is the most common place two catalogs of different providers differ.

Table properties​

Properties are provider-specific and carry what the source system needs, such as the file format for a Hive table or the write mode for an Iceberg table. Each catalog type's page documents its own set, along with its column types and the operations it supports: Apache Hive, AWS Glue, MySQL, PostgreSQL, Oracle, SQL Server, BigQuery, Apache Doris, StarRocks, OceanBase, Hologres, ClickHouse, Apache Iceberg, Apache Paimon, Apache Hudi, and Lakehouse generic.

Not every provider accepts every table change. A change the provider does not support is rejected rather than ignored.

Partitioning, distribution, and sort order​

A table can be created with a partitioning strategy, a distribution, a sort order, and indexes. Which of those a catalog supports depends on the provider. See Table partitioning, distribution, sort order, and indexes.

Once a table is partitioned, its partitions are metadata objects in their own right. See Partitions.

Dropping versus purging​

Dropping a table removes the metadata, and for a managed table the underlying directory as well. For an external table, only the metadata goes and the data stays where it is.

Purging removes the data completely and skips any trash the system would otherwise use. Not every catalog supports it, and purging an external table is rejected rather than silently ignored.

The distinction matters most on Hive, where external tables are common and dropping one leaves the files in place.

Views​

A view is a stored query, and Gravitino treats it as its own object type rather than a kind of table. Views are supported by the Hive, Iceberg, and Paimon catalogs, and a relational catalog with a provider that has no view concept simply has none.

A view carries its columns, one or more representations, and its own comment and properties. Each representation holds the query text and the dialect it is written in, and SQL is the only representation type today. A default catalog and schema can be set so unqualified names in the query resolve. Gravitino stores the definition and does not execute it, so whether a view resolves is a question for the engine reading it.

Dropping a view removes the definition. The tables it reads are untouched.

Views can carry tags, and appear in listings alongside tables.

Working with tables and views in the UI​

In Explore, opening a catalog and then a schema lists its tables with their tags and policies. Tables and views are created through the engines and the API, not in the UI.

Opening a table shows three tabs:

  • Overview: the name, description, column count, owner, and properties. The description, owner, and properties can be edited and saved here.
  • Schema: the columns, with their types, nullability, keys, and tags. To tag columns, select them and click + Tags.
  • Data preview: a preview of the table's data.

The header of the table page shows its grants, tags, and policies, with a control for each.

Permissions​

Creating a table requires CREATE_TABLE and creating a view requires CREATE_VIEW, on the schema or above. Reading a table requires SELECT_TABLE, reading a view requires SELECT_VIEW, and writing to or altering a table requires MODIFY_TABLE.

Granting at a wider scope covers everything beneath it. Altering a view and dropping a table or a view are reserved for the metalake owner and the object owner, and ownership resolves down the hierarchy, so the owner of a catalog has the owner path to every table in it.

See Privileges for a comprehensive list of privilege grants.

Using the API​

Tables and views can be created, listed, altered, and dropped over REST and through the Java and Python clients. The REST reference documents each call for tables and views, with the client code under the Java and Python tabs.

Last updated on