Join¶

class lsst.daf.relation.Join(predicate: lsst.daf.relation._columns._predicate.Predicate = <factory>, min_columns: frozenset = frozenset(), max_columns: Optional[frozenset, None] = None)¶

Bases: lsst.daf.relation.BinaryOperation

A natural join operation.

A natural join combines two relations by matching rows with the same values in their common columns (and satisfying an optional column expression, via a Predicate), producing a new relation whose columns are the union of the columns of its operands. This is equivalent to [INNER] JOIN in SQL.

Attributes Summary

`common_columns`	The common columns between relations that will be used as an equality constraint (`Set` [ `ColumnTag` ]).
`max_columns`	The maximal set of columns that should be used in the equality constraint on `common_columns` (`frozenset` [ `ColumnTag` ] or `None`).
`min_columns`	The minimal set of columns that should be used in the equality constraint on `common_columns` (`frozenset` [ `ColumnTag` ]).

Methods Summary

`applied_columns`(lhs, rhs)	Return the columns of the relation that results from applying this operation to the given targets.
`applied_common_columns`(lhs, rhs)	Compute the actual common columns for a `Join` given its targets.
`applied_max_rows`(lhs, rhs)	Return the maximum number of rows of the relation that results from applying this operation to the given target.
`applied_min_rows`(lhs, rhs)	Return the minimum number of rows of the relation that results from applying this operation to the given targets.
`apply`(lhs, rhs)	Create a new relation that represents the action of this operation on a pair of existing relations.
`partial`(fix, is_lhs)	Return a `UnaryOperation` that represents this join with one operand already provided and held fixed.

Attributes Documentation

common_columns¶

The common columns between relations that will be used as an equality constraint (Set [ ColumnTag ]).

This attribute is not available on Join instances for which min_columns is not the same as max_columns. It is always available on any Join instance attached to a BinaryOperationRelation by apply.

max_columns = None¶

The maximal set of columns that should be used in the equality constraint on common_columns (frozenset [ ColumnTag ] or None).

If the relations this operation is applied to have more columns in common than this set, they will not be included in the equality constraint.

This is guaranteed to be equal to min_columns on any Join instance attached to a BinaryOperationRelation by apply.

min_columns = frozenset()¶

The minimal set of columns that should be used in the equality constraint on common_columns (frozenset [ ColumnTag ]).

If the relations this operation is applied to have common columsn that are not a superset of this set, ColumnError will be raised by apply.

This is guaranteed to be equal to max_columns on any Join instance attached to a BinaryOperationRelation by apply.

Methods Documentation

applied_columns(lhs: Relation, rhs: Relation) → Set[ColumnTag]¶

Return the columns of the relation that results from applying this operation to the given targets.

Parameters:	lhs : `Relation` On relation the operation will act on. rhs : `Relation` The other relation the operation will act on.
Returns:	columns : `Set` [ `ColumnTag` ] Columns the new relation would have.

applied_common_columns(lhs: Relation, rhs: Relation) → frozenset[ColumnTag]¶

Compute the actual common columns for a Join given its targets.

Parameters:	lhs : `Relation` One relation to join. rhs : `Relation` The other relation to join to `lhs`.
Returns:	common_columns : `Set` [ `ColumnTag` ] Columns that are included in all of `lhs.columns` and `rhs.columns` and `max_columns`, checked to be a superset of `min_columns`.
Raises:	ColumnError Raised if the result would not be a superset of `min_columns`.

applied_max_rows(lhs: Relation, rhs: Relation) → int | None¶

Return the maximum number of rows of the relation that results from applying this operation to the given target.

Parameters:	lhs : `Relation` On relation the operation will act on. rhs : `Relation` The other relation the operation will act on.
Returns:	max_rows : `int` or `None` Maximum number of rows the new relation would have.

applied_min_rows(lhs: Relation, rhs: Relation) → int¶

Return the minimum number of rows of the relation that results from applying this operation to the given targets.

Parameters:	lhs : `Relation` On relation the operation will act on. rhs : `Relation` The other relation the operation will act on.
Returns:	min_rows : `int` Minimum number of rows the new relation would have.

apply(lhs: lsst.daf.relation._relation.Relation, rhs: lsst.daf.relation._relation.Relation) → lsst.daf.relation._relation.Relation¶

Create a new relation that represents the action of this operation on a pair of existing relations.

Parameters:	lhs : `Relation` One relation the operation will act on. rhs : `Relation` The other relation the operation will act on.
Returns:	new_relation : `Relation` Relation that includes this operation. This may be `self` if the operation is a no-op, and it may not be a `BinaryOperationRelation` holding this operation (or even a similar one) if the operation was inserted earlier in the tree via commutation relations.
Raises:	ColumnError Raised if the operation could not be applied due to problems with the target relations’ columns. EngineError Raised if the operation could not be applied due to problems with the target relations’ engine(s).

partial(fix: Relation, is_lhs: bool = False) → PartialJoin¶

Return a UnaryOperation that represents this join with one operand already provided and held fixed.

Parameters:	fix : `Relation` Relation to include in the returned unary operation. is_lhs : `bool`, optional Whether `fix` should be considered the `lhs` or `rhs` side of the join (`Join` side is usually irrelevant, but `Engine` implementations are permitted to make additional guarantees about row order or duplicates based on them).
Returns:	partial_join : `PartialJoin` Unary operation representing a join to a fixed relation.
Raises:	ColumnError Raised if the given predicate requires columns not present in `lhs` or `rhs`. RowOrderError Raised if `lhs` or `rhs` is unnecessarily ordered; see `Relation.expect_unordered`.

Notes

This method and the class it returns are called “partial” in the spirit of functools.partial: a callable formed by holding some arguments to another callable fixed.

Navigation

Join¶