How Titan catalogs your lake#

Titan is the catalog authority for organization lakes. It binds table names to Iceberg metadata, publishes new snapshots, vends short-lived storage access, and proves which files remain reachable.

One lake per organization#

The request path and bearer identity both name one lake. A lake bearer cannot widen itself to another lake, and its storage credential is downscoped to that lake's root. Physical lake ids are absent from SQL; the query-facing titan name is only a bound alias.

Loading a table#

An authorized load returns Iceberg metadata inline with expiring storage credentials. The credential class matches the operation: ordinary table reads, result reads, and archives do not share one broad token.

Namespace and table listings are deliberately unpaginated at the current bounded lake scale. Metadata remains the source of truth; no listing infers a table from loose storage objects.

Committing safely#

Each mutation validates requirements against the current table state and publishes a new metadata pointer with compare-and-swap arbitration.

A 409 means Titan proved the requested commit lost a conflict. An unknown outcome returns a 504 CommitStateUnknownException so the caller preserves staged files and reconciles. Reporting an uncertain outcome as 409 would invite cleanup to delete data from a commit that may have succeeded.

Errors use the Iceberg envelope {"error":{"message","type","code"}} plus a stable machine reason for refusals.

Snapshots and retention#

Every commit adds an immutable snapshot. Time travel resolves through catalog metadata, and retention removes history only after live tables, active branches, leases, and protected snapshots no longer reference it.

Garbage collection walks verified reachability. It never treats an unreferenced-looking file in isolation as proof that deletion is safe.

Branches#

A branch is a registered, path-safe name with a parent and bounded depth. Before its first write, it follows the parent's current state. The first accepted write fixes its lineage and publishes a branch-local pointer.

Non-main branches can carry time-to-live and snapshot-retention defaults. Reads use the same lake-scoped authorization boundary. Writes require a read-write lake bearer; internal source operations remain main-only. There is no implicit merge back to main.

Availability without ambiguity#

Health and readiness distinguish process life from the ability to serve authoritative catalog state. If the catalog cannot prove a safe answer, it refuses or reports unknown state. Availability is never purchased by inventing metadata.