List tables

Listing tables lets you view all registered table entities within a namespace in the Lakehouse runtime catalog.

Query engines can list tables using standard SQL commands, and you can retrieve table identifiers using 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 list tables, 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.

List tables

List tables.

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.

Your tables appear on the Namespace details page.

Spark

spark.sql("SHOW TABLES").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

SHOW TABLES;

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 list tables using gcloud, run the gcloud biglake iceberg tables list command.

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

Replace the following:

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

BigQuery

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To list Apache Iceberg tables in the Lakehouse runtime catalog from BigQuery, you can explore the Explorer pane in the BigQuery console or use the bq ls command.

REST

To list table identifiers within a namespace using the REST API, make a GET request to the ListIcebergTableIdentifiers endpoint:

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

The response contains a JSON array of table identifiers registered under the specified namespace.

Replace the following:

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

What's next

• Learn how to get table details.
• Learn how to query a table.