Iceberg REST Catalog Overview #6 — Listing and Creating Tables

Register for 2025 Apache Iceberg Summit

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 provides a standard way to interact with tables programmatically. This post covers how to:

1. List all tables within a namespace (GET /v1/{prefix}/namespaces/{namespace}/tables)

2. Create new tables (POST /v1/{prefix}/namespaces/{namespace}/tables)

These endpoints enable structured table management while ensuring interoperability across different catalog implementations.

Listing Tables in a Namespace (GET /v1/{prefix}/namespaces/{namespace}/tables)

The GET method returns a list of all table identifiers within a given namespace. This is useful for data discovery, schema management, and auditing purposes.

Example: Listing Tables in a Namespace

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

Expected Response

{
  "tables": [
    "customer_orders",
    "sales_summary",
    "user_activity"
  ]
}

Handling Errors

• 404 Not Found → The namespace does not exist.

• 401 Unauthorized / 403 Forbidden → Insufficient permissions to access the namespace.

• 503 Service Unavailable → Temporary issues with the catalog service.

Creating a New Table (POST /v1/{prefix}/namespaces/{namespace}/tables)

The POST method creates a new table within a specified namespace. It supports both immediate creation and staged creation for transactional consistency.

Key Parameters

• stage-create: false → Creates the table immediately.

• stage-create: true → Initializes metadata but does not finalize creation until a commit is made.

Example: Creating a Table Immediately

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

{
  "name": "customer_orders",
  "schema": {
    "type": "struct",
    "fields": [
      {"name": "order_id", "type": "int", "nullable": false},
      {"name": "customer_id", "type": "int", "nullable": false},
      {"name": "order_total", "type": "double", "nullable": false},
      {"name": "order_date", "type": "string", "nullable": false}
    ]
  },
  "stage-create": false
}

Response for Successful Creation

{
  "table": "customer_orders",
  "location": "s3://data-lake/analytics/customer_orders/",
  "metadata": {
    "format-version": 2,
    "created-at": "2025-01-01T12:00:00Z"
  }
}

Handling Table Creation Errors

• 404 Not Found → The specified namespace does not exist.

• 409 Conflict → The table already exists.

• 400 Bad Request → Invalid schema or missing required fields.

• 503 Service Unavailable → Temporary service issues.

Staged Table Creation for Transactional Integrity

By setting stage-create: true, clients can initiate a table creation process without finalizing it immediately. This is useful in transactional workloads where changes must be validated before commit.

Example: Staging a Table Creation

{
  "name": "sales_summary",
  "schema": {
    "type": "struct",
    "fields": [
      {"name": "date", "type": "string", "nullable": false},
      {"name": "total_sales", "type": "double", "nullable": false}
    ]
  },
  "stage-create": true
}

After this, the client must commit the table creation via a separate API call to finalize it.

Key Takeaways

• GET /tables lists all tables under a namespace.

• POST /tables supports both immediate and staged table creation.

• Namespaces must exist before table creation; otherwise, the request fails.

• Proper authentication is required for all operations.

With these endpoints, Iceberg enables consistent, scalable, and structured table management in a RESTful manner. In the next post, we’ll explore managing table metadata and schema evolution within Iceberg catalogs. Stay tuned!