Skip to content

S3 Tables

Protocol: REST JSON Signing service: s3tables Endpoint: http://localhost:4566

Floci emulates the S3 Tables control plane for local development, Terraform convergence, and SDK integration tests. It is a separate AWS service from S3: S3 Tables requests are signed as s3tables and use REST JSON routes such as /buckets and /tables/{tableBucketARN}/{namespace}.

Scope

This service stores table-bucket, namespace, table, policy, maintenance configuration, and metadata-location state, and gives every table a warehouse: a bucket of its own, named like the ones AWS creates (<id>--table-s3), which GetTable and GetTableMetadataLocation report as warehouseLocation. An Iceberg client such as Spark's S3TablesCatalog writes the table's data and metadata files there through Floci's S3 and commits each new metadata file with UpdateTableMetadataLocation. Deleting the table deletes its warehouse and everything in it, every object version included. A warehouse bucket is the table's storage, not a general purpose bucket, so ListBuckets leaves it out. Floci does not run an Iceberg engine itself: compaction, snapshot expiry, replication, data encryption, and metrics are outside this implementation.

A table's ARN ends in an id Floci mints when it creates the table (arn:aws:s3tables:<region>:<account>:bucket/<bucket>/table/<id>), as AWS's do, so two tables of one name in different namespaces have their own ARNs, and a rename keeps it. GetTable takes either tableArn or the table bucket's ARN, namespace and name. A table created by an earlier Floci keeps the ARN it was stored with, which ends in its name.

Supported operations

Area Operations
Table buckets CreateTableBucket, GetTableBucket, ListTableBuckets, DeleteTableBucket
Bucket encryption GetTableBucketEncryption
Bucket policy PutTableBucketPolicy, GetTableBucketPolicy, DeleteTableBucketPolicy
Bucket storage class GetTableBucketStorageClass
Bucket maintenance PutTableBucketMaintenanceConfiguration, GetTableBucketMaintenanceConfiguration
Namespaces CreateNamespace, GetNamespace, ListNamespaces, DeleteNamespace
Tables CreateTable, GetTable, ListTables, DeleteTable, RenameTable
Metadata location GetTableMetadataLocation, UpdateTableMetadataLocation
Table policy PutTablePolicy, GetTablePolicy, DeleteTablePolicy
Table maintenance PutTableMaintenanceConfiguration, GetTableMaintenanceConfiguration

Tables must use ICEBERG format. UpdateTableMetadataLocation implements optimistic concurrency: supply the table's current versionToken; a stale token returns ConflictException.

GetTableBucketEncryption returns the encryption configuration stored by CreateTableBucket, including a configured KMS key ARN. Buckets created without an explicit configuration, including those loaded from older snapshots, report AES256. This is configuration readback; Floci does not encrypt table data or perform KMS cryptographic operations. Updating or deleting a bucket's encryption configuration is not implemented.

Example

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

bucket_arn=$(aws s3tables create-table-bucket --name local-warehouse --query arn --output text)
aws s3tables create-namespace --table-bucket-arn "$bucket_arn" --namespace analytics
aws s3tables create-table \
  --table-bucket-arn "$bucket_arn" \
  --namespace analytics \
  --name events \
  --format ICEBERG

GetTableBucketStorageClass returns the storage-class configuration supplied to CreateTableBucket. An omitted configuration, including in older snapshots, reports STANDARD; an explicit INTELLIGENT_TIERING setting is preserved. This is bucket configuration readback only. Storage-class updates, per-table storage-class reads and inheritance, and physical tier transitions are not implemented.

Configuration

Variable Default Description
FLOCI_SERVICES_S3TABLES_ENABLED true Enables the S3 Tables REST JSON service.
FLOCI_STORAGE_SERVICES_S3TABLES_MODE Global storage mode Optional per-service storage-mode override.
FLOCI_STORAGE_SERVICES_S3TABLES_FLUSH_INTERVAL_MS 5000 Persistence flush interval for hybrid storage.