The Entity Model

Time: ~8 minutes. Tangible win: place every core Polaris entity in the right layer of the hierarchy, so later REST calls and RBAC grants read as structural instead of arbitrary.

Every REST call in this course targets one of six entities. Without a map of how they nest, the URL paths and grant chain in later lessons look like syntax to memorize instead of a structure to reason about.

Primary source Iceberg REST Catalog Open API spec — the protocol Polaris implements for catalog, namespace, and table entities.

Data-plane entities

Catalog — the top-level container. Each catalog is bound to one storage configuration (FILE, S3, AZURE, or GCS) and a default-base-location — where table data physically lands unless overridden.
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 (and View) — live inside a namespace. This course treats Iceberg tables as the default; Lesson 7 covers the newer non-Iceberg "Generic Table" entity.

Access-control entities

Principal — an identity, a user or service, that authenticates to Polaris. Distinct from a database user; it's scoped to Polaris itself.
Principal Role — a label attached to one or more Principals, purely for grouping ("all data engineers get this role").
Catalog Role — scoped to one specific catalog, and it's the object that actually holds privileges (e.g. TABLE_WRITE_DATA). A Catalog Role is meaningless outside the catalog it belongs to.

The access chain, previewed Fully worked in Lesson 6: Privilege → Catalog Role → Principal Role → Principal. Nothing is granted directly to a Principal or directly to a Principal Role — privileges always flow through a Catalog Role first.

Exercise: list the entities in your running server

TOKEN="principal:root;password:<your-root-secret>;realm:default-realm;role:ALL"

curl -s "http://localhost:8181/api/management/v1/catalogs" -H "Authorization: Bearer $TOKEN"
curl -s "http://localhost:8181/api/catalog/v1/<your-catalog>/namespaces" -H "Authorization: Bearer $TOKEN"
curl -s "http://localhost:8181/api/management/v1/principals" -H "Authorization: Bearer $TOKEN"

Verified output shape (this run's actual catalog/principal list):

{"catalogs":[{"type":"INTERNAL","name":"coursecatalog","properties":{"default-base-location":"file:///data"},...,"storageConfigInfo":{"storageType":"FILE","allowedLocations":["file:///data"]}}]}
{"namespaces":[["course_db"]],"next-page-token":null}
{"principals":[{"name":"root","clientId":"f103ea289b7df858",...},{"name":"course_engineer","clientId":"c44d2961a45293c7",...}]}

Retrieval check

Where can a privilege like TABLE_WRITE_DATA actually be attached?

Correct. Privileges only attach to Catalog Roles — Principal Roles are purely a grouping label one level up.

Not quite. The API won't let you attach a privilege there — only a Catalog Role holds privileges.

You create a Catalog Role named writer under catalog-a. Can you reuse it under catalog-b by referencing the same name?

Correct. A Catalog Role is meaningless outside the catalog it belongs to, even if another catalog's role happens to share the same name.

No. Catalog Roles don't transfer across catalogs — you'd need to create and grant a separate one under catalog-b.

Practice

Run the exercise against your own server and note your actual catalog, namespace, and principal names.
Draw (ASCII or prose) the entity tree: catalog → namespace(s) → table(s).
Draw the separate principal → principal role → catalog role tree, and mark with an arrow exactly where the two trees connect.

Ask the agent: "If I nest a namespace three levels deep (a.b.c), does every level need its own explicit grant, or does a grant on a cover a.b.c?" Next lesson bootstraps a real server and finds the one credential every later call depends on.