Types

Versioning Engine

metaxy.versioning.types.LazyIncrement

Bases: NamedTuple

Result of an incremental update containing lazy dataframes.

Contains three sets of samples: - added: New samples from upstream not present in current metadata - changed: Samples with different provenance - removed: Samples in current metadata but not in upstream state

Functions

metaxy.versioning.types.LazyIncrement.collect

collect() -> Increment

Collect all lazy frames to eager DataFrames.

Source code in src/metaxy/versioning/types.py

def collect(self) -> Increment:
    """Collect all lazy frames to eager DataFrames."""
    return Increment(
        added=self.added.collect(),
        changed=self.changed.collect(),
        removed=self.removed.collect(),
    )

metaxy.versioning.types.Increment

Bases: NamedTuple

Result of an incremental update containing eager dataframes.

Contains three sets of samples: - added: New samples from upstream not present in current metadata - changed: Samples with different provenance - removed: Samples in current metadata but not in upstream state

Functions

metaxy.versioning.types.Increment.collect

collect() -> Increment

No-op for eager Increment (already collected).

Source code in src/metaxy/versioning/types.py

def collect(self) -> "Increment":
    """No-op for eager Increment (already collected)."""
    return self

metaxy.HashAlgorithm

Bases: Enum

Supported hash algorithms for field provenance calculation.

These algorithms are chosen for: - Speed (non-cryptographic hashes preferred) - Cross-database availability - Good collision resistance for field provenance calculation

Attributes

metaxy.HashAlgorithm.XXHASH64 class-attribute instance-attribute

XXHASH64 = 'xxhash64'

metaxy.HashAlgorithm.XXHASH32 class-attribute instance-attribute

XXHASH32 = 'xxhash32'

metaxy.HashAlgorithm.WYHASH class-attribute instance-attribute

WYHASH = 'wyhash'

metaxy.HashAlgorithm.SHA256 class-attribute instance-attribute

SHA256 = 'sha256'

metaxy.HashAlgorithm.MD5 class-attribute instance-attribute

MD5 = 'md5'

metaxy.HashAlgorithm.FARMHASH class-attribute instance-attribute

FARMHASH = 'farmhash'

Keys

Types for working with feature and field keys.

Canonical Keys

metaxy.FeatureKey

FeatureKey(parts: str)

FeatureKey(parts: Sequence[str])

FeatureKey(parts: FeatureKey)

FeatureKey(parts: str | Sequence[str] | FeatureKey)

Bases: _Key

Feature key as a sequence of string parts.

Hashable for use as dict keys in registries. Parts cannot contain forward slashes (/) or double underscores (__).

Example:

```py
FeatureKey("a/b/c")  # String format
# FeatureKey(parts=['a', 'b', 'c'])

FeatureKey(["a", "b", "c"])  # List format
# FeatureKey(parts=['a', 'b', 'c'])

FeatureKey(FeatureKey(["a", "b", "c"]))  # FeatureKey copy
# FeatureKey(parts=['a', 'b', 'c'])
```

Source code in src/metaxy/models/types.py

def __init__(  # pyright: ignore[reportMissingSuperCall]
    self,
    parts: str | Sequence[str] | FeatureKey,
) -> None: ...

Attributes

metaxy.FeatureKey.parts property

parts: tuple[str, ...]

Backward compatibility property for accessing root as parts.

metaxy.FeatureKey.table_name property

table_name: str

Get SQL-like table name for this feature key.

Replaces hyphens with underscores for SQL compatibility.

Functions

metaxy.FeatureKey.to_string

to_string() -> str

Convert to string representation with "/" separator.

Source code in src/metaxy/models/types.py

def to_string(self) -> str:
    """Convert to string representation with "/" separator."""
    return KEY_SEPARATOR.join(self.parts)

metaxy.FeatureKey.to_struct_key

to_struct_key() -> str

Convert to a name that can be used as struct key in databases

Source code in src/metaxy/models/types.py

def to_struct_key(self) -> str:
    """Convert to a name that can be used as struct key in databases"""
    return "_".join(self.parts)

metaxy.FeatureKey.__repr__

__repr__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __repr__(self) -> str:
    """Return string representation."""
    return self.to_string()

metaxy.FeatureKey.__str__

__str__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __str__(self) -> str:
    """Return string representation."""
    return self.to_string()

metaxy.FeatureKey.__lt__

__lt__(other: Any) -> bool

Less than comparison for sorting.

Source code in src/metaxy/models/types.py

def __lt__(self, other: Any) -> bool:
    """Less than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts < other.parts
    return NotImplemented

metaxy.FeatureKey.__le__

__le__(other: Any) -> bool

Less than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __le__(self, other: Any) -> bool:
    """Less than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts <= other.parts
    return NotImplemented

metaxy.FeatureKey.__gt__

__gt__(other: Any) -> bool

Greater than comparison for sorting.

Source code in src/metaxy/models/types.py

def __gt__(self, other: Any) -> bool:
    """Greater than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts > other.parts
    return NotImplemented

metaxy.FeatureKey.__ge__

__ge__(other: Any) -> bool

Greater than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __ge__(self, other: Any) -> bool:
    """Greater than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts >= other.parts
    return NotImplemented

metaxy.FeatureKey.__iter__

__iter__() -> Iterator[str]

Return iterator over parts.

Source code in src/metaxy/models/types.py

def __iter__(self) -> Iterator[str]:  # pyright: ignore[reportIncompatibleMethodOverride]
    """Return iterator over parts."""
    return iter(self.parts)

metaxy.FeatureKey.__getitem__

__getitem__(index: int) -> str

Get part by index.

Source code in src/metaxy/models/types.py

def __getitem__(self, index: int) -> str:
    """Get part by index."""
    return self.parts[index]

metaxy.FeatureKey.__len__

__len__() -> int

Get number of parts.

Source code in src/metaxy/models/types.py

def __len__(self) -> int:
    """Get number of parts."""
    return len(self.parts)

metaxy.FeatureKey.__contains__

__contains__(item: str) -> bool

Check if part is in key.

Source code in src/metaxy/models/types.py

def __contains__(self, item: str) -> bool:
    """Check if part is in key."""
    return item in self.parts

metaxy.FeatureKey.__reversed__

__reversed__()

Return reversed iterator over parts.

Source code in src/metaxy/models/types.py

def __reversed__(self):
    """Return reversed iterator over parts."""
    return reversed(self.parts)

metaxy.FeatureKey.model_dump

model_dump(**kwargs: Any) -> Any

Serialize to list format for backward compatibility.

Source code in src/metaxy/models/types.py

def model_dump(self, **kwargs: Any) -> Any:
    """Serialize to list format for backward compatibility."""
    # When serializing this key, return it as a list of parts
    # instead of the full Pydantic model structure
    return list(self.parts)

metaxy.FeatureKey.__hash__

__hash__() -> int

Return hash for use as dict keys.

Source code in src/metaxy/models/types.py

def __hash__(self) -> int:
    """Return hash for use as dict keys."""
    return hash(self.parts)

metaxy.FeatureKey.__eq__

__eq__(other: Any) -> bool

Check equality with another instance.

Source code in src/metaxy/models/types.py

def __eq__(self, other: Any) -> bool:
    """Check equality with another instance."""
    if isinstance(other, self.__class__):
        return self.parts == other.parts
    return super().__eq__(other)

metaxy.FeatureKey.to_column_suffix

to_column_suffix() -> str

Convert to a suffix usable for database column names (typically temporary).

Source code in src/metaxy/models/types.py

def to_column_suffix(self) -> str:
    """Convert to a suffix usable for database column names (typically temporary)."""
    return "__" + "_".join(self.parts)

metaxy.FieldKey

FieldKey(parts: str)

FieldKey(parts: Sequence[str])

FieldKey(parts: FieldKey)

FieldKey(parts: str | Sequence[str] | FieldKey)

Bases: _Key

Field key as a sequence of string parts.

Hashable for use as dict keys in registries. Parts cannot contain forward slashes (/) or double underscores (__).

Example:

```py
FieldKey("a/b/c")  # String format
# FieldKey(parts=['a', 'b', 'c'])

FieldKey(["a", "b", "c"])  # List format
# FieldKey(parts=['a', 'b', 'c'])

FieldKey(FieldKey(["a", "b", "c"]))  # FieldKey copy
# FieldKey(parts=['a', 'b', 'c'])
```

Source code in src/metaxy/models/types.py

def __init__(  # pyright: ignore[reportMissingSuperCall]
    self,
    parts: str | Sequence[str] | FieldKey,
) -> None: ...

Attributes

metaxy.FieldKey.parts property

parts: tuple[str, ...]

Backward compatibility property for accessing root as parts.

metaxy.FieldKey.table_name property

table_name: str

Get SQL-like table name for this feature key.

Replaces hyphens with underscores for SQL compatibility.

Functions

metaxy.FieldKey.to_string

to_string() -> str

Convert to string representation with "/" separator.

Source code in src/metaxy/models/types.py

def to_string(self) -> str:
    """Convert to string representation with "/" separator."""
    return KEY_SEPARATOR.join(self.parts)

metaxy.FieldKey.to_struct_key

to_struct_key() -> str

Convert to a name that can be used as struct key in databases

Source code in src/metaxy/models/types.py

def to_struct_key(self) -> str:
    """Convert to a name that can be used as struct key in databases"""
    return "_".join(self.parts)

metaxy.FieldKey.to_column_suffix

to_column_suffix() -> str

Convert to a suffix usable for database column names (typically temporary).

Source code in src/metaxy/models/types.py

def to_column_suffix(self) -> str:
    """Convert to a suffix usable for database column names (typically temporary)."""
    return "__" + "_".join(self.parts)

metaxy.FieldKey.__repr__

__repr__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __repr__(self) -> str:
    """Return string representation."""
    return self.to_string()

metaxy.FieldKey.__str__

__str__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __str__(self) -> str:
    """Return string representation."""
    return self.to_string()

metaxy.FieldKey.__lt__

__lt__(other: Any) -> bool

Less than comparison for sorting.

Source code in src/metaxy/models/types.py

def __lt__(self, other: Any) -> bool:
    """Less than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts < other.parts
    return NotImplemented

metaxy.FieldKey.__le__

__le__(other: Any) -> bool

Less than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __le__(self, other: Any) -> bool:
    """Less than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts <= other.parts
    return NotImplemented

metaxy.FieldKey.__gt__

__gt__(other: Any) -> bool

Greater than comparison for sorting.

Source code in src/metaxy/models/types.py

def __gt__(self, other: Any) -> bool:
    """Greater than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts > other.parts
    return NotImplemented

metaxy.FieldKey.__ge__

__ge__(other: Any) -> bool

Greater than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __ge__(self, other: Any) -> bool:
    """Greater than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts >= other.parts
    return NotImplemented

metaxy.FieldKey.__iter__

__iter__() -> Iterator[str]

Return iterator over parts.

Source code in src/metaxy/models/types.py

def __iter__(self) -> Iterator[str]:  # pyright: ignore[reportIncompatibleMethodOverride]
    """Return iterator over parts."""
    return iter(self.parts)

metaxy.FieldKey.__getitem__

__getitem__(index: int) -> str

Get part by index.

Source code in src/metaxy/models/types.py

def __getitem__(self, index: int) -> str:
    """Get part by index."""
    return self.parts[index]

metaxy.FieldKey.__len__

__len__() -> int

Get number of parts.

Source code in src/metaxy/models/types.py

def __len__(self) -> int:
    """Get number of parts."""
    return len(self.parts)

metaxy.FieldKey.__contains__

__contains__(item: str) -> bool

Check if part is in key.

Source code in src/metaxy/models/types.py

def __contains__(self, item: str) -> bool:
    """Check if part is in key."""
    return item in self.parts

metaxy.FieldKey.__reversed__

__reversed__()

Return reversed iterator over parts.

Source code in src/metaxy/models/types.py

def __reversed__(self):
    """Return reversed iterator over parts."""
    return reversed(self.parts)

metaxy.FieldKey.model_dump

model_dump(**kwargs: Any) -> Any

Serialize to list format for backward compatibility.

Source code in src/metaxy/models/types.py

def model_dump(self, **kwargs: Any) -> Any:
    """Serialize to list format for backward compatibility."""
    # When serializing this key, return it as a list of parts
    # instead of the full Pydantic model structure
    return list(self.parts)

metaxy.FieldKey.__hash__

__hash__() -> int

Return hash for use as dict keys.

Source code in src/metaxy/models/types.py

def __hash__(self) -> int:
    """Return hash for use as dict keys."""
    return hash(self.parts)

metaxy.FieldKey.__eq__

__eq__(other: Any) -> bool

Check equality with another instance.

Source code in src/metaxy/models/types.py

def __eq__(self, other: Any) -> bool:
    """Check equality with another instance."""
    if isinstance(other, self.__class__):
        return self.parts == other.parts
    return super().__eq__(other)

Type Annotations

These are typically used to annotate function parameters. Most APIs in Metaxy accepts them and perform type coercion into canonical types.

metaxy.CoercibleToFeatureKey module-attribute

CoercibleToFeatureKey: TypeAlias = str | Sequence[str] | FeatureKey | type['BaseFeature']

metaxy.CoercibleToFieldKey module-attribute

CoercibleToFieldKey: TypeAlias = str | Sequence[str] | FieldKey

Pydantic Type Annotations

These types are used for type coercion into canonical types with Pydantic.

metaxy.ValidatedFeatureKey module-attribute

ValidatedFeatureKey: TypeAlias = FeatureKey

metaxy.ValidatedFieldKey module-attribute

ValidatedFieldKey: TypeAlias = FieldKey

metaxy.ValidatedFeatureKeySequence module-attribute

ValidatedFeatureKeySequence: TypeAlias = Sequence[ValidatedFeatureKey]

metaxy.ValidatedFieldKeySequence module-attribute

ValidatedFieldKeySequence: TypeAlias = Sequence[ValidatedFieldKey]

Adapters

These can perform type coercsion into canonical types in non-pydantic code.

metaxy.ValidatedFeatureKeyAdapter module-attribute

ValidatedFeatureKeyAdapter: TypeAdapter[ValidatedFeatureKey] = TypeAdapter(ValidatedFeatureKey)

metaxy.ValidatedFeatureKeySequenceAdapter module-attribute

ValidatedFeatureKeySequenceAdapter: TypeAdapter[ValidatedFeatureKeySequence] = TypeAdapter(ValidatedFeatureKeySequence)

metaxy.ValidatedFieldKeyAdapter module-attribute

ValidatedFieldKeyAdapter: TypeAdapter[ValidatedFieldKey] = TypeAdapter(ValidatedFieldKey)

metaxy.ValidatedFieldKeySequenceAdapter module-attribute

ValidatedFieldKeySequenceAdapter: TypeAdapter[ValidatedFieldKeySequence] = TypeAdapter(ValidatedFieldKeySequence)

Other Types

metaxy.models.types.SnapshotPushResult

Bases: NamedTuple

Result of recording a feature graph snapshot.

Attributes:

• snapshot_version (str) –

  The deterministic hash of the graph snapshot

• already_pushed (bool) –

  True if this snapshot_version was already pushed previously

• updated_features (list[str]) –

  List of feature keys with updated information (changed full_definition_version)

metaxy.IDColumns module-attribute

IDColumns: TypeAlias = Sequence[str]