Skip to content

yggdrasil.io.delta.protocol

protocol

Delta transaction-log action types.

Every line of a Delta JSON commit is exactly one action — a dict with a single top-level key naming the action type. The same shapes appear inside parquet checkpoints, expanded into typed columns.

Action types modelled here:

  • protocol — reader/writer version + named features
  • metaData — schema, partition columns, configuration
  • add — parquet file added
  • remove — parquet file logically removed
  • txn — idempotent-write marker
  • domainMetadata — per-domain named blob
  • commitInfo — operational provenance (opaque to replay)

cdc, checkpointMetadata, sidecar, and the rest of the zoo are treated as opaque — the log iterator exposes the raw payload so callers that need them can pull them out themselves.

DeltaAction

Marker base for every Delta action dataclass.

Subclasses register themselves under their JSON key on the class-level :data:ACTIONS map via :meth:__init_subclass__.

DeletionVectorDescriptor dataclass 

DeletionVectorDescriptor(
    storage_type: str,
    path_or_inline_dv: str,
    size_in_bytes: int,
    cardinality: int = 0,
    offset: Optional[int] = None,
)

Pointer to a deletion-vector blob.

Three storage shapes:

  • "i" — inline (Z85-encoded bytes in pathOrInlineDv).
  • "u" — uuid-based sidecar (deletion_vector_<uuid>.bin).
  • "p" — absolute path (table-relative).

Protocol dataclass 

Protocol(
    min_reader_version: int = 1,
    min_writer_version: int = 2,
    reader_features: List[str] = list(),
    writer_features: List[str] = list(),
)

Bases: DeltaAction

Reader / writer version requirements + named features.

Metadata dataclass 

Metadata(
    id: str = "",
    name: Optional[str] = None,
    description: Optional[str] = None,
    format_provider: str = "parquet",
    format_options: Dict[str, str] = dict(),
    schema_string: str = "",
    partition_columns: List[str] = list(),
    configuration: Dict[str, str] = dict(),
    created_time: Optional[int] = None,
)

Bases: DeltaAction

Table identity + schema + partitioning + configuration.

AddFile dataclass 

AddFile(
    path: str = "",
    partition_values: Dict[str, Optional[str]] = dict(),
    size: int = 0,
    modification_time: int = 0,
    data_change: bool = True,
    stats: Optional[str] = None,
    tags: Optional[Dict[str, str]] = None,
    deletion_vector: Optional[DeletionVectorDescriptor] = None,
    base_row_id: Optional[int] = None,
    default_row_commit_version: Optional[int] = None,
)

Bases: DeltaAction

A parquet data file added to the table at a given commit version.

RemoveFile dataclass 

RemoveFile(
    path: str = "",
    deletion_timestamp: Optional[int] = None,
    data_change: bool = True,
    extended_file_metadata: bool = False,
    partition_values: Optional[Dict[str, Optional[str]]] = None,
    size: Optional[int] = None,
    deletion_vector: Optional[DeletionVectorDescriptor] = None,
    base_row_id: Optional[int] = None,
    default_row_commit_version: Optional[int] = None,
)

Bases: DeltaAction

A previously-added parquet file logically removed at this commit.

Txn dataclass 

Txn(app_id: str = '', version: int = 0, last_updated: Optional[int] = None)

Bases: DeltaAction

Application-level idempotency record.

DomainMetadata dataclass 

DomainMetadata(
    domain: str = "", configuration: str = "", removed: bool = False
)

Bases: DeltaAction

Named per-domain configuration blob.

CommitInfo dataclass 

CommitInfo(payload: Dict[str, Any] = dict())

Bases: DeltaAction

Free-form commit metadata. Opaque to replay.

parse_action 

parse_action(line: Mapping[str, Any]) -> 'DeltaAction | None'

Dispatch one JSON commit line to its typed action.

Returns None for unknown action keys — matches the spec's forward-compatibility guidance.