QueryBase

class lsst.daf.butler.queries.QueryBase(driver: QueryDriver, tree: QueryTree)

Bases: ABC

Common base class for Query and all QueryResult objects.

This class should rarely be referenced directly; it is public only because it provides public methods to its subclasses.

Parameters:

driverQueryDriver

Implementation object that knows how to actually execute queries.

treeQueryTree

Description of the query as a tree of joins and column expressions.

Methods Summary

any(*[, execute, exact])	Test whether the query would return any rows.
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.

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.

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.

abstract 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 Query.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

Expressions referring to dimensions or dimension elements are resolved automatically. References to dataset fields (see expression_factory for the distinction) may or may not be resolvable, depending on the implementation class.

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