Iceberg REST Catalog Overview #4 — Managing Namespaces

Free Copy of Apache Iceberg: The Definitive Guide

Free Apache Iceberg Course

2025 Apache Iceberg Architecture Guide

Ultimate Iceberg Resource Guide

Apache Iceberg’s REST Catalog API enables seamless management of namespaces, which serve as logical groupings for tables akin to databases or schemas in traditional RDBMS. The /v1/{prefix}/namespaces endpoint allows clients to list and create namespaces dynamically, providing a structured way to organize data within an Iceberg catalog.

In this blog, we will explore:

• How to list namespaces at different levels

• How to create new namespaces

• Key considerations for handling errors and access control

Listing Namespaces (GET /v1/{prefix}/namespaces)

Namespaces in Iceberg provide a hierarchical structure for organizing datasets. The GET /v1/{prefix}/namespaces endpoint retrieves available namespaces at the top level or under a specified parent namespace.

How Namespace Listing Works

By default, calling this endpoint without parameters will return all top-level namespaces. However, specifying a parent namespace refines the results to only the child namespaces within it.

Examples of Listing Namespaces

Example 1: Fetching Top-Level Namespaces

A request without the parent parameter returns all root-level namespaces:

GET /v1/namespaces HTTP/1.1  
Host: iceberg.catalog.com  
Authorization: Bearer <your-access-token>

Response:

{
  "namespaces": [
    ["accounting"],
    ["engineering"],
    ["sales"]
  ]
}

Example 2: Fetching Nested Namespaces

If a table named accounting.tax.paid.info exists, we can query its structure:

• Querying GET /v1/namespaces?parent=accounting returns:

{   "namespaces": [  ["accounting", "tax"]   ] }

• Querying GET /v1/namespaces?parent=accounting%1Ftax (where %1F is the unit separator) returns:

{   "namespaces": [  ["accounting", "tax", "paid"]  ] }

Handling Pagination and Errors

• Clients can specify pagination parameters (page-token, page-size) to retrieve results in chunks.

• If a non-existent namespace is provided in parent, the API returns a 404 (Not Found) error.

• Authentication failures result in 401 (Unauthorized) or 403 (Forbidden) errors.

Creating a Namespace (POST /v1/{prefix}/namespaces)

The POST /v1/{prefix}/namespaces endpoint enables the creation of new namespaces. Clients can include optional metadata (e.g., ownership details).

Example: Creating a Namespace

POST /v1/namespaces HTTP/1.1  
Host: iceberg.catalog.com  
Authorization: Bearer <your-access-token>  
Content-Type: application/json

{
  "namespace": ["analytics"],
  "properties": {
    "owner": "data-team",
    "created_at": "2025-01-01T12:00:00Z"
  }
}

Response:

{
  "namespace": ["analytics"],
  "properties": {
    "owner": "data-team",
    "created_at": "2025-01-01T12:00:00Z"
  }
}

Handling Conflicts and Errors

• The API returns a 409 (Conflict) error if the namespace already exists.

• A 400 (Bad Request) error is returned if the request body is malformed.

• Servers may enforce additional properties (e.g., timestamps).

Key Takeaways

• Namespaces help organize Iceberg tables hierarchically, much like databases or schemas.

• The GET endpoint allows listing namespaces at any level, supporting hierarchical filtering.

• The POST endpoint enables namespace creation with optional metadata.

• Proper authentication is required for both operations.

• Pagination and error handling should be considered for production usage.

In the next post, we will explore managing namespace properties, including dynamically updating and deleting namespaces.