Skip to main content
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 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. 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.

​
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 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 Metastore — how StarTree authenticates with Horizon’s Iceberg REST API. Storage — credentials for reading the underlying Parquet data files from S3. 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: 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.