Namespace Endpoints

REST API endpoints for managing namespaces in Apache Iceberg catalogs

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 create

Example: ["accounting", "tax"]

properties · object

String-to-string map of namespace properties

Example: {"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"

Related

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