S3 Tables

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, 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 awslocal wrapper script.

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 API.

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

awslocal s3tables create-table-bucket --name my-table-bucket

{
    "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 API.

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

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

{
    "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 API.

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

awslocal 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

{
    "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 API.

Run the following command to describe the table my_table:

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

{
    "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 API.

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

awslocal 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

{
    "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 API.

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

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

{
    "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"
        }
    ]
}

API Coverage

Operation ▲	Implemented	Image	Tested on Kubernetes

Page 1 of 0