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, discard])Count the number of rows this query would return.
expanded
()Return a
DatasetQueryResults
for whichDataCoordinate.hasRecords
returnsTrue
for all data IDs in returnedDatasetRef
objects.explain_no_results
([execute])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, discard: bool = False) 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. IfFalse
, the result may be an upper bound.- discard
bool
, 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. IfFalse
, 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 passingexact=False
). Ignored ifexact=False
.
- exact
- 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(execute: bool = True) Iterable[str] ¶
Return human-readable messages that may help explain why the query yields no results.
- abstract materialize() AbstractContextManager[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