Reference — the vocabulary of Apache Polaris's entity model, RBAC, and ecosystem. All lessons use terms consistently with this page.
Entity model
Catalog
The top-level container in Polaris. Bound to one storage configuration (FILE, S3, AZURE, or GCS) and a default-base-location. [docs]
Namespace
Lives inside a catalog, groups tables the way a schema/database groups tables in a traditional RDBMS. Namespaces can nest (a.b.c), each level tracked as its own entity.
Table / View
Live inside a namespace. This course treats Iceberg tables as the default; see Generic Table for the non-Iceberg alternative.
Realm
A top-level tenant boundary inside one Polaris deployment — catalogs, principals, and roles all live inside exactly one realm. Sits above the entity tree entirely, not a peer of Catalog.
Access control
Principal
An identity — a user or service — that authenticates to Polaris. Scoped to Polaris itself, distinct from a database user.
Principal Role
A label attached to one or more Principals, purely for grouping. Holds no privileges directly.
Catalog Role
Scoped to one specific catalog; the object that actually holds privileges. Meaningless outside the catalog it belongs to, even if reused by name elsewhere.
Privilege
A named permission (e.g. TABLE_READ_DATA, CATALOG_MANAGE_CONTENT, NAMESPACE_CREATE) granted to a Catalog Role. Additive and scoped to what it names — granting one never implies another.
Grant chain
The full access path: Privilege → Catalog Role → Principal Role → Principal. Nothing is granted directly to a Principal or a Principal Role.
403 Forbidden
Polaris's response when a principal has zero grants for an operation — an explicit denial naming the operation and activated roles checked, not a 404 pretending the catalog doesn't exist.
Protocol and auth
Iceberg REST Catalog spec
The vendor-neutral HTTP API for catalog operations that Polaris implements. A protocol, implementable by anyone — Polaris is one specific, Apache-governed implementation of it. [docs]
OAuth2 client credentials grant
The auth flow used against /api/catalog/v1/oauth/tokens: POST client_id, client_secret, and a scope, get back a bearer token. [docs]
Bearer token
The access token returned by the OAuth exchange, sent as Authorization: Bearer <token> on every subsequent call. Expires after expires_in seconds (3600s by default in this course).
Management API (/api/management/v1/...)
The URL prefix for admin objects: catalogs, principals, principal roles, catalog roles, grants.
Catalog API (/api/catalog/v1/{catalog}/...)
The URL prefix for Iceberg data-plane objects: namespaces, tables. A different prefix from the Management API, both behind the same bearer token.
storageConfigInfo
The block required when creating a catalog, naming a storageType and an allowedLocations allowlist. Polaris refuses to create tables outside those locations.
RESTCatalog (Spark)
The catalog-impl value (org.apache.iceberg.rest.RESTCatalog) that tells Spark to talk Iceberg REST to a configured URI, instead of a Hive Metastore or Spark's built-in catalog.
token-refresh-enabled
A Spark catalog property that makes Spark re-authenticate automatically instead of failing once its bearer token expires mid-session.
Beyond Iceberg
Generic Table
A Polaris entity for non-Iceberg tables (e.g. delta, csv): name, format, optional location, free-form properties — deliberately no schema or partition spec. [docs]
Commit coordination
Polaris's server-side handling of concurrent-write conflicts for Iceberg tables. Generic Tables get none of it — that responsibility falls to the table format's own concurrency control.
Credential vending
Polaris handing out short-lived, scoped storage credentials per request for Iceberg tables. Not provided for Generic Tables.
Catalog federation
A Polaris catalog proxying requests through to an external catalog system (Iceberg REST, Hive Metastore, or BigQuery Metastore) instead of managing entities itself. Changes how engines talk to the catalog, not where the data lives. [docs]
Persistence and topology
Persistence backend / metastore
Where Polaris's own state (catalogs, namespace pointers, principals, roles, grants) is stored — pluggable via metaStoreManager.type, separate from wherever the actual Iceberg table data lives. [docs]
metaStoreManager.type: in-memory
The quickstart default. Does not survive a container restart — all catalogs, principals, and grants are lost. Not production-safe.
EclipseLink
The JDBC-backed persistence backend option for production deployments, offered as an alternative to in-memory.
Horizontal scaling (Polaris)
Running multiple Polaris instances behind a load balancer, all sharing one persistence backend — viable because no instance holds catalog state locally.