AWS.S3Tables reference

GetTable

Source: src/AWS/S3Tables/GetTable.ts

Runtime binding for the GetTable operation (IAM action s3tables:GetTable on the table ARN).

Reads the bound Table’s details — its current versionToken, metadataLocation, warehouseLocation, and format. The version token and metadata location are the inputs to the Iceberg commit protocol (see UpdateTableMetadataLocation). Provide the implementation with Effect.provide(AWS.S3Tables.GetTableHttp).

GetTable: Reading Table Metadata

const getTable = yield* AWS.S3Tables.GetTable(table);

const { versionToken, metadataLocation, warehouseLocation } =
  yield* getTable();

GetTableMaintenanceJobStatus

Source: src/AWS/S3Tables/GetTableMaintenanceJobStatus.ts

Runtime binding for the GetTableMaintenanceJobStatus operation (IAM action s3tables:GetTableMaintenanceJobStatus on the table ARN).

Reads the status of the bound Table’s managed maintenance jobs — Iceberg compaction and snapshot management — including when each job last ran and whether it succeeded. Useful for compute that monitors table health at runtime. Provide the implementation with Effect.provide(AWS.S3Tables.GetTableMaintenanceJobStatusHttp).

GetTableMaintenanceJobStatus: Monitoring Maintenance

const getTableMaintenanceJobStatus =
  yield* AWS.S3Tables.GetTableMaintenanceJobStatus(table);

const { status } = yield* getTableMaintenanceJobStatus();
for (const [job, state] of Object.entries(status)) {
  yield* Effect.log(`${job}: ${state?.status}`);
}

GetTableMetadataLocation

Source: src/AWS/S3Tables/GetTableMetadataLocation.ts

Runtime binding for the GetTableMetadataLocation operation (IAM action s3tables:GetTableMetadataLocation on the table ARN).

Reads the bound Table’s current metadata location and version token — the read half of the Iceberg commit protocol: read the current metadata, write a new metadata file to the warehouse, then commit it with UpdateTableMetadataLocation. Provide the implementation with Effect.provide(AWS.S3Tables.GetTableMetadataLocationHttp).

GetTableMetadataLocation: The Iceberg Commit Protocol

const getTableMetadataLocation =
  yield* AWS.S3Tables.GetTableMetadataLocation(table);

const { versionToken, metadataLocation, warehouseLocation } =
  yield* getTableMetadataLocation();

ListNamespaces

Source: src/AWS/S3Tables/ListNamespaces.ts

Runtime binding for the ListNamespaces operation (IAM action s3tables:ListNamespaces on the table bucket ARN).

Lists the namespaces in the bound TableBucket — the catalog’s databases. Useful for compute that discovers tables dynamically at runtime. Provide the implementation with Effect.provide(AWS.S3Tables.ListNamespacesHttp).

ListNamespaces: Discovering Namespaces and Tables

const listNamespaces = yield* AWS.S3Tables.ListNamespaces(bucket);

const { namespaces } = yield* listNamespaces();
for (const ns of namespaces) {
  yield* Effect.log(`namespace: ${ns.namespace[0]}`);
}

ListTables

Source: src/AWS/S3Tables/ListTables.ts

Runtime binding for the ListTables operation (IAM action s3tables:ListTables on the table bucket ARN).

Lists the tables in the bound TableBucket, optionally filtered to a namespace or name prefix. Useful for compute that enumerates the catalog at runtime. Provide the implementation with Effect.provide(AWS.S3Tables.ListTablesHttp).

ListTables: Discovering Namespaces and Tables

const listTables = yield* AWS.S3Tables.ListTables(bucket);

const { tables } = yield* listTables({ namespace: "events" });
for (const table of tables) {
  yield* Effect.log(`table: ${table.name}`);
}

Namespace

Source: src/AWS/S3Tables/Namespace.ts

A namespace within an Amazon S3 Tables TableBucket — a logical grouping of Tables, equivalent to a database in an Iceberg catalog.

Namespace: Creating Namespaces

Basic Namespace

import * as S3Tables from "alchemy/AWS/S3Tables";

const bucket = yield* S3Tables.TableBucket("Analytics");
const ns = yield* S3Tables.Namespace("Events", {
  tableBucket: bucket.tableBucketArn,
});

Named Namespace

const ns = yield* S3Tables.Namespace("Events", {
  tableBucket: bucket.tableBucketArn,
  namespace: "raw_events",
});

Table

Source: src/AWS/S3Tables/Table.ts

A fully-managed Apache Iceberg table within an S3 Tables Namespace.

S3 Tables manages the table’s storage, metadata, and maintenance (compaction, snapshot expiration). Query it through engines like Amazon Athena, Amazon EMR, or Apache Spark via the S3 Tables Iceberg catalog.

Table: Creating Tables

import * as S3Tables from "alchemy/AWS/S3Tables";

const bucket = yield* S3Tables.TableBucket("Analytics");
const ns = yield* S3Tables.Namespace("Events", {
  tableBucket: bucket.tableBucketArn,
});
const table = yield* S3Tables.Table("PageViews", {
  tableBucket: bucket.tableBucketArn,
  namespace: ns.namespace,
  schema: {
    fields: [
      { name: "id", type: "long", required: true },
      { name: "url", type: "string" },
      { name: "ts", type: "timestamp" },
    ],
  },
});

TableBucket

Source: src/AWS/S3Tables/TableBucket.ts

An Amazon S3 Tables table bucket — a purpose-built bucket for storing fully-managed Apache Iceberg tables.

A table bucket is regional and holds Namespaces, which in turn hold Tables. The bucket name is auto-generated from the app, stage, and logical ID unless you provide one explicitly.

TableBucket: Creating Table Buckets

Basic Table Bucket

import * as S3Tables from "alchemy/AWS/S3Tables";

const bucket = yield* S3Tables.TableBucket("Analytics");

Named Table Bucket

const bucket = yield* S3Tables.TableBucket("Analytics", {
  name: "my-analytics-tables",
});

TableBucket: Encryption

const bucket = yield* S3Tables.TableBucket("Secure", {
  encryptionConfiguration: {
    sseAlgorithm: "aws:kms",
    kmsKeyArn: key.keyArn,
  },
});

UpdateTableMetadataLocation

Source: src/AWS/S3Tables/UpdateTableMetadataLocation.ts

Runtime binding for the UpdateTableMetadataLocation operation (IAM action s3tables:UpdateTableMetadataLocation on the table ARN).

Commits a new Iceberg metadata file for the bound Table — the write half of the Iceberg commit protocol: read the current version with GetTableMetadataLocation, write a new metadata file into the table’s warehouse, then commit it here with the observed versionToken. A stale token fails with the typed ConflictException (another writer committed first). Provide the implementation with Effect.provide(AWS.S3Tables.UpdateTableMetadataLocationHttp).

UpdateTableMetadataLocation: The Iceberg Commit Protocol

const getTableMetadataLocation =
  yield* AWS.S3Tables.GetTableMetadataLocation(table);
const updateTableMetadataLocation =
  yield* AWS.S3Tables.UpdateTableMetadataLocation(table);

const { versionToken, warehouseLocation } =
  yield* getTableMetadataLocation();
// ... write `${warehouseLocation}/metadata/00001-….metadata.json` ...
yield* updateTableMetadataLocation({
  versionToken,
  metadataLocation: `${warehouseLocation}/metadata/00001-….metadata.json`,
});