List tables

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

Query engines can list tables using standard SQL commands, and REST clients can retrieve table identifiers directly via the open-source Iceberg REST Catalog API specification (GET /v1/{prefix}/namespaces/{namespace}/tables).

Before you begin

See the table overview to understand the different types of tables and the implications of using them.

  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

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.

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()

Trino 

SHOW TABLES;

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 Lakehouse runtime catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.

What's next