Skip to main content
This feature requires StarTree release 0.16.0 or later, and must be enabled on demand — contact StarTree support to activate it.
As an alternative to the REST onboarding flow (/connections/browse → /tables/preview → /schemas → /tables), you can create an External Table directly with a single SQL statement:
This is submitted as SQL DDL via POST /sql/ddl and is equivalent to running the full preview → schema → table REST flow — the controller infers the Pinot schema from the source table and pre-validates it against the catalog before creating the table.

Option reference

Recognized option names are case-insensitive. Unrecognized options pass through verbatim — with their original case preserved — into the generated table’s task config, so you can set advanced ExternalTableSyncTask keys (see Best Practices & Configs) directly in the WITH clause. Type those keys in their exact camelCase spelling (e.g. 'storeNestedSchema.enabled' = 'true'): the task config lookup is case-sensitive, and pass-through keys are also read at CREATE-time schema inference.
Any option not listed above is passed through unchanged to the External Table task config — for example executor = 'controller' to explicitly select the watcher-based sync path used by the observability endpoints.

Example: Unity Catalog with OAuth2

catalog_type = 'unity' is equivalent to catalog_type = 'rest' against a Unity Catalog endpoint — it’s shorthand that sets the Unity service type explicitly instead of relying on generic REST detection. Either value works for Unity today.

Hive Metastore

Use catalog_type = 'hive' for Iceberg or native Parquet tables registered in a Hive Metastore (HMS), reached over a binary Thrift endpoint — catalog_uri must be thrift://host:port (even with TLS; thrift+ssl:// isn’t accepted). catalog_name sets the warehouse. REST auth options (auth_type, client_id/client_secret, token) aren’t accepted for this catalog type — use the metastore.* options below instead. storage.* options configure access to the underlying data — S3 by default, or Azure Blob/ADLS via storage.provider = 'azure' (see Azure source storage). For every option with its default, limits and common errors, see Hive Metastore: Onboarding via API. For worked DDL examples, see Onboarding via SQL DDL.
Authentication and certificate failures reject the connection — there is no plaintext fallback. The keytab, ticket cache, and TLS stores must exist as local files, readable by the Pinot process, on every controller that browses or synchronizes the table.
Example — Kerberos over TLS:

Azure source storage

Azure source storage is in beta. Contact StarTree support to enable it for your environment.
Hive Metastore (catalog_type = 'hive') and Unity Catalog / generic Iceberg REST (catalog_type = 'unity' or 'rest') can read Parquet data from Azure Blob Storage or ADLS instead of Amazon S3, using a configured SAS token. AWS Glue and Amazon S3 Tables don’t support Azure source storage — those services are Amazon S3 only. Set storage.provider = 'azure' along with storage.sas_token (an unexpired SAS granting read/list access, referenced as an srn2:secret#... secret) and storage.credential_prefix (the container/path the SAS is scoped to). These replace the storage.region / storage.access_key / storage.secret_key / storage.session_token / storage.endpoint options, which are rejected when storage.provider = 'azure'.
For Unity Catalog, catalog authentication (the bearer token or OAuth2 credentials under auth_type) stays independent of the Azure source credentials above. With storage.provider = 'azure', SQL DDL always uses the configured SAS token. It can’t set up Unity-vended Azure credentials. Unlike S3, an enumeration failure against a configured Azure source always fails the CREATE TABLE statement — there’s no best-effort fallback to the table root. This SQL DDL path is currently the only way to onboard Azure source storage; the Data Portal and REST onboarding flow (/connections/browse → /tables/preview → /schemas → /tables) don’t expose it yet.

Limitations

  • The generated schema and table config aren’t visible for review before creation, unlike the REST flow’s /tables/preview step — use the REST flow instead when you need to inspect or tweak the inferred schema first.
  • As with the REST flow, the table is created immediately but data only appears once the controller’s watcher completes the first sync — see Observability to track progress.
  • Hive Metastore (catalog_type = 'hive') only reaches the HMS binary Thrift endpoint — HTTP/REST metastore endpoints aren’t supported. For an Iceberg table registered in HMS, v2 equality deletes and standard Parquet position deletes are applied the same way as for other catalogs — set 'enableDeletionVectors' = 'true' (see Deletion Vectors) only after every controller and server is upgraded to a build that supports derived row-delete blobs; without the flag, affected rows stay visible even after a successful sync. Native Hive Parquet tables (type = 'hive') are append-only, with no snapshots, deletion vectors, or segment groups.