Tables API

Tables are the primary data containers in Iceberg, holding schema, partition specs, and metadata.

List Tables

List all tables in a namespace.

Request

GET /v1/namespaces/{namespace}/tables
GET /v1/namespaces/{namespace}/tables?pageToken={token}&pageSize={size}

Query Parameters

Parameter	Type	Required	Description
`pageToken`	string	No	Pagination token
`pageSize`	integer	No	Maximum results (default: 100)

Response

{
  "identifiers": [
    {"namespace": ["analytics"], "name": "user_events"},
    {"namespace": ["analytics"], "name": "page_views"}
  ],
  "next-page-token": null
}

Example

curl http://localhost:8181/v1/namespaces/analytics/tables

Create Table

Create a new Iceberg table.

Request

POST /v1/namespaces/{namespace}/tables

Request Body

{
  "name": "user_events",
  "location": "s3://bucket/warehouse/analytics/user_events",
  "schema": {
    "type": "struct",
    "schema-id": 0,
    "fields": [
      {"id": 1, "name": "event_id", "required": true, "type": "string"},
      {"id": 2, "name": "user_id", "required": true, "type": "long"},
      {"id": 3, "name": "event_type", "required": true, "type": "string"},
      {"id": 4, "name": "event_time", "required": true, "type": "timestamptz"},
      {"id": 5, "name": "properties", "required": false, "type": {
        "type": "map",
        "key-id": 6,
        "key": "string",
        "value-id": 7,
        "value": "string"
      }}
    ]
  },
  "partition-spec": {
    "spec-id": 0,
    "fields": [
      {"source-id": 4, "field-id": 1000, "name": "event_day", "transform": "day"}
    ]
  },
  "properties": {
    "format-version": "2",
    "write.parquet.compression-codec": "zstd"
  }
}

Request Fields

Field	Type	Required	Description
`name`	string	Yes	Table name
`location`	string	No	Custom table location (uses warehouse default if omitted)
`schema`	object	Yes	Iceberg schema definition
`partition-spec`	object	No	Partition specification
`write-order`	object	No	Sort order for writes
`stage-create`	boolean	No	If true, creates staged table (no data files)
`properties`	object	No	Table properties

Response

Returns the full table metadata:

{
  "metadata-location": "s3://bucket/warehouse/analytics/user_events/metadata/00000-uuid.metadata.json",
  "metadata": {
    "format-version": 2,
    "table-uuid": "550e8400-e29b-41d4-a716-446655440000",
    "location": "s3://bucket/warehouse/analytics/user_events",
    "last-updated-ms": 1705312200000,
    "schema": { "..." },
    "current-schema-id": 0,
    "partition-spec": [],
    "properties": {}
  }
}

Example

curl -X POST http://localhost:8181/v1/namespaces/analytics/tables \
  -H "Content-Type: application/json" \
  -d '{
    "name": "events",
    "schema": {
      "type": "struct",
      "schema-id": 0,
      "fields": [
        {"id": 1, "name": "id", "required": true, "type": "long"},
        {"id": 2, "name": "data", "required": false, "type": "string"}
      ]
    }
  }'

Load Table

Load a table's current metadata.

Request

GET /v1/namespaces/{namespace}/tables/{table}
GET /v1/namespaces/{namespace}/tables/{table}?snapshots={snapshots}

Query Parameters

Parameter	Type	Description
`snapshots`	string	`all` to include all snapshots, `refs` for referenced only

Response

{
  "metadata-location": "s3://bucket/warehouse/analytics/events/metadata/00001-uuid.metadata.json",
  "metadata": {
    "format-version": 2,
    "table-uuid": "550e8400-e29b-41d4-a716-446655440000",
    "location": "s3://bucket/warehouse/analytics/events",
    "current-snapshot-id": 123456789,
    "snapshots": [
      {
        "snapshot-id": 123456789,
        "timestamp-ms": 1705312200000,
        "summary": {
          "operation": "append",
          "added-data-files": "10",
          "added-records": "1000"
        }
      }
    ]
  }
}

Example

curl http://localhost:8181/v1/namespaces/analytics/tables/events

Check Table Exists

Check if a table exists.

Request

HEAD /v1/namespaces/{namespace}/tables/{table}

Response

200 OK: Table exists
404 Not Found: Table does not exist

Example

curl -I http://localhost:8181/v1/namespaces/analytics/tables/events

Commit Table Updates

Commit updates to a table (schema changes, new snapshots, property updates).

Request

POST /v1/namespaces/{namespace}/tables/{table}

Request Body

{
  "identifier": {
    "namespace": ["analytics"],
    "name": "events"
  },
  "requirements": [
    {"type": "assert-current-schema-id", "current-schema-id": 0},
    {"type": "assert-table-uuid", "uuid": "550e8400-e29b-41d4-a716-446655440000"}
  ],
  "updates": [
    {
      "action": "add-schema",
      "schema": {
        "type": "struct",
        "schema-id": 1,
        "fields": [
          {"id": 1, "name": "id", "required": true, "type": "long"},
          {"id": 2, "name": "data", "required": false, "type": "string"},
          {"id": 3, "name": "created_at", "required": true, "type": "timestamptz"}
        ]
      }
    },
    {"action": "set-current-schema", "schema-id": 1}
  ]
}

Requirements

Type	Fields	Description
`assert-create`	-	Assert table doesn't exist
`assert-table-uuid`	`uuid`	Assert table UUID matches
`assert-ref-snapshot-id`	`ref`, `snapshot-id`	Assert ref points to snapshot
`assert-current-schema-id`	`current-schema-id`	Assert current schema ID
`assert-default-spec-id`	`default-spec-id`	Assert default partition spec

Update Actions

Action	Fields	Description
`upgrade-format-version`	`format-version`	Upgrade format version
`add-schema`	`schema`	Add new schema
`set-current-schema`	`schema-id`	Set current schema
`add-partition-spec`	`spec`	Add partition spec
`set-default-spec`	`spec-id`	Set default partition spec
`add-snapshot`	`snapshot`	Add snapshot
`set-snapshot-ref`	`ref-name`, `type`, `snapshot-id`	Set snapshot reference
`remove-snapshots`	`snapshot-ids`	Remove snapshots
`set-properties`	`updates`	Update properties
`remove-properties`	`removals`	Remove properties

Errors

Code	Error	Description
404	`NoSuchTableException`	Table not found
409	`CommitFailedException`	Requirements not met

Drop Table

Delete a table.

Request

DELETE /v1/namespaces/{namespace}/tables/{table}
DELETE /v1/namespaces/{namespace}/tables/{table}?purgeRequested={true|false}

Query Parameters

Parameter	Type	Description
`purgeRequested`	boolean	If true, delete data files (default: false)

Response

204 No Content: Table deleted

Example

# Drop table, keep data files
curl -X DELETE http://localhost:8181/v1/namespaces/analytics/tables/events

# Drop table and purge data
curl -X DELETE "http://localhost:8181/v1/namespaces/analytics/tables/events?purgeRequested=true"

Register Table

Request

POST /v1/namespaces/{namespace}/register

Request Body

{
  "name": "imported_table",
  "metadata-location": "s3://bucket/path/to/metadata.json"
}

Example

curl -X POST http://localhost:8181/v1/namespaces/analytics/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported",
    "metadata-location": "s3://bucket/tables/imported/metadata/00000.metadata.json"
  }'

Rename Table

Rename a table or move it to a different namespace.

Request

POST /v1/tables/rename

Request Body

{
  "source": {
    "namespace": ["analytics"],
    "name": "old_name"
  },
  "destination": {
    "namespace": ["analytics"],
    "name": "new_name"
  }
}

Example

curl -X POST http://localhost:8181/v1/tables/rename \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"namespace": ["analytics"], "name": "events"},
    "destination": {"namespace": ["analytics"], "name": "user_events"}
  }'

Tables API

On this page