Namespace API

Namespace endpoints manage the hierarchical organization of tables and views in an Iceberg catalog.

List Namespaces

List all namespaces at a certain level, optionally starting from a parent namespace.

GET /v1/{prefix}/namespaces

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

Query Parameters

parent

string

An optional namespace to list underneath. If not provided, all top-level namespaces are listed.For multi-part namespaces, parts must be separated by the namespace separator (default: %1F).Example: accounting%1Ftax

pageToken

string

Pagination token from a previous response

pageSize

integer

Maximum number of namespaces to return

Response

namespaces

array

required

List of namespace identifiers

Show items

namespace

array

Array of strings representing namespace parts

next-page-token

string

Token for fetching the next page of results. Null if no more results.

Examples

List top-level namespaces:

curl -X GET "https://catalog.example.com/v1/production/namespaces" \
  -H "Authorization: Bearer <token>"

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

List namespaces under a parent:

curl -X GET "https://catalog.example.com/v1/production/namespaces?parent=accounting%1Ftax" \
  -H "Authorization: Bearer <token>"

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

Create Namespace

Create a new namespace with optional properties.

POST /v1/{prefix}/namespaces

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

Headers

Idempotency-Key

string (uuid)

UUIDv7 for idempotent request handling

Request Body

namespace

array

required

Array of strings representing the namespace to createExample: ["accounting", "tax"]

properties

object

String-to-string map of namespace propertiesExample: {"owner": "finance-team"}

Response

namespace

array

required

The created namespace identifier

properties

object

Properties of the created namespace (may include server-added properties)

Examples

curl -X POST "https://catalog.example.com/v1/production/namespaces" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 017F22E2-79B0-7CC3-98C4-DC0C0C07398F" \
  -d '{
    "namespace": ["accounting", "tax"],
    "properties": {
      "owner": "finance-team",
      "description": "Tax accounting tables"
    }
  }'

{
  "namespace": ["accounting", "tax"],
  "properties": {
    "owner": "finance-team",
    "description": "Tax accounting tables",
    "last_modified_time": "2024-01-15T10:30:00Z"
  }
}

Load Namespace Metadata

Retrieve metadata properties for a namespace.

GET /v1/{prefix}/namespaces/{namespace}

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

namespace

string

required

Namespace identifier. Multi-part namespaces use separator (default: %1F).Examples:

accounting - Single-part namespace
accounting%1Ftax - Multi-part namespace

Response

namespace

array

required

The namespace identifier

properties

object

All stored metadata properties for the namespace

Example

curl -X GET "https://catalog.example.com/v1/production/namespaces/accounting%1Ftax" \
  -H "Authorization: Bearer <token>"

{
  "namespace": ["accounting", "tax"],
  "properties": {
    "owner": "finance-team",
    "description": "Tax accounting tables",
    "created_time": "2024-01-01T00:00:00Z",
    "last_modified_time": "2024-01-15T10:30:00Z"
  }
}

Check Namespace Exists

Check if a namespace exists without retrieving its metadata.

HEAD /v1/{prefix}/namespaces/{namespace}

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

namespace

string

required

Namespace identifier

Response

No response body. Status code indicates existence.

Example

curl -I "https://catalog.example.com/v1/production/namespaces/accounting" \
  -H "Authorization: Bearer <token>"

Success:

HTTP/1.1 204 No Content

Not Found:

HTTP/1.1 404 Not Found

Update Namespace Properties

Set and/or remove properties on a namespace.

POST /v1/{prefix}/namespaces/{namespace}/properties

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

namespace

string

required

Namespace identifier

Headers

Idempotency-Key

string (uuid)

UUIDv7 for idempotent request handling

Request Body

removals

array

List of property keys to remove

updates

object

Map of property keys and values to set or update

Response

updated

array

required

List of property keys that were updated

removed

array

required

List of property keys that were removed

missing

array

List of properties requested for removal that were not found

Example

curl -X POST "https://catalog.example.com/v1/production/namespaces/accounting/properties" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "removals": ["department"],
    "updates": {
      "owner": "new-owner",
      "description": "Updated description"
    }
  }'

{
  "updated": ["owner", "description"],
  "removed": ["department"],
  "missing": []
}

Properties not in the request are not modified. A key cannot appear in both removals and updates.

Drop Namespace

Delete a namespace from the catalog. The namespace must be empty.

DELETE /v1/{prefix}/namespaces/{namespace}

Path Parameters

prefix

string

required

Optional prefix for multi-tenant deployments

namespace

string

required

Namespace identifier to delete

Headers

Idempotency-Key

string (uuid)

UUIDv7 for idempotent request handling

Response

No response body on success.

Example

curl -X DELETE "https://catalog.example.com/v1/production/namespaces/accounting%1Ftax" \
  -H "Authorization: Bearer <token>"

Success:

HTTP/1.1 204 No Content

The namespace must be empty (no tables or views). Otherwise, the request returns 409 Conflict.

Status Codes

Success

200 OK - Request successful with response body
204 No Content - Request successful without response body

Client Errors

400 Bad Request - Invalid request format
401 Unauthorized - Authentication required
403 Forbidden - Not authorized
404 Not Found - Namespace does not exist
406 Not Acceptable - Server doesn’t support namespace properties
409 Conflict - Namespace already exists or not empty
419 Authentication Timeout - Authentication expired
422 Unprocessable Entity - Property key in both removals and updates

Server Errors

503 Service Unavailable - Service temporarily unavailable
5XX - Other server errors

Common Use Cases

Create Hierarchical Namespace

# Create parent namespace
curl -X POST ".../namespaces" \
  -d '{"namespace": ["accounting"]}'

# Create child namespace
curl -X POST ".../namespaces" \
  -d '{"namespace": ["accounting", "tax"]}'

# Create grandchild namespace  
curl -X POST ".../namespaces" \
  -d '{"namespace": ["accounting", "tax", "2024"]}'

List All Namespaces in Hierarchy

# List top-level
curl -X GET ".../namespaces"
# Returns: [["accounting"]]

# List under accounting
curl -X GET ".../namespaces?parent=accounting"
# Returns: [["accounting", "tax"]]

# List under accounting.tax
curl -X GET ".../namespaces?parent=accounting%1Ftax"
# Returns: [["accounting", "tax", "2024"]]

Manage Namespace Lifecycle

# 1. Create with properties
curl -X POST ".../namespaces" \
  -d '{
    "namespace": ["analytics"],
    "properties": {"owner": "data-team"}
  }'

# 2. Update properties
curl -X POST ".../namespaces/analytics/properties" \
  -d '{"updates": {"description": "Analytics tables"}}'

# 3. Check if exists
curl -I ".../namespaces/analytics"

# 4. Delete when empty
curl -X DELETE ".../namespaces/analytics"

Table Endpoints - Manage tables within namespaces
View Endpoints - Manage views within namespaces
REST API Overview - API overview

Core API

Catalog API

Scan API

Write API

Actions API

REST Catalog API

Types & Expressions

​Namespace API

​List Namespaces

​Path Parameters

​Query Parameters

​Response

​Examples

​Create Namespace

​Path Parameters

​Headers

​Request Body

​Response

​Examples

​Load Namespace Metadata

​Path Parameters

​Response

​Example

​Check Namespace Exists

​Path Parameters

​Response

​Example

​Update Namespace Properties

​Path Parameters

​Headers

​Request Body

​Response

​Example

​Drop Namespace

​Path Parameters

​Headers

​Response

​Example

​Status Codes

​Success

​Client Errors

​Server Errors

​Common Use Cases

​Create Hierarchical Namespace

​List All Namespaces in Hierarchy

​Manage Namespace Lifecycle

​Related

Build docs developers (and LLMs) love

Namespace API

List Namespaces

Path Parameters

Query Parameters

Response

Examples

Create Namespace

Path Parameters

Headers

Request Body

Response

Examples

Load Namespace Metadata

Path Parameters

Response

Example

Check Namespace Exists

Path Parameters

Response

Example

Update Namespace Properties

Path Parameters

Headers

Request Body

Response

Example

Drop Namespace

Path Parameters

Headers

Response

Example

Status Codes

Success

Client Errors

Server Errors

Common Use Cases

Create Hierarchical Namespace

List All Namespaces in Hierarchy

Manage Namespace Lifecycle

Related