> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect to Amazon S3 Tables Catalog
> Connect an Amazon S3 table bucket as an Iceberg catalog in Wherobots from the Data Hub, then read and write S3 Tables from your Wherobots Spark workloads.
Use the data in your Amazon S3 table buckets in Wherobots. Connect a table bucket once from the Data Hub, then read and write its Iceberg tables from your Wherobots Spark workloads.
Wherobots connects to Amazon S3 Tables through a [**Cloud Connection**](#cloud-connections), which is a reusable IAM role that Wherobots assumes in your AWS account. The Data Hub wizard provisions everything with AWS CloudFormation, so there's no IAM policy or Spark configuration to write by hand.
## Before you start
The following requirements must be met within both your Wherobots Organization and AWS account before you can connect to an S3 Tables catalog.
* An **Admin** account within a **Professional**, **Innovation**, or **Enterprise** Edition Organization to create catalogs and Cloud Connections.
Wherobots Organization members with the **User** role can use existing catalogs and Cloud Connections set up by Admins but cannot create new ones. See [Organization Roles](/get-started/organization-info/organization-roles/).
* An existing **Cloud Connection** to your AWS account, or permission to create one. For more information, see [Cloud Connections](#cloud-connections).
* Your **Organization ID**, found at [cloud.wherobots.com/organization](https://cloud.wherobots.com/organization).
* An **AWS account** with an existing **S3 table bucket**. Unlike a general purpose S3 bucket, a table bucket stores Iceberg tables and manages their storage for you, so you don't supply a separate S3 path.
* The **ARN of the table bucket** you want to connect, in the form `arn:aws:s3tables:::bucket/`. Find it in the AWS console under **S3** → **Table buckets**.
* Permission to **create CloudFormation stacks that provision IAM resources** (typically `AdministratorAccess`), so Wherobots can set up the Cloud Connection and grant it S3 Tables access. CloudFormation creates the IAM role and policies for you, so you don't edit them by hand.
The pre-filled templates create or modify IAM resources on your behalf. The actions they perform typically require `AdministratorAccess`:
| IAM Action | Description |
| ------------------------ | --------------------------------------------------------- |
| `CreateRole` | Creates the Cloud Connection IAM role |
| `UpdateAssumeRolePolicy` | Sets the trust policy that lets Wherobots assume the role |
| `PutRolePolicy` | Attaches the inline policy granting S3 Tables access |
| `AttachRolePolicy` | Attaches a managed policy to the role |
| `DeleteRolePolicy` | Removes an inline policy (on stack update or delete) |
| `DetachRolePolicy` | Detaches a managed policy (on stack update or delete) |
For a complete list of IAM Actions, see [Actions defined by AWS Identity and Access Management](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) in the AWS Documentation.
### Cloud Connections
Before you can connect to an Amazon S3 Tables catalog, Wherobots needs a **Cloud Connection** to your AWS account.
A **Cloud Connection** is a single, reusable trust relationship between your Wherobots Organization and a cloud provider account. For AWS, it's a first-class object that stores your AWS **account ID** and an IAM **role** (with an **external ID**) that Wherobots assumes on your behalf to access resources in your account.
Create **one** Cloud Connection per AWS account and reuse it across all of your **S3 storage integrations** and **AWS Glue catalogs** in that account, instead of configuring credentials separately for each one.
**Trust is established with AWS CloudFormation.** Create the connection directly in the Wherobots UI, or download the CloudFormation template (YAML) so your security team can review it before deploying.
### Manage Cloud Connections
Cloud Connections live in [**Organization Settings**](https://cloud.wherobots.com/organization#cloud-connections) under **Cloud Connections**, where Admins can create, list, verify, and delete them.
* **Verify**: Confirms Wherobots can assume your IAM role through the two-hop AWS STS `AssumeRole` chain.
* **Delete**: Blocked while any storage integration or Glue catalog is still bound to the connection. You must remove any resources bound to that Cloud Connection prior to its deletion.
## Connect to the Amazon S3 Tables catalog
Connect your S3 table bucket to your Wherobots Organization in order to read and write to it from your Wherobots workloads.
The Data Hub wizard provisions the connection with a CloudFormation stack, so you don't have to write IAM policies or Spark configs by hand.
In [Wherobots Cloud](https://cloud.wherobots.com/), open the [**Data Hub**](https://cloud.wherobots.com/data-hub).
With no catalog selected, the details pane shows **Add data** cards. Select the **Amazon S3 Tables** card.
This opens the **Add Amazon S3 Tables Catalog** wizard.
On the **Details** step, enter:
* **Name:** The name of the catalog in Wherobots.
* This affects the Fully Qualified Name (FQN) used to reference this catalog in Wherobots: `CATALOG_NAME.DATABASE_NAME.TABLE_NAME`, where `DATABASE_NAME` is the S3 Tables namespace.
* A name can contain any character. But if it includes anything other than letters, numbers, or underscores — such as a space, dash, or period — you must wrap the name in backticks wherever you reference it in the FQN. For example, a catalog named `My-Catalog` is referenced as `` `My-Catalog`.namespace.table ``.
For simplicity and to avoid quoting issues, it's recommended to use only alphanumeric characters or underscores.
* **Table Bucket ARN:** The ARN of the S3 table bucket you're connecting, for example `arn:aws:s3tables:us-east-1:123456789012:bucket/my-table-bucket`. The region and AWS account are read from the ARN, so there's no separate **AWS Region** or **S3 Path** field to fill in.
* **Access level:** The level of access Wherobots has to the catalog.
* Choose **Read-only** to allow Wherobots to read tables in your S3 Tables catalog, but not create or modify them.
* Choose **Read-write** to allow Wherobots to read, create, and modify tables in your S3 Tables catalog.
* Click **Continue**.
On the **Connection** step, pick an existing [Cloud Connection](#cloud-connections) or create a new one, then click **Continue**.
Creating a connection takes two steps inside the **Create Cloud Connection** dialog.
* **Connection Name** — a label that identifies the trust relationship in Wherobots.
* **AWS Account ID** — the 12-digit AWS account you're connecting to.
Click **Create Connection**.
Wherobots generates a pre-filled CloudFormation stack that creates the connection's IAM role. Click **Open in AWS Console** to launch it in a new tab, or **Download Template** to run it yourself.
On the AWS **Quick create stack** page, everything is pre-filled. Scroll to the bottom, select **I acknowledge that AWS CloudFormation might create IAM resources**, and click **Create stack**.
Back in Wherobots, click **Done** to finish creating the connection.
On the **Deploy** step, launch the pre-filled CloudFormation stack. It attaches S3 Tables access to your Cloud Connection.
Wherobots displays the **Stack name** it uses, so you can find the stack later in the AWS CloudFormation console.
1. Click **Open in AWS Console** (or **Download Template** to manually paste it into the AWS CloudFormation console).
2. On the AWS **Quick create stack** page, scroll to the bottom, select **I acknowledge that AWS CloudFormation might create IAM resources**, and click **Create stack**.
3. Return to Wherobots and click **Create catalog**.
**Create catalog** stays disabled until you launch the stack or download the template.
Expand **What to do on the AWS page** for an annotated walkthrough of the AWS **Quick create stack** page.
After the stack completes, Wherobots verifies it can access your table bucket. Once verified, the catalog appears in the [**Data Hub**](https://cloud.wherobots.com/data-hub) and is ready to use.
IAM changes can take a few minutes to propagate across AWS. If verification fails immediately, wait a moment and retry.
## Next Steps
After you connect your S3 Tables catalog, you can query its tables from a Wherobots notebook. See [Query Amazon S3 Tables Catalog in a Notebook](/get-started/initial-storage/aws/query-s3-tables-catalog-in-a-notebook) for guidance and starter code.
**Runtime Restart Required After Data Integration**
To use new storage integrations or catalogs in your notebooks, you must start a new runtime.
Notebooks can only access storage integrations or catalogs that were created before the runtime started.
## Limitations
Review the following caveats of the s3 tables integration:
* S3 tables integration doesn't support staged creates.
* `CREATE TABLE` `AS` `SELECT` (CTAS) / `REPLACE TABLE` `AS` `SELECT` (RTAS) unsupported as S3 Tables rejects staged creates and will output `"Stage-create is currently not supported"` if attempted.
* S3 tables integration doesn't support reading or writing views.
* S3 tables integration doesn't support `ALTER TABLE … RENAME TO`.
* Iceberg V3 Tables can be read, but *ONLY* if they don't have any of the new column types (`geometry` / `geography`, `variant`, `timestamp_ns`).
* Geometry round-trips as WKB binary is not supported.
* `geometry` columns are read back as binary and require use of `ST_GeomFromWKB()`.
* `DROP TABLE `/ `DROP NAMESPACE` from Spark is unsupported.