> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3 Tables

> Register an Amazon S3 Tables bucket as an Iceberg catalog.

Register an [S3 table bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html) to query its Iceberg tables alongside your lake. oleander assumes an IAM role in your AWS account to get temporary credentials for the bucket.

## Setup

### 1. Create an IAM role

Create a role with access to S3 Tables. You can scope `Resource` down to specific table buckets.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3tables:*"],
      "Resource": "*"
    },
    {
      "Sid": "PassRoleToS3TablesReplication",
      "Effect": "Allow",
      "Action": ["iam:PassRole"],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": ["replication.s3tables.amazonaws.com"]
        }
      }
    }
  ]
}
```

Set the role's trust relationship so oleander can assume it:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::579897423473:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

### 2. Register the catalog

1. Open [Settings → Lake](https://oleander.dev/app/settings/lake) and find **External catalogs**.
2. Select **Amazon S3 Tables** and fill in the fields:

| Field | Description |
| - | - |
| **Catalog name** | A short name, e.g. `s3_tables`. Tables are queried as `name.namespace.table`. |
| **AWS Region** | The region of the table bucket, e.g. `us-east-2` |
| **AWS Account ID** | The 12-digit account that owns the bucket |
| **S3 Tables Bucket** | The table bucket name |
| **Role ARN** | The role from step 1 |

Or from the [CLI](https://docs.oleander.dev/cli/lake.md#register-a-catalog):

```bash theme={null}
oleander catalogs register s3_tables \
  --region us-east-2 \
  --account-id 123456789012 \
  --bucket my-table-bucket \
  --role-arn arn:aws:iam::123456789012:role/oleander
```

## Query

Test the catalog from the CLI:

```bash theme={null}
oleander query '
  SELECT *
  FROM s3_tables.analytics.orders
  LIMIT 100
' --engine duckdb
```

Drop `--engine duckdb` to let oleander pick the engine automatically. The catalog is also listed on the [lake page](https://oleander.dev/app/lake).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.