Create a namespace

Creating a namespace in a catalog (such as an Apache Iceberg REST catalog or Apache Hive catalog) helps you organize your tables within the Lakehouse runtime catalog.

Before you begin

1. Read About the Lakehouse runtime catalog to understand how the Lakehouse runtime catalog works and the limitations for the service.
Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 create a namespace, ask your administrator to grant you the following IAM roles on your project:

• All:
  • BigLake Admin (roles/biglake.admin)
  • Storage Admin (roles/storage.admin)

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.

Create a namespace

Create a namespace within a catalog.

Considerations

When you create a namespace, you can optionally specify a Cloud Storage bucket or path to associate with the namespace:

• Multi-bucket (bl://) (recommended): You can set any custom location as long as it is under a location allowed by the catalog (default_location or restricted_locations). If you do not specify a location, the namespace is created under the catalog's default location (for example, gs://{default_location}/{namespace_name}).

• Single-bucket (gs://): The namespace location is automatically inherited from the catalog's single bucket.

Console

Note: multi-bucket (bl://) catalogs (recommended) are not supported in the Google Cloud console. To create a namespace in this type of catalog, use gcloud or the REST API.

1. In the Google Cloud console, open the Lakehouse page.

   Go to Lakehouse

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

3. In the menu bar, click + Create namespace.

4. For Namespace name, enter a unique name for your namespace.

5. For Location, optionally specify a Cloud Storage bucket or path to associate with your namespace. The location matches the warehouse bucket.

6. Click Create.

   Your namespace is created and appears in your catalog details list.

gcloud

Create a namespace in a multi-bucket (bl://) catalog (recommended)

To create a namespace in a multi-bucket catalog (where you can optionally specify a custom location), run the gcloud biglake iceberg namespaces create command with the --properties flag:

gcloud biglake iceberg namespaces create NAMESPACE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    [--properties="location=LOCATION"]

Replace the following:

• NAMESPACE_NAME: a name for your namespace.
• PROJECT_ID: your Google Cloud project ID.
• CATALOG_ID: the ID of your catalog.
• LOCATION: (Optional) a custom Cloud Storage bucket or path to associate with the namespace (for example, gs://my-bucket/my-path).

Create a namespace in a single-bucket (gs://) catalog

To create a namespace in a single-bucket catalog, omit the --properties flag. The namespace location is automatically inherited from the catalog's single bucket.

gcloud biglake iceberg namespaces create NAMESPACE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID"

REST

To create a namespace using the REST API, make a POST request to the CreateIcebergNamespace endpoint:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces

The request body must contain a valid Iceberg CreateNamespaceRequest JSON payload defining the namespace identifier and properties:

{
  "namespace": [
    "NAMESPACE_NAME"
  ],
  "properties": {
    "location": "LOCATION"
  }
}

Replace the following:

• PROJECT_ID: your Google Cloud project ID.
• CATALOG_ID: the ID of your catalog.
• NAMESPACE_NAME: a name for your namespace.
• LOCATION: (Optional) a custom Cloud Storage bucket or path to associate with the namespace (for example, gs://my-bucket/my-path).