Prerequisites
- StarTree Cloud 0.19.0 or later with the External Table feature enabled and tiered storage configured for your environment. On older environments, GCS isn’t offered in the Storage Provider list. Contact StarTree support if unsure.
- A Unity Catalog on a Databricks workspace hosted on Google Cloud, set up as in Prepare Databricks: the table has Iceberg reads (UniForm) turned on if it’s a Delta table, you have OAuth service-principal credentials or a PAT with the
all-apisscope, and the principal has the grants it needs, includingEXTERNAL USE SCHEMA. - The Unity Catalog catalog name and the schema and table you want to onboard.
- Read access to the data, in one of two ways:
- Unity Catalog Credentials (recommended). Unity issues a short-lived GCS token for each table. External data access must be on for the metastore.
- Application Default Credentials. Pinot reads the bucket as the Google service account attached to your StarTree environment, and you grant that account read access to the bucket.
Domain restricted sharing. Unity Catalog on Google Cloud reaches your bucket through a service account that Databricks creates in its own project. If your organization enforces the
iam.allowedPolicyMemberDomains policy, GCS rejects that grant with One or more users named in the policy do not belong to a permitted customer. Your GCP admin needs to allow Databricks’ customer ID C01p0oudw on the project that holds the bucket. See Databricks’ Google Cloud requirements. Granting StarTree’s service account for Application Default Credentials may need a similar exception.Step 1: Open the External Tables
- Log in to Data Portal.
- In the left navigation, go to Tables.
- Click + Connect External Table.
Step 2: Configure the Unity Catalog Connection
Choose Unity Catalog as the catalog type. Details
Metastore: how Data Portal authenticates with the Unity Catalog Iceberg REST API.
For OAuth (Databricks service principal):
For Personal Access Token, enter a Databricks token issued with the
all-apis scope. On Google Cloud workspaces, a PAT works with both access policies.
Storage: how Pinot reads the Parquet data files.
GCS takes no region and no storage keys.
Access policy: Unity Catalog Credentials
Unity issues a short-lived GCS token scoped to each table, and Pinot renews it before it expires. You don’t manage any storage credentials. Use it for Unity-managed Iceberg tables and Delta tables with UniForm turned on. Unity doesn’t issue credentials for some table types, such as foreign Iceberg tables. Use Application Default Credentials for those.Access policy: Application Default Credentials
Pinot reads the bucket as the Google service account attached to your StarTree environment, with read-only access. Grant that accountstorage.objects.get and storage.objects.list on the bucket. The Storage Object Viewer role covers both. Contact StarTree support for the service account to grant.
Click Validate Connection. Data Portal browses the catalog to confirm the catalog credentials and connectivity. Storage access is checked later, when you pick a table.
Step 3: Browse and Select a Table
Once the connection is validated:- Data Portal lists the available schemas (the field is labeled Database) in the Unity Catalog.
- Select a schema to expand its tables.
- Click the table you want to onboard.
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, because overriding them can break segment generation. The Pinot Field Type column is editable inline, so you can switch a column between Dimension, Metric, and Date-Time where its data type allows. 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
The sync schedule is fixed at every 5 minutes at creation, and null handling is enabled automatically on the generated table config.
Click Create Table. Data Portal registers the schema and table with Pinot and starts the first onboarding run right away.
Step 6: Monitor Onboarding
The table detail view shows the onboarding status in real time:- Running: the task is reading Iceberg snapshots and building Pinot segments.
- Completed: onboarding finished. The last ingested snapshot ID is shown.
- Failed: onboarding hit an error. The error message and the number of files discovered vs. segments generated help diagnose it.
Frequently Asked Questions
GCS isn’t in the Storage Provider list. Why? The option appears only on StarTree Cloud 0.19.0 or later. Contact StarTree support to check your environment’s version.The table preview or sync fails even though browsing worked. What should I check?
- With Unity Catalog Credentials: confirm external data access is on for the metastore and the principal has
EXTERNAL USE SCHEMAandSELECT. A workspace admin withoutEXTERNAL USE SCHEMAgets no token either. Also check that the catalog endpoint and token URI use the workspace host. See Set up a service principal and grants. - With Application Default Credentials: confirm StarTree’s service account has Storage Object Viewer (or
storage.objects.getandstorage.objects.list) on the bucket.
Can I onboard multiple tables from the same catalog? Yes. Start the wizard again and reuse the same connection. Each table is an independent Pinot table with its own onboarding schedule.
Can I query these tables with cursor pagination? No. Cursor pagination isn’t supported on tables that read GCS through Unity-issued credentials.

