The Lakehouse runtime catalog lets you create namespaces in
borderless Lakehouse
[catalog endpoints](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt#configuration) to
group and organize related tables.

When you create a namespace, you can optionally associate it with a custom
Cloud Storage bucket or path, or inherit the catalog's default storage location.

## Before you begin

1. Read [About the Lakehouse runtime catalog](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt) to understand how the Lakehouse runtime catalog works and the limitations for the service.

### 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](https://docs.cloud.google.com/iam/docs/roles-permissions/biglake.md.txt#biglake.admin) (`roles/biglake.admin`)
  - [Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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:

- **Multiple-bucket catalog** (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 catalog**: The namespace location is automatically
  inherited from the catalog's single bucket.

### Console

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

   [Go to Lakehouse](https://console.cloud.google.com/biglake)
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 multiple-bucket catalog (recommended)**

To create a namespace in a multiple-bucket catalog
(where you can optionally specify a custom location), run the
[`gcloud biglake iceberg namespaces create` command](https://docs.cloud.google.com/sdk/gcloud/reference/biglake/iceberg/namespaces/create) with
the `--properties` flag:

```bash
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 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.

```bash
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`](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.v1.projects.catalogs.namespaces/create.md.txt) 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:

```json
{
  "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`).

## What's next

- Learn how to [manage namespace ACLs](https://docs.cloud.google.com/lakehouse/docs/manage-tables-acl.md.txt#apply-acl-namespaces).