AIStor Tables API Reference

AIStor Tables implements native Apache Iceberg tables support directly within AIStor object storage, eliminating dependencies on external catalog services or metadata databases. The AIStor Tables API provides a RESTful interface compatible with the Iceberg REST Catalog specification.

All API requests use the following base path:

http://example.net:9000/_iceberg/v1

Replace example.net with your AIStor server hostname or IP address.

All requests require AWS Signature Version 4 (SigV4) authentication with the service name s3tables. Requests must include standard AWS SigV4 headers:

• Authorization - AWS SigV4 signature
• X-Amz-Date - Request timestamp
• X-Amz-Content-SHA256 - Payload hash

To authenticate a request:

1. Create an HTTP request with method, URL, headers, and body.
2. Calculate the payload hash (SHA256 of request body).
3. Generate the SigV4 signature using your access key and secret key.
4. Add the signature to the Authorization header.

Most AWS SDKs and libraries provide built-in SigV4 signing functionality. For example, the following Python code uses boto3and botocore:

from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
import boto3

session = boto3.Session(
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key'
)

request = AWSRequest(
    method='POST',
    url='http://localhost:9000/_iceberg/v1/warehouses',
    data='{"name":"analytics"}',
    headers={'Content-Type': 'application/json'}
)

SigV4Auth(session.get_credentials(), 's3', 'region').add_auth(request)

Warehouses serve as the root container for all tables and namespaces.

Create a new warehouse for storing tables and namespaces.

POST /_iceberg/v1/warehouses

Request body:

{
  "name": "analytics",
  "upgrade-existing": false
}

Response: 200 OK

{
  "name": "analytics"
}

Action: s3tables:CreateWarehouse

Return all warehouses accessible to the authenticated user or service.

GET /_iceberg/v1/warehouses

Query parameters:

Response: 200 OK

{
  "warehouses": ["analytics", "dev", "staging"],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListWarehouses

Retrieve metadata for a specific warehouse.

GET /_iceberg/v1/warehouses/{warehouse}

Response: 200 OK

{
  "name": "analytics",
  "bucket": "mybucket",
  "uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
  "created-at": "2025-10-22T10:30:00Z",
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Action: s3tables:GetWarehouse

Resource: arn:aws:s3tables:::bucket/{warehouse}

Remove a warehouse. The warehouse must be empty (no namespaces) before deletion.

DELETE /_iceberg/v1/warehouses/{warehouse}

Query parameters:

Response: 204 No Content

Action: s3tables:DeleteWarehouse

Resource: arn:aws:s3tables:::bucket/{warehouse}

Namespaces organize tables within a warehouse and support custom properties.

Create a new namespace within a warehouse.

POST /_iceberg/v1/{warehouse}/namespaces

Request body:

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Response: 200 OK

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Action: s3tables:CreateNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Return all namespaces in a warehouse.

GET /_iceberg/v1/{warehouse}/namespaces

Query parameters:

Response: 200 OK

{
  "namespaces": [
    ["data_science"],
    ["engineering"],
    ["marketing"]
  ],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListNamespaces

Resource: arn:aws:s3tables:::bucket/{warehouse}

Retrieve namespace properties.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}

Response: 200 OK

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables"
  }
}

Action: s3tables:GetNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Update or add namespace properties.

POST /_iceberg/v1/{warehouse}/namespaces/{namespace}/properties

Request body:

{
  "updates": {
    "owner": "new-team",
    "description": "Updated description"
  },
  "removals": ["environment"]
}

Response: 200 OK

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

Action: s3tables:UpdateNamespace

Remove a namespace. The namespace must be empty (no tables) before deletion.

DELETE /_iceberg/v1/{warehouse}/namespaces/{namespace}

Response: 204 No Content

Action: s3tables:DeleteNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Tables are Apache Iceberg tables with schema, partitioning, and transaction support.

Create a new table with specified schema and optional partitioning.

POST /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables

Request body:

{
  "name": "orders",
  "schema": {
    "type": "struct",
    "fields": [
      {
        "id": 1,
        "name": "order_id",
        "type": "long",
        "required": true
      },
      {
        "id": 2,
        "name": "customer_id",
        "type": "long",
        "required": true
      },
      {
        "id": 3,
        "name": "order_date",
        "type": "date",
        "required": true
      },
      {
        "id": 4,
        "name": "amount",
        "type": "decimal(10,2)",
        "required": true
      }
    ]
  },
  "partition-spec": [
    {
      "name": "order_date_year",
      "transform": "year",
      "source-id": 3,
      "field-id": 1000
    }
  ],
  "properties": {
    "owner": "orders-team",
    "description": "Order transactions"
  }
}

Restrictions:

• AIStor manages table locations, you cannot specify a custom location.
• Properties cannot begin with write.data.path.
• Most write.metadata.* properties are not supported.

Response: 200 OK

{
  "metadata": {
    "format-version": 2,
    "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
    "location": "s3://analytics/data_science/orders",
    "current-schema-id": 0,
    "schemas": [...],
    "partition-specs": [...],
    "properties": {...}
  },
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v1.metadata.json",
  "config": {}
}

Action: s3tables:CreateTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

Conditions:

• s3tables:namespace - Restrict by namespace name
• s3tables:tableName - Restrict by table name

Return all tables in a namespace.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables

Query parameters:

Response: 200 OK

{
  "identifiers": [
    {
      "namespace": ["data_science"],
      "name": "orders"
    },
    {
      "namespace": ["data_science"],
      "name": "customers"
    }
  ],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListTables

Retrieve complete table metadata including schema, partitioning, and snapshots.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Response: 200 OK

{
  "metadata": {
    "format-version": 2,
    "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
    "location": "s3://analytics/data_science/orders",
    "last-updated-ms": 1698854400000,
    "current-schema-id": 0,
    "schemas": [...],
    "current-snapshot-id": 3051729675574597004,
    "snapshots": [...],
    "partition-specs": [...],
    "properties": {...}
  },
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v3.metadata.json"
}

Action: s3tables:GetTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

You can also use a HEAD request to check if a table exists without returning metadata.

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

Response:

• 200 OK - Table exists
• 404 Not Found - Table does not exist

Atomically commit changes to a table using optimistic concurrency control.

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

Request body:

{
  "identifier": {
    "namespace": ["data_science"],
    "name": "orders"
  },
  "requirements": [
    {
      "type": "assert-table-uuid",
      "uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1"
    },
    {
      "type": "assert-last-assigned-field-id",
      "last-assigned-field-id": 4
    }
  ],
  "updates": [
    {
      "action": "append",
      "manifest-list": "s3://analytics/data_science/orders/metadata/snap-3051729675574597004.avro"
    }
  ]
}

Commit requirements:

Requirements validate preconditions before applying updates. Common types include:

Commit updates:

Updates modify table state atomically. Common actions include:

Response: 200 OK

{
  "metadata": {...},
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v4.metadata.json"
}

Action: s3tables:UpdateTable

Move a table to a different namespace or change its name.

POST /_iceberg/v1/{warehouse}/tables/rename

Request body:

{
  "source": {
    "namespace": ["data_science"],
    "name": "orders"
  },
  "destination": {
    "namespace": ["analytics"],
    "name": "order_history"
  }
}

Response: 204 No Content

Action: s3tables:RenameTable

Remove a table from the catalog.

DELETE /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Query parameters:

Response: 204 No Content

Purge Behavior:

• purgeRequested=true (default) - Remove both catalog metadata and table data files.
• purgeRequested=false - Remove only catalog entry, preserving data files.

Action: s3tables:DeleteTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

Commit changes to multiple tables atomically.

POST /_iceberg/v1/{warehouse}/transactions/commit

Request body:

{
  "table-changes": [
    {
      "identifier": {
        "namespace": ["data_science"],
        "name": "orders"
      },
      "requirements": [...],
      "updates": [...]
    },
    {
      "identifier": {
        "namespace": ["data_science"],
        "name": "customers"
      },
      "requirements": [...],
      "updates": [...]
    }
  ]
}

Response: 200 OK

The transaction succeeds only if all table commits succeed. If any table commit fails, the entire transaction is rolled back.

Retrieve catalog-level configuration and capabilities.

GET /_iceberg/v1/{warehouse}/config?warehouse={warehouse}

Response: 200 OK

{
  "defaults": {
    "s3.endpoint": "http://localhost:9000"
  },
  "overrides": {}
}

All errors return JSON responses with the following structure:

{
  "error": {
    "code": 409,
    "type": "IcebergTableAlreadyExists",
    "message": "The specified table already exists."
  }
}

Common error types:

Entity names must follow these rules:

Additional constraints:

• Multi-level namespaces: Maximum 10 nested namespaces.
• Custom table locations: Not allowed (AIStor manages locations).
• Property size: Each property key and value limited to 2KB.

AIStor Tables does not impose hard rate limits but implements best-effort concurrency control:

• Concurrent commits to the same table use optimistic locking.
• Failed commits due to conflicts should be retried with exponential backoff.
• Maximum transaction timeout is configurable per deployment.