Skip to main content
This feature is available starting in StarTree release 0.15.0. It must be enabled on demand — contact your StarTree representative to have it activated for your environment.
This guide walks through connecting an Amazon S3 Tables bucket to StarTree using the Data Portal UI. No API calls or JSON configuration required — Data Portal guides you through catalog connection, table selection, and onboarding setup through a point-and-click interface. Amazon S3 Tables are Iceberg-compatible tables accessed over the Iceberg REST protocol with AWS SigV4 authentication.
Looking for the API-based approach? See Amazon S3 Tables: Onboarding via API. Using AWS Glue instead? See AWS Glue: Onboarding via Data Portal.

​
Prerequisites

Before starting, ensure you have:
  • StarTree 0.15.0 or later with the external table Beta feature enabled for your environment.
  • AWS credentials (access key + secret key) with read permissions on both the S3 Tables catalog service and the underlying S3 data.
  • The full ARN of your S3 Tables bucket, e.g. arn:aws:s3tables:<region>:<account-id>:bucket/<bucket-name>.

​
Step 1: Open the External Tables

  1. Log in to Data Portal.
  2. In the left navigation, go to Tables.
  3. Click + Connect External Table.
The wizard opens with a connection configuration screen.

​
Step 2: Configure the S3 Tables Connection

Choose Amazon S3 Tables as the catalog type. Fill in the credentials and connection details: Details Metastore — how StarTree authenticates with the S3 Tables REST catalog API. Storage — credentials for reading the underlying Parquet data files. Click Validate Connection. Data Portal calls the catalog’s validate endpoint and confirms credentials and connectivity before proceeding.

​
Step 3: Browse and Select a Table

Once the connection is validated:
  1. Data Portal lists the available namespaces in the S3 Tables bucket.
  2. Select a namespace to expand its tables.
  3. Click the table you want to onboard.
Data Portal reads the Iceberg schema and derives a Pinot schema automatically.

​
Step 4: Review the Schema

The inferred Pinot schema is displayed for review. For External Tables this step is mostly read-only — columns can’t be added, removed, or renamed, and the inferred data types should be kept (overriding them can break segment generation). One thing is editable inline: the Pinot Field Type column lets you switch a column between Dimension, Metric, and Date-Time where its data type allows (for example, a LONG can be any of the three; a TIMESTAMP can only be Date-Time). Selecting Date-Time opens a dialog to set the value format and granularity. Multi-value columns are flagged in a dedicated column. Click Next when the schema looks correct.

​
Step 5: Configure the Table

Set the final table options: The sync schedule is fixed at every 5 minutes at creation (change it afterwards via the table config, or use Pause Sync / Resume Sync), and null handling is enabled automatically on the generated table config. Click Create Table to register the schema and table with Pinot. Data Portal automatically triggers the first onboarding run immediately after creation — no manual step required.

​
Step 6: Monitor Onboarding

Once the table is created, onboarding starts automatically. The table detail view shows the status in real time:
  • Running — the task is actively reading Iceberg snapshots and building Pinot segments.
  • Completed — onboarding finished successfully. The last ingested snapshot ID is shown.
  • Failed — onboarding encountered an error. The error message and the number of files discovered vs. segments generated are surfaced to help diagnose the issue.
For deeper observability — watcher status, checkpoint values, and per-snapshot file counts — see the Observability page.

​
Pausing Onboarding

To pause scheduled onboarding from Data Portal:
  1. Open the table in the Tables view.
  2. Click Pause Sync. This removes the schedule (cron trigger) from the table’s ExternalTableSyncTask config and stashes its value under schedule.paused, so the watcher stops firing new runs. Any run currently in progress completes normally, and existing segments and the last checkpoint are untouched. Click Resume Sync to restore the schedule from schedule.paused — onboarding resumes from where it left off; it does not restart from scratch.
This is a separate mechanism from the enabled key documented in Best Practices & Configs — that key can also be set to false directly via the table config or API to stop new runs, but the Data Portal’s Pause Sync button acts on schedule/schedule.paused, not enabled.

​
Frequently Asked Questions

The Validate step fails — what should I check?
  • Confirm the access key has s3tables:GetTableBucket, s3tables:ListTableBuckets, s3tables:ListNamespaces, s3tables:GetNamespace, s3tables:ListTables, s3tables:GetTable, s3tables:GetTableMetadataLocation, s3tables:GetTableData, and s3:GetObject permissions (or equivalent). The Steps to create IAM Policy panel in the connection form generates the exact policy for you.
  • Verify the region matches where your S3 Tables bucket lives.
  • Ensure the Table Bucket ARN is complete and correctly formatted.
Can I onboard multiple tables from the same catalog? Yes. After creating the first table, start the wizard again and reuse the same connection credentials. Each table is registered as an independent Pinot table with its own onboarding schedule.
The table was created but onboarding hasn’t started — what should I check? Data Portal triggers the first onboarding run automatically after table creation. If onboarding hasn’t started, check the table’s detail page for an error status and review the error message. You can also trigger a run manually via the trigger API.