/connections/browse → /tables/preview → /schemas → /tables), you can create an External Table directly with a single SQL statement:
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 advancedExternalTableSyncTask 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
Usecatalog_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.
Azure source storage
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'.
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/previewstep — 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.

