Engine¶

class lsst.daf.relation.iteration.Engine(*, name: str = 'iteration', functions: dict[str, _F] = <factory>, relation_name_counter: int = 0)¶

Bases: GenericConcreteEngine[Callable[…, Any]]

A concrete engine that treats relations as iterables with Mapping rows.

See the iteration module documentation for details.

Attributes Summary

`name`	Name of the engine; primarily used for display purposes (`str`).
`relation_name_counter`	An integer counter used to generate relation names (`int`).

Methods Summary

`append_binary`(operation, lhs, rhs)	Hook for maintaining the engine's `conform` invariants through `BinaryOperation.apply`.
`append_unary`(operation, target)	Hook for maintaining the engine's `conform` invariants through `UnaryOperation.apply`.
`apply_custom_unary_operation`(operation, target)	Convert a custom `UnaryOperation` to a `RowIterable`.
`backtrack_unary`(operation, tree, preferred)	Attempt to insert a unary operation in another engine upstream of this one by via operation commutators.
`conform`(relation)	Ensure a relation tree satisfies this engine's invariants.
`convert_column_container`(expression)	Convert a `ColumnContainer` to a Python callable.
`convert_column_expression`(expression)	Convert a `ColumnExpression` to a Python callable.
`convert_predicate`(predicate)	Convert a `Predicate` to a Python callable.
`execute`(relation)	Execute a native iteration relation, returning a Python iterable.
`get_doomed_payload`(columns)	Return a `payload` for a leaf relation that has no rows.
`get_function`(name)	Return the named column expression function.
`get_join_identity_payload`()	Return a `payload` for a leaf relation that is the `join identity`.
`get_relation_name`([prefix])	Return a name suitable for a new relation in this engine.
`make_doomed_relation`(columns, messages[, name])	Construct a leaf relation with no rows and one or more messages explaining why.
`make_join_identity_relation`([name])	Construct a leaf relation with no columns and exactly one row.
`make_leaf`(columns, payload, *[, name, ...])	Create a nontrivial leaf relation in this engine.
`materialize`(target[, name, name_prefix])	Mark that a target relation's payload should be cached.
`transfer`(target[, payload])	Mark that a relation's payload should be transferred from some other engine to this one.

Attributes Documentation

name: str = 'iteration'¶: Name of the engine; primarily used for display purposes (str).

relation_name_counter: int = 0¶: An integer counter used to generate relation names (int).

Methods Documentation

append_binary(operation: BinaryOperation, lhs: Relation, rhs: Relation) → Relation¶

Hook for maintaining the engine’s conform invariants through BinaryOperation.apply.

This method should only be called by BinaryOperation.apply and the engine’s own methods and helper classes. External code should call BinaryOperation.apply or a Relation factory method instead.

Parameters:

operationBinaryOperation: Operation to apply; should already be filtered through BinaryOperation._begin_apply.
lhsRelation: One relation to apply the operation to directly.
rhsRelation: The other relation to apply the operation to directly.

Returns:

relationRelation: Relation that includes the given operation acting on lhs and rhs, or a simplified equivalent.

Notes

Implementations should delegate back to UnaryOperation._finish_apply to actually create a UnaryOperationRelation and perform final simplification and checks. This is all the default implementation does.

append_unary(operation: UnaryOperation, target: Relation) → Relation¶

Hook for maintaining the engine’s conform invariants through UnaryOperation.apply.

This method should only be called by UnaryOperation.apply and the engine’s own methods and helper classes. External code should call UnaryOperation.apply or a Relation factory method instead.

Parameters:

operationUnaryOperation: Operation to apply; should already be filtered through UnaryOperation._begin_apply.
targetRelation: Relation to apply the operation to directly.

Returns:

relationRelation: Relation that includes the given operation acting on target, or a simplified equivalent.

Notes

Implementations should delegate back to UnaryOperation._finish_apply to actually create a UnaryOperationRelation and perform final simplification and checks. This is all the default implementation does.

apply_custom_unary_operation(operation: UnaryOperation, target: Relation) → RowIterable¶

Convert a custom UnaryOperation to a RowIterable.

This method must be implemented in a subclass engine in order to support any custom UnaryOperation.

Parameters:

operationUnaryOperation: Operation to apply. Guaranteed to be a Marker, Reordering, or RowFilter subclass.
targetRelation: Target of the unary operation. Typically this will be passed to execute and the result used to construct a new RowIterable.

Returns:

rowsRowIterable: Iterable over rows, with each row a mapping keyed by ColumnTag.

backtrack_unary(operation: UnaryOperation, tree: Relation, preferred: Engine) → tuple[lsst.daf.relation._relation.Relation, bool, tuple[str, ...]]¶

Attempt to insert a unary operation in another engine upstream of this one by via operation commutators.

Parameters:

operationUnaryOperation: Unary operation to apply.
treeRelation: Relation tree the operation logically acts on; any upstream insertion of the given operation should be equivalent to applying it to the root of this tree. Caller guarantees that tree.engine == self.
preferredEngine: Engine in which the operation or its commuted equivalent should be performed.

Returns:

new_treeRelation: Possibly-updated relation tree.
donebool: If True, the operation has been fully inserted upstream in the preferred engine. If False, either tree was returned unmodified or only a part of the operation (e.g. a projection whose columns are superset of the given projection’s) was inserted upstream.
messagesSequence [ str ]: Messages explaining why backtracking insertion was unsuccessful or incomplete. Should be sentences with no trailing . and no capitalization; they will be joined with semicolons.

conform(relation: Relation) → Relation¶

Ensure a relation tree satisfies this engine’s invariants.

This can include reordering operations (in a way consistent with their commutators) and/or inserting MarkerRelation nodes.

Parameters:

relationRelation: Original relation tree.

Returns:

conformedRelation: Relation tree that satisfies this engine’s invariants.

Notes

The default implementation returns the given relation. Engines with a non-trivial conform implementation should always call it on any relations they are passed, as algorithms that process the relation tree are not guaranteed to maintain those invariants themselves. It is recommended to use a custom MarkerRelation to indicate trees that satisfy invariants, allowing the corresponding conform implementation to short-circuit quickly.

convert_column_container(expression: ColumnContainer) → Callable[[Mapping[ColumnTag, Any]], Container]¶

Convert a ColumnContainer to a Python callable.

Parameters:

expressionColumnContainer: Expression to convert.

Returns:

callable: Callable that takes a single Mapping argument (with ColumnTag keys and regular Python values, representing a row in a relation), returning the evaluated expression as collections.abc.Container instance.

convert_column_expression(expression: ColumnExpression) → Callable[[Mapping[ColumnTag, Any]], Any]¶

Convert a ColumnExpression to a Python callable.

Parameters:

expressionColumnExpression: Expression to convert.

Returns:

callable: Callable that takes a single Mapping argument (with ColumnTag keys and regular Python values, representing a row in a relation), returning the evaluated expression as another regular Python value.

convert_predicate(predicate: Predicate) → Callable[[Mapping[ColumnTag, Any]], bool]¶

Convert a Predicate to a Python callable.

Parameters:

predicatePredicate: Expression to convert.

Returns:

callable: Callable that takes a single Mapping argument (with ColumnTag keys and regular Python values, representing a row in a relation), returning the evaluated expression as a bool.

execute(relation: Relation) → RowIterable¶

Execute a native iteration relation, returning a Python iterable.

Parameters:

relationRelation: Relation to execute.

Returns:

rowsRowIterable: Iterable over rows, with each row a mapping keyed by ColumnTag.

Notes

This method does not in general iterate over the relation’s rows; while some operations like Sort and Deduplication do require processing all rows up front (which will happen during a call to execute), most return lazy iterables that do little or nothing until actually iterated over.

This method requires all relations in the tree to have the same engine (self). Use the Processor class to handle trees with multiple engines.

get_doomed_payload(columns: Set[ColumnTag]) → RowIterable¶

Return a payload for a leaf relation that has no rows.

Parameters:

columnsSet [ ColumnTag ]: The columns the relation should have.

Returns:

payload: The engine-specific content for this relation.

get_function(name: str) → _F | None¶

Return the named column expression function.

Parameters:

namestr: Name of the function, from ColumnFunction.name or PredicateFunction.name

Returns:

function: Engine-specific callable, or None if no match was found.

Notes

This implementation first looks for a symbol with this name in the built-in operator module, to handle the common case (shared by both the iteration and sql engines) where these functions are appropriate for the engine due to operator overloading. When this fails, the name is looked up in the functions attribute.

get_join_identity_payload() → RowIterable¶

Return a payload for a leaf relation that is the join identity.

Returns:

payload: The engine-specific content for this relation.

get_relation_name(prefix: str = 'leaf') → str¶

Return a name suitable for a new relation in this engine.

Parameters:

prefixstr, optional: Prefix to include in the returned name.

Returns:

namestr: Name for the relation; guaranteed to be unique over all of the relations in this engine.

Notes

This implementation combines the given prefix with both the current relation_name_counter value and a random hexadecimal suffix.

make_doomed_relation(columns: Set[ColumnTag], messages: Sequence[str], name: str = '0') → Relation¶

Construct a leaf relation with no rows and one or more messages explaining why.

Parameters:

columnsSet [ ColumnTag ]: The columns in this relation.
messagesSequence [ str ]: One or more messages explaining why the relation has no rows.
namestr, optional: Name used to identify and reconstruct this relation.

Returns:

relationRelation: Doomed relation.

Notes

This is simplify a convenience method that delegates to LeafRelation.make_doomed. Derived engines with a nontrivial conform should override this method to conform the return value.

make_join_identity_relation(name: str = 'I') → Relation¶

Construct a leaf relation with no columns and exactly one row.

Parameters:

engineEngine: The engine that is responsible for interpreting this relation.
namestr, optional: Name used to identify and reconstruct this relation.

Returns:

relationRelation: Relation with no columns and one row.

make_leaf(columns: Set[ColumnTag], payload: MaterializedRowIterable, *, name: str = '', messages: Sequence[str] = (), name_prefix: str = 'leaf', parameters: Any = None) → LeafRelation¶

Create a nontrivial leaf relation in this engine.

This is a convenience method that simply forwards all arguments to the LeafRelation constructor; see that class for details.

materialize(target: Relation, name: str | None = None, name_prefix: str = 'materialization_') → Relation¶

Mark that a target relation’s payload should be cached.

Parameters:

targetRelation: Relation to mark.
namestr, optional: Name to use for the cached payload within the engine.
name_prefixstr, optional: Prefix to pass to get_relation_name; ignored if name is provided.

Returns:

relationRelation: New relation that marks its upstream tree for caching, unless the materialization was simplified away.

Navigation

Engine¶