> ## 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.

# Snowflake Horizon Catalog: Onboarding via Data Portal

> Connect Snowflake-managed Iceberg tables (Horizon Catalog) to StarTree as an External Table with the point-and-click Data Portal wizard, authenticating with a Snowflake programmatic access token (PAT).

<Warning>
  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.
</Warning>

This guide walks through connecting a **Snowflake Horizon Catalog** 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.

Snowflake Horizon exposes Snowflake-managed Iceberg tables over the standard **Iceberg REST protocol**, served on the Snowflake account host under `/polaris/api/catalog`, authenticated with a **programmatic access token (PAT)**. Data files must be **Parquet**.

> Looking for the API-based approach? See [Snowflake Horizon Catalog: Onboarding via API](./onboarding-api).
>
> Running **self-managed Apache Polaris** or **Snowflake Open Catalog** instead? Those use principal client-id/client-secret credentials — see [Apache Polaris & Snowflake Open Catalog: Onboarding via Data Portal](../polaris/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 Snowflake account with **Snowflake-managed Iceberg tables** and a **programmatic access token (PAT)** whose role restriction covers a role with read access to them.
* The Snowflake **database** backing the Iceberg tables and the schema/table you want to onboard.
* Read access to the underlying S3 object storage (the external volume's bucket) — 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 Horizon Connection

Choose **Snowflake Horizon Catalog** as the catalog type — it appears as a top-level tile 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 Horizon's Iceberg REST API.

| Field                           | Description                                                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Catalog Endpoint URI**        | The Horizon Iceberg REST endpoint: `https://<orgname>-<account_name>.snowflakecomputing.com/polaris/api/catalog`.                      |
| **Database**                    | The Snowflake database backing the Iceberg tables.                                                                                     |
| **REST Authentication Type**    | **OAuth** — the PAT is exchanged through the OAuth2 token endpoint.                                                                    |
| **OAuth Token URI**             | The token endpoint on the account host: `https://<orgname>-<account_name>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens`. |
| **Personal Access Token (PAT)** | The Snowflake programmatic access token — sent as the OAuth2 client secret.                                                            |
| **OAuth Scopes**                | `session:role:<SNOWFLAKE_ROLE>` — must match the PAT's role restriction.                                                               |

**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 **schemas** in the database — the field is labeled **Schema**.
2. Select a schema 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).