delta_engine.schema¶

Public schema declaration surface.

Import table declarations, columns, data types, properties, and key helpers from here when defining desired Delta table schemas.

Attributes¶

Self

Classes¶

`DeltaTable`	Defines a Delta table schema.
`ForeignKey`	Public declaration of a foreign key relationship.
`Array`	Array of homogeneous `element` values.
`Binary`	Sequence-of-bytes type.
`Boolean`	Boolean truth value type.
`Byte`	8-bit signed integer type (TINYINT).
`Date`	Calendar date without time or timezone.
`Decimal`	Fixed-precision decimal type.
`Column`	Immutable column declaration preserving its authored identifier spelling.
`Double`	64-bit floating point type.
`Float`	32-bit floating point type.
`Integer`	32-bit signed integer type.
`Long`	64-bit signed integer type.
`Map`	Dictionary of `key` to `value` elements.
`Short`	16-bit signed integer type (SMALLINT).
`String`	Unicode string type.
`Struct`	Struct of named fields; identity is their ordered name, type, and nullability.
`StructField`	One named field inside a `Struct`.
`TableProperty`	The Delta table properties a user may declare on a table.
`Timestamp`	Timestamp with date and time (timezone handling is engine-specific).
`TimestampNtz`	Timestamp with date and time, no timezone.
`Variant`	Semi-structured value type (Databricks VARIANT).

Module Contents¶

class DeltaTable(catalog: str, schema: str, name: str, columns: collections.abc.Iterable[delta_engine.domain.model.DesiredColumn], comment: str = '', properties: collections.abc.Mapping[str, str | None] | None = None, tags: collections.abc.Mapping[str, str] | None = None, partitioned_by: delta_engine.domain.collection_types.ListOrTuple[str] = (), clustered_by: delta_engine.domain.collection_types.ListOrTuple[str] = (), primary_key: delta_engine.domain.collection_types.ListOrTuple[str] | None = None, foreign_keys: collections.abc.Iterable[ForeignKey] | None = None, scope: ScopeName = 'full', primary_key_name: str | None = None)¶

Defines a Delta table schema.

scope selects how much of the table the declaration manages: the whole table (default), catalog metadata, comments and tags, or tags alone.

Note on dropping columns: Delta only permits ALTER TABLE ... DROP COLUMN when delta.columnMapping.mode is name. Declare it in properties on any table whose columns may be dropped; a sync that drops a column without it fails at validation with a message naming the property.

A declaration is immutable once constructed: attribute assignment and deletion are refused, and there are no fields to reassign. This matters when declarations are shared — a package of tables one team imports from another cannot be edited in place and then synced. The state is validated exactly once, at construction, so a table that exists is a table whose declaration was accepted.

Copying is refused too: copy.copy and copy.deepcopy raise. Share the single validated instance rather than copying it.

property catalog: str¶: Unity Catalog catalog name.

property schema: str¶: Schema (database) name within the catalog.

property name: str¶: Table name.

property columns: tuple[delta_engine.domain.model.DesiredColumn, Ellipsis]¶: Declared columns, in declaration order.

property comment: str¶: Table-level comment (empty string when unset).

property properties: collections.abc.Mapping[str, str | None]¶

Declared table properties.

A None value asserts the property must be absent from the table.

property tags: collections.abc.Mapping[str, str]¶: Declared table tags.

property partitioned_by: tuple[str, Ellipsis]¶: Partition column names, in declaration order.

property clustered_by: tuple[str, Ellipsis]¶: Clustering key column names, in declaration order.

property primary_key: tuple[str, Ellipsis]¶: Column names of the primary key, in canonical order (sorted, case-insensitive).

property primary_key_name: str | None¶: Explicitly declared primary-key name, if one was supplied.

property foreign_keys: tuple[ForeignKey, Ellipsis]¶: Foreign key declarations, before lowering to domain constraints.

class ForeignKey¶

Public declaration of a foreign key relationship.

columns accepts one local column name for a single-column parent key, a list or tuple of local names for a same-name key, or an explicit {local: referenced} mapping. List, tuple, and mapping orders are irrelevant; ambiguous composite keys require the explicit form. Identifier spelling is preserved; identifiers differing only in case name the same column, and declarations differing only in column case or mapping order are equal.

name optionally requests the physical name when the constraint is created. When omitted, Databricks chooses the name. Existing constraints match by definition regardless of their physical name.

references is another DeltaTable, the Self sentinel for a self-referential key, or the referenced table’s full "catalog.schema.table" name. The referenced table must live in the same catalog as the declaring table — information_schema is per-catalog, so a cross-catalog constraint could be created but never observed afterwards. A name reference carries no primary key to resolve shorthands against, so it requires the explicit {local: referenced} mapping, and its primary-key and column-type checks happen when the sync judges the registered parent instead of at declaration time. Either way the referenced table must be part of the same sync.

Raises:

TypeError – columns or references is not one of the accepted forms.
ValueError – columns is empty or repeats a local column, name is not a valid identifier, or a name reference is not a valid catalog.schema.table name or lacks its explicit mapping.

columns: str | delta_engine.domain.collection_types.ListOrTuple[str] | collections.abc.Mapping[str, str]¶

references: DeltaTable | _SelfReference | str¶

name: str | None = None¶

Self: Final¶

class Array¶

Bases: DataType

Array of homogeneous element values.

element: DataType¶

class Binary¶

Bases: DataType

Sequence-of-bytes type.

class Boolean¶

Bases: DataType

Boolean truth value type.

class Byte¶

Bases: DataType

8-bit signed integer type (TINYINT).

class Date¶

Bases: DataType

Calendar date without time or timezone.

class Decimal¶

Bases: DataType

Fixed-precision decimal type.

Variables:

precision – Total number of digits (1-38, Delta/Spark limit).
scale – Digits to the right of the decimal point.

precision: int¶

scale: int = 0¶

class Column¶

Immutable column declaration preserving its authored identifier spelling.

Exposed to users as Column through delta_engine.schema; the domain name states the desired/observed side explicitly, mirroring ObservedColumn.

Variables:

name – Column name, stored verbatim as a case-insensitive Identifier.
data_type – Logical data type of the column.
nullable – Whether the column accepts NULL values.
comment – Optional column comment.
tags – Read-only mapping of Unity Catalog column tag keys to values. Tag keys are case-sensitive and are stored verbatim (never lowercased, unlike the column name).
renamed_from – The column’s previous name, declaring a rename. Inert unless the old name is observed and the new one is not, so it is safe to keep on declarations that continue to manage column structure, and correct on fresh environments.

name: str¶

data_type: delta_engine.domain.model.data_type.DataType¶

nullable: bool = True¶

comment: str = ''¶

tags: collections.abc.Mapping[str, str]¶

renamed_from: str | None = None¶

class Double¶

Bases: DataType

64-bit floating point type.

class Float¶

Bases: DataType

32-bit floating point type.

class Integer¶

Bases: DataType

32-bit signed integer type.

class Long¶

Bases: DataType

64-bit signed integer type.

class Map¶

Bases: DataType

Dictionary of key to value elements.

key: DataType¶

value: DataType¶

class Short¶

Bases: DataType

16-bit signed integer type (SMALLINT).

class String¶

Bases: DataType

Unicode string type.

class Struct¶

Bases: DataType

Struct of named fields; identity is their ordered name, type, and nullability.

fields: delta_engine.domain.collection_types.ListOrTuple[StructField]¶

class StructField¶

One named field inside a Struct.

Nullability is part of the field’s identity and defaults to nullable, matching Databricks SQL. Nested field comments remain unmanaged.

name: str¶

data_type: DataType¶

nullable: bool = True¶

class TableProperty¶

Bases: enum.StrEnum

The Delta table properties a user may declare on a table.

COLUMN_MAPPING_MODE = 'delta.columnMapping.mode'¶

CHANGE_DATA_FEED = 'delta.enableChangeDataFeed'¶

DELETED_FILE_RETENTION_DURATION = 'delta.deletedFileRetentionDuration'¶

LOG_RETENTION_DURATION = 'delta.logRetentionDuration'¶

DATA_SKIPPING_NUM_INDEXED_COLS = 'delta.dataSkippingNumIndexedCols'¶

TYPE_WIDENING = 'delta.enableTypeWidening'¶

class Timestamp¶

Bases: DataType

Timestamp with date and time (timezone handling is engine-specific).

class TimestampNtz¶

Bases: DataType

Timestamp with date and time, no timezone.

required_feature: ClassVar[delta_engine.domain.model.feature.TableFeature]¶

class Variant¶

Bases: DataType

Semi-structured value type (Databricks VARIANT).

required_feature: ClassVar[delta_engine.domain.model.feature.TableFeature]¶