Skip to content

common_db.contracts.identity

identity.py — where data lives and how it is keyed.

TableRef and DatasetRef (Place) and KeySpec (Identity/Relation): the nouns every op, model, and policy speaks. TableRef addresses a Postgres table; DatasetRef addresses a parquet dataset (the archive leg). Partial uniques are FIRST-CLASS — the incarnation indexes proved a table’s real identity often needs a WHERE clause.

Classes

DatasetRef

Bases: BaseModel

One dataset’s address: root + name. Frozen; renders itself.

The Place noun of the archive leg — a parquet dataset is a directory (or URI prefix) of hive-partitioned fragments, not a table. Canonical string form is root::name — ’::’ because roots are paths/URIs (‘/lake’, ‘s3://garage-bucket/prefix’) where ’.’ and ’/’ are load-bearing.

Example: DatasetRef.parse(“/lake::bars_1m”) # -> DatasetRef(root=/lake, name=bars_1m) ref.path # -> “/lake/bars_1m” ref.qualified # -> “/lake::bars_1m”

Fields and properties declared here; inherited members belong to the bases above.

name

name: str = Field(description='Dataset name within the root (one directory).')

partitioning

partitioning: tuple[str, ...] = Field(default=(), description='Declared partition columns (hive layout), outermost first.')

path

Read-only property.

path: str

The dataset’s location — root/name (works for paths and URIs alike).

qualified

Read-only property.

qualified: str

root

root: str = Field(description='Dataset store root — a directory or URI (s3://... included).')

parse

@classmethod
def parse(ref: DatasetRef | str) -> DatasetRef

‘root::name’ | DatasetRef -> DatasetRef.

IndexSpec

Bases: BaseModel

One index — emitted AFTER bulk loads by the index pass.

Fields and properties declared here; inherited members belong to the bases above.

columns

columns: tuple[str, ...] = Field(min_length=1, description='Indexed columns, in order.')

name

name: str | None = Field(default=None, description='Index name; derived when None.')

unique

unique: bool = Field(default=False, description='Unique index?')

where

where: str | None = Field(default=None, description='Partial-index predicate (SQL), if any.')

KeySpec

Bases: BaseModel

A table’s full identity story: PK + uniques + indexes.

conflict_key answers “what do upserts collide on by default” — the PK when present, else the first full (non-partial) unique.

Fields and properties declared here; inherited members belong to the bases above.

conflict_key

Read-only property.

conflict_key: tuple[str, ...]

has_identity

Read-only property.

has_identity: bool

Can this table upsert at all? (Keyless tables can only append.)

indexes

indexes: tuple[IndexSpec, ...] = Field(default=(), description='Plain indexes (the index pass).')

primary

primary: tuple[str, ...] = Field(default=(), description="Primary-key columns ('' = keyless).")

uniques

uniques: tuple[UniqueSpec, ...] = Field(default=(), description='Unique constraints (partials included).')

TableRef

Bases: BaseModel

One table’s address: schema + name. Frozen; renders itself.

Example: TableRef.parse(“raw.bars”) # -> TableRef(schema=raw, name=bars) ref.qualified # -> “raw.bars” ref.retired # -> TableRef for raw.bars__retired

Fields and properties declared here; inherited members belong to the bases above.

db_schema

db_schema: str = Field(description="Postgres schema (namespace), e.g. 'raw'.")

is_retired

Read-only property.

is_retired: bool

name

name: str = Field(description='Table name within the schema.')

qualified

Read-only property.

qualified: str

retired

Read-only property.

retired: TableRef

The table’s stale-row shadow (the reconcile ARCHIVE target).

parse

@classmethod
def parse(ref: TableRef | str, *, default_schema: str = 'public') -> TableRef

‘schema.table’ | ‘table’ (default schema) | TableRef -> TableRef.

UniqueSpec

Bases: BaseModel

One uniqueness rule — WHERE makes it partial (first-class, not exotic).

Fields and properties declared here; inherited members belong to the bases above.

columns

columns: tuple[str, ...] = Field(min_length=1, description='The unique column set.')

name

name: str | None = Field(default=None, description='Constraint/index name; derived when None.')

where

where: str | None = Field(default=None, description='Partial-unique predicate (SQL), if any.')