> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/apache/iceberg/llms.txt
> Use this file to discover all available pages before exploring further.

# Table Endpoints

> REST API endpoints for managing tables in Apache Iceberg catalogs

# Table API

Table endpoints provide operations for creating, reading, updating, and deleting Iceberg tables through the REST Catalog API.

## List Tables

List all tables in a namespace.

```http theme={null}
GET /v1/{prefix}/namespaces/{namespace}/tables
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier (multi-part namespaces use `%1F` separator)
</ParamField>

### Query Parameters

<ParamField query="pageToken" type="string" optional>
  Pagination token from a previous response
</ParamField>

<ParamField query="pageSize" type="integer" optional>
  Maximum number of tables to return
</ParamField>

### Response

<ResponseField name="identifiers" type="array" required>
  List of table identifiers

  <Expandable title="items">
    <ResponseField name="namespace" type="array">
      Namespace parts
    </ResponseField>

    <ResponseField name="name" type="string">
      Table name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next-page-token" type="string" optional>
  Token for next page of results
</ResponseField>

### Example

```bash theme={null}
curl -X GET "https://catalog.example.com/v1/production/namespaces/accounting/tables" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "identifiers": [
    {
      "namespace": ["accounting"],
      "name": "invoices"
    },
    {
      "namespace": ["accounting"],
      "name": "payments"
    }
  ]
}
```

***

## Create Table

Create a new table in the specified namespace.

```http theme={null}
POST /v1/{prefix}/namespaces/{namespace}/tables
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

### Headers

<ParamField header="Idempotency-Key" type="string (uuid)" optional>
  UUIDv7 for idempotent request handling
</ParamField>

<ParamField header="X-Iceberg-Access-Delegation" type="string" optional>
  Comma-separated list of access delegation mechanisms: `vended-credentials`, `remote-signing`
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Table name
</ParamField>

<ParamField body="location" type="string" optional>
  Table location. If not provided, a location will be generated.
</ParamField>

<ParamField body="schema" type="object" required>
  Table schema definition
</ParamField>

<ParamField body="partition-spec" type="object" optional>
  Partition specification
</ParamField>

<ParamField body="write-order" type="object" optional>
  Sort order for data
</ParamField>

<ParamField body="properties" type="object" optional>
  Table properties
</ParamField>

<ParamField body="stage-create" type="boolean" optional>
  If true, table is not created but metadata is initialized for a transaction. Default: false.
</ParamField>

### Response

<ResponseField name="metadata-location" type="string" required>
  Location of table metadata file
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Complete table metadata
</ResponseField>

<ResponseField name="config" type="object" optional>
  Additional configuration for the table
</ResponseField>

### Example

```bash theme={null}
curl -X POST "https://catalog.example.com/v1/production/namespaces/accounting/tables" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 017F22E2-79B0-7CC3-98C4-DC0C0C07398F" \
  -d '{
    "name": "invoices",
    "schema": {
      "type": "struct",
      "fields": [
        {"id": 1, "name": "id", "type": "long", "required": true},
        {"id": 2, "name": "amount", "type": "decimal(10,2)", "required": true},
        {"id": 3, "name": "date", "type": "date", "required": true}
      ]
    },
    "partition-spec": {
      "spec-id": 0,
      "fields": [
        {"field-id": 1000, "source-id": 3, "name": "date", "transform": "day"}
      ]
    },
    "properties": {
      "write.format.default": "parquet"
    }
  }'
```

***

## Load Table

Load table metadata from the catalog.

```http theme={null}
GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

<ParamField path="table" type="string" required>
  Table name
</ParamField>

### Headers

<ParamField header="If-None-Match" type="string" optional>
  ETag from previous response. Server returns 304 if metadata hasn't changed.
</ParamField>

<ParamField header="X-Iceberg-Access-Delegation" type="string" optional>
  Access delegation mechanisms
</ParamField>

### Query Parameters

<ParamField query="snapshots" type="string" optional>
  Which snapshots to include: `all` (default) or `refs` (only referenced snapshots)
</ParamField>

<ParamField query="referenced-by" type="string" optional>
  Comma-separated list of view identifiers referencing this table
</ParamField>

### Response

<ResponseField name="metadata-location" type="string" required>
  Location of table metadata file
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Complete table metadata including schema, partition specs, snapshots, etc.
</ResponseField>

<ResponseField name="config" type="object" optional>
  Additional configuration and credentials for accessing the table
</ResponseField>

### Example

```bash theme={null}
curl -X GET "https://catalog.example.com/v1/production/namespaces/accounting/tables/invoices" \
  -H "Authorization: Bearer <token>" \
  -H "X-Iceberg-Access-Delegation: vended-credentials"
```

```json theme={null}
{
  "metadata-location": "s3://bucket/warehouse/accounting/invoices/metadata/v1.metadata.json",
  "metadata": {
    "format-version": 2,
    "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
    "location": "s3://bucket/warehouse/accounting/invoices",
    "schemas": [...],
    "current-schema-id": 0,
    "partition-specs": [...],
    "default-spec-id": 0,
    "snapshots": [...],
    "properties": {...}
  },
  "config": {
    "token": "eyJhbGc..."
  }
}
```

***

## Update Table

Commit updates to table metadata.

```http theme={null}
POST /v1/{prefix}/namespaces/{namespace}/tables/{table}
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

<ParamField path="table" type="string" required>
  Table name
</ParamField>

### Headers

<ParamField header="Idempotency-Key" type="string (uuid)" optional>
  UUIDv7 for idempotent request handling
</ParamField>

### Request Body

<ParamField body="requirements" type="array" required>
  Assertions that must be true before applying updates
</ParamField>

<ParamField body="updates" type="array" required>
  Changes to apply to table metadata
</ParamField>

### Response

<ResponseField name="metadata-location" type="string" required>
  Location of new metadata file
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Updated table metadata
</ResponseField>

### Example

```bash theme={null}
curl -X POST "https://catalog.example.com/v1/production/namespaces/accounting/tables/invoices" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requirements": [
      {
        "type": "assert-ref-snapshot-id",
        "ref": "main",
        "snapshot-id": 12345
      }
    ],
    "updates": [
      {
        "action": "append",
        "data-files": [...]
      },
      {
        "action": "set-snapshot-ref",
        "ref-name": "main",
        "snapshot-id": 12346
      }
    ]
  }'
```

<Note>
  The server validates requirements before applying updates. If any requirement fails, the entire commit is rejected with 409 Conflict.
</Note>

***

## Check Table Exists

Check if a table exists without loading its metadata.

```http theme={null}
HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

<ParamField path="table" type="string" required>
  Table name
</ParamField>

### Response

No response body. Status code indicates existence.

### Example

```bash theme={null}
curl -I "https://catalog.example.com/v1/production/namespaces/accounting/tables/invoices" \
  -H "Authorization: Bearer <token>"
```

***

## Drop Table

Delete a table from the catalog.

```http theme={null}
DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

<ParamField path="table" type="string" required>
  Table name
</ParamField>

### Query Parameters

<ParamField query="purgeRequested" type="boolean" optional>
  If true, delete table data and metadata. Default: false.
</ParamField>

### Headers

<ParamField header="Idempotency-Key" type="string (uuid)" optional>
  UUIDv7 for idempotent request handling
</ParamField>

### Response

No response body on success.

### Example

```bash theme={null}
curl -X DELETE "https://catalog.example.com/v1/production/namespaces/accounting/tables/invoices?purgeRequested=true" \
  -H "Authorization: Bearer <token>"
```

<Warning>
  With `purgeRequested=true`, all table data and metadata are permanently deleted and cannot be recovered.
</Warning>

***

## Rename Table

Rename a table or move it to a different namespace.

```http theme={null}
POST /v1/{prefix}/tables/rename
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

### Headers

<ParamField header="Idempotency-Key" type="string (uuid)" optional>
  UUIDv7 for idempotent request handling
</ParamField>

### Request Body

<ParamField body="source" type="object" required>
  Current table identifier

  <Expandable title="properties">
    <ParamField body="namespace" type="array" required>
      Current namespace
    </ParamField>

    <ParamField body="name" type="string" required>
      Current table name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="destination" type="object" required>
  New table identifier

  <Expandable title="properties">
    <ParamField body="namespace" type="array" required>
      New namespace
    </ParamField>

    <ParamField body="name" type="string" required>
      New table name
    </ParamField>
  </Expandable>
</ParamField>

### Response

No response body on success.

### Example

```bash theme={null}
curl -X POST "https://catalog.example.com/v1/production/tables/rename" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "namespace": ["accounting"],
      "name": "invoices"
    },
    "destination": {
      "namespace": ["accounting", "archive"],
      "name": "invoices_old"
    }
  }'
```

<Note>
  Moving tables across namespaces is valid but not all servers support it. Check the 406 response if cross-namespace moves fail.
</Note>

***

## Register Table

Register an existing table using its metadata file location.

```http theme={null}
POST /v1/{prefix}/namespaces/{namespace}/register
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

### Headers

<ParamField header="Idempotency-Key" type="string (uuid)" optional>
  UUIDv7 for idempotent request handling
</ParamField>

<ParamField header="X-Iceberg-Access-Delegation" type="string" optional>
  Access delegation mechanisms
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Table name to register
</ParamField>

<ParamField body="metadata-location" type="string" required>
  Location of existing metadata file
</ParamField>

### Response

Same as Load Table response.

### Example

```bash theme={null}
curl -X POST "https://catalog.example.com/v1/production/namespaces/accounting/register" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported_invoices",
    "metadata-location": "s3://external-bucket/tables/invoices/metadata/v5.metadata.json"
  }'
```

***

## Report Metrics

Send table operation metrics to the catalog.

```http theme={null}
POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics
```

### Path Parameters

<ParamField path="prefix" type="string" required>
  Optional prefix for multi-tenant deployments
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace identifier
</ParamField>

<ParamField path="table" type="string" required>
  Table name
</ParamField>

### Request Body

Metrics report containing scan metrics, commit metrics, etc.

### Response

No response body on success.

### Example

```bash theme={null}
curl -X POST "https://catalog.example.com/v1/production/namespaces/accounting/tables/invoices/metrics" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot-id": 12345,
    "scan-metrics": {
      "total-planning-duration": 100,
      "result-data-files": 5,
      "result-delete-files": 0
    }
  }'
```

***

## Status Codes

### Success

* `200 OK` - Request successful with response body
* `204 No Content` - Request successful without response body
* `304 Not Modified` - Table metadata unchanged (with If-None-Match)

### Client Errors

* `400 Bad Request` - Invalid request format
* `401 Unauthorized` - Authentication required
* `403 Forbidden` - Not authorized
* `404 Not Found` - Table or namespace does not exist
* `406 Not Acceptable` - Operation not supported
* `409 Conflict` - Table already exists or commit requirements failed
* `419 Authentication Timeout` - Authentication expired

### Server Errors

* `500 Internal Server Error` - Commit state unknown
* `502 Bad Gateway` - Gateway error, commit state unknown
* `503 Service Unavailable` - Service temporarily unavailable
* `504 Gateway Timeout` - Timeout, commit state unknown

## Common Patterns

### Staged Table Creation (CTAS)

```bash theme={null}
# 1. Stage create (don't commit yet)
curl -X POST ".../namespaces/accounting/tables" \
  -d '{
    "name": "new_table",
    "schema": {...},
    "stage-create": true
  }'

# Returns metadata without creating table

# 2. Write data and commit via update
curl -X POST ".../namespaces/accounting/tables/new_table" \
  -d '{
    "requirements": [{"type": "assert-create"}],
    "updates": [
      {"action": "add-schema", ...},
      {"action": "append", ...}
    ]
  }'
```

### Optimistic Concurrency Control

```bash theme={null}
# Load table
curl -X GET ".../tables/invoices"
# Note current snapshot ID: 12345

# Commit with requirement
curl -X POST ".../tables/invoices" \
  -d '{
    "requirements": [
      {"type": "assert-ref-snapshot-id", "ref": "main", "snapshot-id": 12345}
    ],
    "updates": [...]
  }'

# Returns 409 if another commit happened first
```

### Using ETags

```bash theme={null}
# First load
curl -X GET ".../tables/invoices"
# Response includes: ETag: "abc123"

# Subsequent load
curl -X GET ".../tables/invoices" \
  -H "If-None-Match: abc123"
# Returns 304 if unchanged, 200 with new data if changed
```

## Related

* [Namespace Endpoints](/api/rest/namespaces) - Namespace management
* [View Endpoints](/api/rest/views) - View management
* [Table Metadata Spec](/concepts/table-format#table-metadata-file) - Metadata format
* [REST API Overview](/api/rest/overview) - API overview