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: strThe dataset’s location — root/name (works for paths and URIs alike).
qualified
Read-only property.
qualified: strroot
root: str = Field(description='Dataset store root — a directory or URI (s3://... included).')parse
@classmethoddef 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: boolCan 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: boolname
name: str = Field(description='Table name within the schema.')qualified
Read-only property.
qualified: strretired
Read-only property.
retired: TableRefThe table’s stale-row shadow (the reconcile ARCHIVE target).
parse
@classmethoddef 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.')