DimensionRecordQueryResults

class lsst.daf.butler.registry.queries.DimensionRecordQueryResults

Bases: collections.abc.Iterable, typing.Generic

An interface for objects that represent the results of queries for dimension records.

Methods Summary

any(*, execute, exact)	Test whether this query returns any results.
count(*, exact)	Count the number of rows this query would return.
explain_no_results()	Return human-readable messages that may help explain why the query yields no results.
limit(limit, offset, None] = None)	Make the iterator return limited number of records.
order_by(*args)	Make the iterator return ordered result.

Methods Documentation

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

Test whether this query returns any results.

Parameters:

execute : bool, 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.

exact : bool, 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:

any : bool

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

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

Count the number of rows this query would return.

Parameters:

exact : bool, 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.

Returns:

count : int

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

Notes

This counts the number of rows returned, not the number of unique rows returned, so even with exact=True it may provide only an upper bound on the number of deduplicated result rows.

explain_no_results() → Iterator[str]

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

Returns:

messages : Iterator [ str ]

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

Notes

Messages related to post-query filtering are only available if the iterator has been exhausted, or if any or count was already called (with exact=True for the latter two).

This method first yields messages that are generated while the query is being built or filtered, but may then proceed to diagnostics generated by performing what should be inexpensive follow-up queries. Callers can short-circuit this at any time by simply not iterating further.

limit(limit: int, offset: Optional[int, None] = None) → lsst.daf.butler.registry.queries._results.DimensionRecordQueryResults

Make the iterator return limited number of records.

Parameters:

limit : int

Upper limit on the number of returned records.

offset : int or None

If not None then the number of records to skip before returning limit records.

Returns:

result : DimensionRecordQueryResults

Returns self instance which is updated to return limited set of records.

Notes

This method can modify the iterator in place and return the same instance. Normally this method is used together with order_by method.

order_by(*args) → lsst.daf.butler.registry.queries._results.DimensionRecordQueryResults

Make the iterator return ordered result.

Parameters:

*args : str

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

Returns:

result : DimensionRecordQueryResults

Returns self instance which is updated to return ordered result.

Notes

This method can modify the iterator in place and return the same instance.