DatasetQueryResults¶
- class lsst.daf.butler.registry.queries.DatasetQueryResults¶
Bases:
Iterable
[DatasetRef
]An interface for objects that represent the results of queries for datasets.
Methods Summary
any
(*[, execute, exact])Test whether this query returns any results.
Group results by parent dataset type.
count
(*[, exact])Count the number of rows this query would return.
expanded
()Return a
DatasetQueryResults
for whichDataCoordinate.hasRecords
returnsTrue
for all data IDs in returnedDatasetRef
objects.Return human-readable messages that may help explain why the query yields no results.
Insert this query's results into a temporary table.
Methods Documentation
- abstract any(*, execute: bool = True, exact: bool = True) bool ¶
Test whether this query returns any results.
- Parameters:
- execute
bool
, optional If
True
, execute at least aLIMIT 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. IfFalse
, the returned result does not account for post-query filtering, and hence may beTrue
even when all result rows would be filtered out.
- execute
- Returns:
- abstract byParentDatasetType() Iterator[ParentDatasetQueryResults] ¶
Group results by parent dataset type.
- Returns:
- iter
Iterator
[ParentDatasetQueryResults
] An iterator over
DatasetQueryResults
instances that are each responsible for a single parent dataset type (either just that dataset type, one or more of its component dataset types, or both).
- iter
- abstract count(*, exact: bool = True) int ¶
Count the number of rows this query would return.
- Parameters:
- Returns:
- count
int
The number of rows the query would return, or an upper bound if
exact=False
.
- count
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.
- abstract expanded() DatasetQueryResults ¶
Return a
DatasetQueryResults
for whichDataCoordinate.hasRecords
returnsTrue
for all data IDs in returnedDatasetRef
objects.- Returns:
- expanded
DatasetQueryResults
Either a new
DatasetQueryResults
instance orself
, if it is already expanded.
- expanded
Notes
As with
DataCoordinateQueryResults.expanded
, it may be more efficient to callmaterialize
before expanding data IDs for very large result sets.
- abstract 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.
- messages
Notes
Messages related to post-query filtering are only available if the iterator has been exhausted, or if
any
orcount
was already called (withexact=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 simplying not iterating further.
- abstract materialize() ContextManager[DatasetQueryResults] ¶
Insert this query’s results into a temporary table.
- Returns:
- context
typing.ContextManager
[DatasetQueryResults
] A context manager that ensures the temporary table is created and populated in
__enter__
(returning a results object backed by that table), and dropped in__exit__
. Ifself
is already materialized, the context manager may do nothing (reflecting the fact that an outer context manager should already take care of everything else).
- context