# S3 Tables

Source: /aws/services/s3tables/

## Introduction

Amazon S3 Tables is a managed Apache Iceberg table catalog that uses S3 storage.
It acts as a catalog that transparently manages the underlying S3 buckets for you, providing built-in maintenance features like automatic compaction and snapshot management.
It is designed for analytics workloads that need high read/write throughput and simplified table operations without having to directly manage S3 bucket infrastructure.

LocalStack lets you use the S3 Tables API locally to create table buckets, organize tables in namespaces, and manage table metadata locations.
The supported APIs are available on the [API coverage section](#api-coverage), which provides information on the extent of S3 Tables' integration with LocalStack.

## Getting started

This guide is designed for users new to S3 Tables and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#aws) command.

Start your LocalStack container using your preferred method.
We will demonstrate how to create a table bucket, a namespace, a table, and how to retrieve table details and metadata location with the AWS CLI.

### Create a table bucket

You can create a table bucket to store S3 Tables using the [`CreateTableBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_CreateTableBucket.html) API.

Run the following command to create a table bucket named `my-table-bucket`:

```bash
lstk aws s3tables create-table-bucket --name my-table-bucket
```

```bash title="Output"
{
    "arn": "arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket"
}
```

### Create a namespace

Namespaces help organize tables within a table bucket. You can create a namespace within the table bucket using the [`CreateNamespace`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_CreateNamespace.html) API.

Run the following command to create a namespace named `my_namespace` within the table bucket `my-table-bucket`:

```bash
lstk aws s3tables create-namespace \
    --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \
    --namespace my_namespace
```

```bash title="Output"
{
    "tableBucketARN": "arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket",
    "namespace": [
        "my_namespace"
    ]
}
```

### Create a table

You can also create a table within the namespace with the [`CreateTable`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Tables_CreateTable.html) API.

Run the following command to create a table named `my_table` within the namespace `my_namespace`:

```bash
lstk aws s3tables create-table \
    --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \
    --namespace my_namespace \
    --name my_table \
    --format ICEBERG
```

```bash title="Output"
{
    "tableARN": "arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket/table/my_table",
    "versionToken": "0c0c1509"
}
```

### Retrieve table information

You can describe the table to view details such as ARN, namespace, format, and warehouse location using the [`GetTable`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Tables_GetTable.html) API.

Run the following command to describe the table `my_table`:

```bash
lstk aws s3tables get-table \
    --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \
    --namespace my_namespace \
    --name my_table
```

```bash title="Output"
{
    "name": "my_table",
    "type": "customer",
    "tableARN": "arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket/table/my_table",
    "namespace": [
        "my_namespace"
    ],
    "namespaceId": "380d99d1-abbf-4121-8e2c-c9a06e2def06",
    "versionToken": "0c0c1509",
    "warehouseLocation": "s3://hqpdve6ni1lb7w5bdn24lruswomtsh5bdrw66oip--table-s3",
    "createdAt": "2025-10-23T15:34:59.193399Z",
    "createdBy": "000000000000",
    "modifiedAt": "2025-10-23T15:34:59.193400Z",
    "ownerAccountId": "000000000000",
    "format": "ICEBERG",
    "tableBucketId": "bead5f2e-405f-4c66-b8f3-545f89ee1058"
}
```

### Retrieve table metadata location

You can fetch the warehouse location used for table metadata using the [`GetTableMetadataLocation`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Tables_GetTableMetadataLocation.html) API.

Run the following command to fetch the warehouse location for the table `my_table`:

```bash
lstk aws s3tables get-table-metadata-location \
    --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \
    --namespace my_namespace \
    --name my_table
```

```bash title="Output"
{
    "versionToken": "0c0c1509",
    "metadataLocation": "s3://hqpdve6ni1lb7w5bdn24lruswomtsh5bdrw66oip--table-s3/metadata/00000-b6d96c57-403a-4387-ac59-ec55ac2e646b.metadata.json",
    "warehouseLocation": "s3://hqpdve6ni1lb7w5bdn24lruswomtsh5bdrw66oip--table-s3"
}
```

### List tables in a namespace

You can list tables in the `my_namespace` namespace using the [`ListTables`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Tables_ListTables.html) API.

Run the following command to list tables in the namespace `my_namespace`:

```bash
lstk aws s3tables list-tables \
    --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \
    --namespace my_namespace
```

```bash title="Output"
{
    "tables": [
        {
            "namespace": [
                "my_namespace"
            ],
            "name": "my_table",
            "type": "customer",
            "tableARN": "arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket/table/my_table",
            "createdAt": "2025-10-23T15:34:59.193399Z",
            "modifiedAt": "2025-10-23T15:34:59.193400Z"
        }
    ]
}
```

## Querying S3 Tables from Athena

LocalStack [Athena](/aws/services/athena/) can query S3 Tables data through a Glue federated catalog.
Once you register a federated `s3tablescatalog` in Glue and add a matching Athena data catalog, you can run SQL against your S3 Tables namespaces and tables directly from Athena.

See [S3 Tables in the Athena documentation](/aws/services/athena/#s3-tables) for the full workflow.

## API Coverage


### s3tables API coverage

Source service: `s3tables`. 26 of 49 tracked operations are implemented.

Service documentation: /aws/services/s3tables/

| Operation | Status |
| --- | --- |
| CreateNamespace | Implemented |
| CreateTable | Implemented |
| CreateTableBucket | Implemented |
| DeleteNamespace | Implemented |
| DeleteTable | Implemented |
| DeleteTableBucket | Implemented |
| DeleteTableBucketEncryption | Implemented |
| DeleteTableBucketMetricsConfiguration | Not implemented |
| DeleteTableBucketPolicy | Not implemented |
| DeleteTableBucketReplication | Not implemented |
| DeleteTablePolicy | Not implemented |
| DeleteTableReplication | Not implemented |
| GetNamespace | Implemented |
| GetTable | Implemented |
| GetTableBucket | Implemented |
| GetTableBucketEncryption | Implemented |
| GetTableBucketMaintenanceConfiguration | Implemented |
| GetTableBucketMetricsConfiguration | Not implemented |
| GetTableBucketPolicy | Not implemented |
| GetTableBucketReplication | Not implemented |
| GetTableBucketStorageClass | Not implemented |
| GetTableEncryption | Implemented |
| GetTableMaintenanceConfiguration | Implemented |
| GetTableMaintenanceJobStatus | Not implemented |
| GetTableMetadataLocation | Implemented |
| GetTablePolicy | Not implemented |
| GetTableRecordExpirationConfiguration | Not implemented |
| GetTableRecordExpirationJobStatus | Not implemented |
| GetTableReplication | Not implemented |
| GetTableReplicationStatus | Not implemented |
| GetTableStorageClass | Not implemented |
| ListNamespaces | Implemented |
| ListTableBuckets | Implemented |
| ListTables | Implemented |
| ListTagsForResource | Implemented |
| PutTableBucketEncryption | Implemented |
| PutTableBucketMaintenanceConfiguration | Implemented |
| PutTableBucketMetricsConfiguration | Not implemented |
| PutTableBucketPolicy | Not implemented |
| PutTableBucketReplication | Not implemented |
| PutTableBucketStorageClass | Not implemented |
| PutTableMaintenanceConfiguration | Implemented |
| PutTablePolicy | Not implemented |
| PutTableRecordExpirationConfiguration | Not implemented |
| PutTableReplication | Not implemented |
| RenameTable | Implemented |
| TagResource | Implemented |
| UntagResource | Implemented |
| UpdateTableMetadataLocation | Implemented |