ParentDatasetQueryResults

class lsst.daf.butler.registry.queries.ParentDatasetQueryResults(query: lsst.daf.butler.registry.queries._query.Query, dataset_type: lsst.daf.butler.core.datasets.type.DatasetType, components: collections.abc.Sequence[str | None[str, None]] = (None, ))

Bases: lsst.daf.butler.registry.queries.DatasetQueryResults

An object that represents results from a query for datasets with a single parent DatasetType.

Parameters:

query : Query

Low-level query object that backs these results.

dataset_type : DatasetType

Parent dataset type for all datasets returned by this query.

components : Sequence [ str or None ], optional

Names of components to include in iteration. None may be included (at most once) to include the parent dataset type.

Notes

The Query class now implements essentially all of this class’s functionality; “QueryResult” classes like this one now exist only to provide interface backwards compatibility and more specific iterator types.

Attributes Summary

dataIds	A lazy-evaluation object representing a query for just the data IDs of the datasets that would be returned by this query (DataCoordinateQueryResults).
parentDatasetType	The parent dataset type for all datasets in this iterable (DatasetType).

Methods Summary

any(*, execute, exact)	Test whether this query returns any results.
byParentDatasetType()	Group results by parent dataset type.
count(*, exact, discard)	Count the number of rows this query would return.
expanded()	Return a DatasetQueryResults for which DataCoordinate.hasRecords returns True for all data IDs in returned DatasetRef objects.
explain_no_results(execute)	Return human-readable messages that may help explain why the query yields no results.
materialize()	Insert this query’s results into a temporary table.
withComponents(components, None]])	Return a new query results object for the same parent datasets but different components.

Attributes Documentation

dataIds

A lazy-evaluation object representing a query for just the data IDs of the datasets that would be returned by this query (DataCoordinateQueryResults).

The returned object is not in general zip-iterable with self; it may be in a different order or have (or not have) duplicates.

parentDatasetType

The parent dataset type for all datasets in this iterable (DatasetType).

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.

byParentDatasetType() → collections.abc.Iterator[lsst.daf.butler.registry.queries._results.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).

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. If False, 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. 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:

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.

expanded() → lsst.daf.butler.registry.queries._results.ParentDatasetQueryResults

Return a DatasetQueryResults for which DataCoordinate.hasRecords returns True for all data IDs in returned DatasetRef objects.

Returns:

expanded : DatasetQueryResults

Either a new DatasetQueryResults instance or self, if it is already expanded.

Notes

As with DataCoordinateQueryResults.expanded, it may be more efficient to call materialize before expanding data IDs for very large result sets.

explain_no_results(execute: bool = True) → collections.abc.Iterable[str]

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

Parameters:

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

messages : Iterable [ str ]

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

materialize() → collections.abc.Iterator[lsst.daf.butler.registry.queries._results.ParentDatasetQueryResults]

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__. If self is already materialized, the context manager may do nothing (reflecting the fact that an outer context manager should already take care of everything else).

withComponents(components: collections.abc.Sequence[str | None[str, None]]) → lsst.daf.butler.registry.queries._results.ParentDatasetQueryResults

Return a new query results object for the same parent datasets but different components.

components : Sequence [ str or None ]

Names of components to include in iteration. None may be included (at most once) to include the parent dataset type.