Get table details

Viewing table details exposes the underlying schema, table properties, and configuration metadata for an Apache Iceberg table in the Lakehouse runtime catalog.

In credential vending mode, query engines also retrieve short-lived access credentials to interact safely with underlying Cloud Storage files without requiring direct IAM storage permissions.

You can inspect table details using the Google Cloud console, SQL DESCRIBE commands in Spark and Trino, or the REST API.

Before you begin

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  3. Set up the Lakehouse runtime catalog with the Apache Iceberg REST catalog endpoint.

Required roles

To get the permissions that you need to view table details, ask your administrator to grant you the following IAM roles on your project:

  • All: BigLake Viewer (roles/biglake.viewer) - your project

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Table capabilities and support

When using tables in the Lakehouse runtime catalog, it's helpful to understand the different table types and their opt-in capabilities. To learn more about using Apache Iceberg tables specifically, see Overview of Apache Iceberg tables.

Supported Iceberg tables

Only Apache Iceberg V2 (GA) and V3 (Preview) tables are supported. Iceberg V1 tables aren't supported. To upgrade existing V1 tables, see Upgrade Iceberg V1 tables to V2.

Get table details

Inspect table schema and properties.

Console

  1. In the Google Cloud console, go to Lakehouse.

    Go to Lakehouse

  2. Select an existing catalog or create one if you don't have one.

  3. In the Namespace details table, click the name of the table you want to inspect.

  4. On the Table details page, explore the table's schema, partition specification, and metadata properties.

Spark 

spark.sql("DESCRIBE EXTENDED NAMESPACE_NAME.TABLE_NAME").show()

To enable read/write interoperability and table management (preview), add the properties to the TBLPROPERTIES clause:

TBLPROPERTIES (
  'gcp.biglake.bigquery-dml.enabled' = true,
  'gcp.biglake.table-management.enabled' = true
)

Trino 

DESCRIBE SCHEMA_NAME.TABLE_NAME;

To enable read/write interoperability and table management (Preview), add these properties to the WITH clause:

WITH (
  "gcp.biglake.bigquery-dml.enabled" = 'true',
  "gcp.biglake.table-management.enabled" = 'true'
)

gcloud

To describe a table using gcloud, run the gcloud biglake iceberg tables describe command.

gcloud biglake iceberg tables describe TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME"

Replace the following:

  • TABLE_NAME: the name of your Iceberg table.
  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.

BigQuery

To view table details and metadata properties for an Apache Iceberg table in the Lakehouse runtime catalog from BigQuery, you can examine the table details in the BigQuery console or use the bq show command.

REST

To retrieve table metadata using the REST API, make a GET request to the GetIcebergTable endpoint:

GET /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables/TABLE_NAME

To load short-lived table credentials in credential vending mode, make a GET request to the LoadIcebergTableCredentials endpoint:

GET /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables/TABLE_NAME/credentials

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your Lakehouse runtime catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.
  • TABLE_NAME: the name of your Iceberg table.

What's next