GeneralQueryResults

final class lsst.daf.butler.queries.GeneralQueryResults(driver: QueryDriver, tree: QueryTree, spec: GeneralResultSpec)

Bases: QueryResultsBase

A query for DatasetRef results with a single dataset type.

Parameters:

driverQueryDriver

Implementation object that knows how to actually execute queries.

treeQueryTree

Description of the query as a tree of joins and column expressions. The instance returned directly by the Butler._query entry point should be constructed via make_unit_query_tree.

specGeneralResultSpec

Specification of the query result rows, including output columns, ordering, and slicing.

Notes

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

Attributes Summary

dimensions	All dimensions included in the query's columns.
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.
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.
iter_tuples(*dataset_types)	Iterate over result rows and return data coordinate, and dataset refs constructed from each row, and an original row.
limit([limit])	Return a new query that slices its result rows positionally.
order_by(*args)	Return a new query that yields ordered 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

dimensions

has_dimension_records

Whether all data IDs in this iterable contain 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.

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.

iter_tuples(*dataset_types: DatasetType) → Iterator[GeneralResultTuple]

Iterate over result rows and return data coordinate, and dataset refs constructed from each row, and an original row.

Parameters:

*dataset_typesDatasetType

Zero or more types of the datasets to return.

Yields:

row_tupleGeneralResultTuple

Structure containing data coordinate, refs, and a copy of the row.

limit(limit: int | None = None) → Self

Return a new query that slices its result rows positionally.

Parameters:

limitint or None, optional

Upper limit on the number of returned records. None (default) means no limit.

Returns:

resultQueryResultsBase

A sliced version of this query results object.

Notes

If this method is called multiple times, the new slice parameters replace the old ones. Slicing always occurs after sorting, even if limit is called before order_by.

order_by(*args: str | IntColumnLiteral | StringColumnLiteral | FloatColumnLiteral | HashColumnLiteral | UUIDColumnLiteral | DateTimeColumnLiteral | TimespanColumnLiteral | RegionColumnLiteral | DimensionKeyReference | DimensionFieldReference | DatasetFieldReference | UnaryExpression | BinaryExpression | Reversed | ExpressionProxy) → Self

Return a new query that yields ordered results.

Parameters:

*argsstr

Names of the columns/dimensions to use for ordering. Column name can be prefixed with minus (-) to use descending ordering.

Returns:

resultQueryResultsBase

An ordered version of this query results object.

Notes

If this method is called multiple times, the new sort terms replace the old ones.

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

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() → GeneralQueryResults

Return a results object for which has_dimension_records is True.