> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Apache Polaris & Snowflake Open Catalog: Onboarding via Data Portal
> Connect an Apache Polaris or Snowflake Open Catalog Iceberg table to StarTree as an External Table with the point-and-click Data Portal wizard, authenticating with OAuth2 principal credentials.
This feature is available starting in **StarTree release 0.16.0**. It must be enabled on demand — contact your StarTree representative to have it activated for your environment.
This guide walks through connecting an **Apache Polaris** or **Snowflake Open Catalog** table 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.
Both catalogs speak the standard **Iceberg REST protocol** and authenticate with **OAuth2 principal credentials** (client ID + client secret). The wizard has a dedicated tile for each; the two forms are identical apart from defaults, so this page covers both. Data files must be **Parquet**.
> Looking for the API-based approach? See [Apache Polaris & Snowflake Open Catalog: Onboarding via API](./onboarding-api).
>
> Using **Snowflake Horizon Catalog** (Snowflake-managed Iceberg tables, PAT auth) instead? See [Snowflake Horizon: Onboarding via Data Portal](../horizon/onboarding-data-portal).
***
## Prerequisites
Before starting, ensure you have:
* **StarTree 0.16.0 or later** with the External Table feature enabled and **tiered storage configured** for your environment. Contact StarTree support if unsure.
* A running catalog:
* **Apache Polaris** — a reachable Polaris server and a principal (client ID + client secret) whose principal role can read the catalog.
* **Snowflake Open Catalog** — an Open Catalog account and a service connection's principal credentials.
* The **catalog name** (Polaris/Open Catalog catalog backing the Iceberg tables) and the namespace/table you want to onboard.
* Read access to the underlying S3 object storage — static keys or an IAM role StarTree can assume. See [Onboarding via API — Authentication](./onboarding-api#authentication) for the permissions required.
***
## 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 Catalog Connection
Choose **Apache Polaris** or **Snowflake Open Catalog** as the catalog type — they appear as top-level tiles alongside AWS Glue, Amazon S3 Tables, and Unity Catalog.
Fill in the connection details:
**Details**
| Field | Description |
| ------------------- | --------------------------------------------------------- |
| **Connection Name** | A unique name to identify this connection in Data Portal. |
**Metastore** — how StarTree authenticates with the Iceberg REST API.
| Field | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Catalog Endpoint URI** | The Iceberg REST endpoint — `https:///api/catalog` for Apache Polaris, or `https://.snowflakecomputing.com/polaris/api/catalog` for Snowflake Open Catalog. |
| **Catalog Name** | The Polaris / Open Catalog **catalog** backing the Iceberg tables. |
| **Prefix** | *(Snowflake Open Catalog only)* Multi-catalog REST prefix; pre-filled from the Catalog Name — leave the default unless your deployment uses a different prefix. |
| **REST Authentication Type** | **OAuth** — the only option for these catalogs. |
| **OAuth Token URI** | The catalog's OAuth2 token endpoint, e.g. `.../api/catalog/v1/oauth/tokens` (Polaris) or `https://.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens` (Open Catalog). |
| **OAuth Client ID** | The principal's client ID. |
| **OAuth Client Secret** | The principal's client secret. |
| **OAuth Scopes** | The principal-role scope, default `PRINCIPAL_ROLE:ALL`. Narrow it to a specific principal role if your security model requires it. |
**Storage** — credentials for reading the underlying Parquet data files from S3.
| Field | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Region** | AWS region where the S3 data files are stored. Always required. |
| **Authentication Type** | **Basic Authentication** (Access Key + Secret Key) or **IAM Role** (a cross-account role StarTree assumes). |
| **Access Key** / **Secret Key** | With **Basic Authentication**: static AWS credentials for S3 data access. |
| **IAM Role ARN** | With **IAM Role**: the ARN of the role to assume. The form shows **Steps to create IAM Policy** — a ready-made trust policy including the StarTree account and External ID to configure on the role. |
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** — the field is labeled **Namespace** (Apache Polaris) or **Schema** (Snowflake Open Catalog).
2. Select one 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:
| Setting | Default | Notes |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table Name** | — | Name of the Pinot table to create. |
| **Serving Replicas** | `1` | Replication factor for the table's (metadata-only) segments. `1` maximizes onboarding throughput; it can be raised later. |
| **Time Column** | *(first candidate)* | Shown only when the schema has date-time columns — pick the primary time column used for segment pruning and retention, or leave the table without one. |
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
The table detail view shows sync status in real time — files discovered, segments generated, last synced snapshot, and ingestion lag. Use **Schedule Now** to trigger an immediate sync, or **Pause Sync** / **Resume Sync** from the table menu. For API-based monitoring, see [Observability](../observability).