ChainedDatasetQueryResults

final class lsst.daf.butler.ChainedDatasetQueryResults(by_dataset_type: tuple[lsst.daf.butler.queries._dataset_query_results.SingleTypeDatasetQueryResults, ...])

Bases: DatasetQueryResults

A query for DatasetRef results with multiple dataset types.

Parameters:

by_dataset_typetuple [ SingleTypeDatasetQueryResults ]

Tuple of single-dataset-type query result objects to combine.

Notes

This class should never be constructed directly by users; use Query.datasets instead.

Attributes Summary

has_dimension_records

Whether all data IDs in this iterable contain dimension records.

Methods Summary

any(*[, execute, exact])	Test whether the query would return any rows.
by_dataset_type()	Group results by dataset type.
count(*[, exact, discard])	Count the number of rows this query would return.
explain_no_results([execute])	Return human-readable messages that may help explain why the query yields no results.
where(*args[, bind])	Return a query with a boolean-expression filter on its rows.
with_dimension_records()	Return a results object for which has_dimension_records is True.

Attributes Documentation

has_dimension_records

Methods Documentation

any(*, execute: bool = True, exact: bool = True) → bool

Test whether the query would return any rows.

Parameters:

executebool, optional

If True, execute at least a LIMIT 1 query if it cannot be determined prior to execution that the query would return no rows.

exactbool, optional

If True, run the full query and perform post-query filtering if needed, until at least one result row is found. If False, the returned result does not account for post-query filtering, and hence may be True even when all result rows would be filtered out.

Returns:

anybool

True if the query would (or might, depending on arguments) yield result rows. False if it definitely would not.

by_dataset_type() → Iterator[SingleTypeDatasetQueryResults]

Group results by dataset type.

Returns:

iterIterator [ SingleTypeDatasetQueryResults ]

An iterator over DatasetQueryResults instances that are each responsible for a single dataset type.

count(*, exact: bool = True, discard: bool = False) → int

Count the number of rows this query would return.

Parameters:

exactbool, optional

If True, run the full query and perform post-query filtering if needed to account for that filtering in the count. If False, the result may be an upper bound.

discardbool, optional

If True, compute the exact count even if it would require running the full query and then throwing away the result rows after counting them. If False, this is an error, as the user would usually be better off executing the query first to fetch its rows into a new query (or passing exact=False). Ignored if exact=False.

Returns:

countint

The number of rows the query would return, or an upper bound if exact=False.

explain_no_results(execute: bool = True) → Iterable[str]

Return human-readable messages that may help explain why the query yields no results.

Parameters:

executebool, optional

If True (default) execute simplified versions (e.g. LIMIT 1) of aspects of the tree to more precisely determine where rows were filtered out.

Returns:

messagesIterable [ str ]

String messages that describe reasons the query might not yield any results.

where(*args: DataCoordinate | Mapping[str, Any] | str | Predicate, bind: Mapping[str, Any] | None = None, **kwargs: Any) → ChainedDatasetQueryResults

Return a query with a boolean-expression filter on its rows.

Parameters:

*args

Constraints to apply, combined with logical AND. Arguments may be str expressions to parse, Predicate objects (these are typically constructed via expression_factory) or data IDs.

bindMapping

Mapping from string identifier appearing in a string expression to a literal value that should be substituted for it. This is recommended instead of embedding literals directly into the expression, especially for strings, timespans, or other types where quoting or formatting is nontrivial.

**kwargs

Data ID key value pairs that extend and override any present in *args.

Returns:

queryQueryBase

A new query object with the given row filters (as well as any already present in self). All row filters are combined with logical AND.

Notes

If an expression references a dimension or dimension element that is not already present in the query, it will be joined in, but dataset searches must already be joined into a query in order to reference their fields in expressions.

Data ID values are not checked for consistency; they are extracted from args and then kwargs and combined, with later values overriding earlier ones.

with_dimension_records() → ChainedDatasetQueryResults

Return a results object for which has_dimension_records is True.