Query¶

class lsst.daf.butler.Query¶

Bases: ABC

Interface for construction and execution of complex queries.

Methods Summary

`data_ids`(dimensions, *[, data_id, where, bind])	Query for data IDs matching user-provided criteria.
`datasets`(dataset_type[, collections, ...])	Query for and iterate over dataset references matching user-provided criteria.
`dimension_records`(element, *[, data_id, ...])	Query for dimension information matching user-provided criteria.

Methods Documentation

abstract data_ids(dimensions: DimensionGroup | Iterable[str] | str, *, data_id: DataId | None = None, where: str = '', bind: Mapping[str, Any] | None = None, **kwargs: Any) → DataCoordinateQueryResults¶

Query for data IDs matching user-provided criteria.

Parameters:

dimensionsDimensionGroup, str, or Iterable [str]: The dimensions of the data IDs to yield, as either DimensionGroup instances or str. Will be automatically expanded to a complete DimensionGroup.
data_iddict or DataCoordinate, optional: A data ID whose key-value pairs are used as equality constraints in the query.
wherestr, optional: A string expression similar to a SQL WHERE clause. May involve any column of a dimension table or (as a shortcut for the primary key column of a dimension table) dimension name. See Dimension expressions for more information.
bindMapping, optional: Mapping containing literal values that should be injected into the where expression, keyed by the identifiers they replace. Values of collection type can be expanded in some cases; see Identifiers for more information.
**kwargs: Additional keyword arguments are forwarded to DataCoordinate.standardize when processing the data_id argument (and may be used to provide a constraining data ID even when the data_id argument is None).

Returns:

dataIdsDataCoordinateQueryResults: Data IDs matching the given query parameters. These are guaranteed to identify all dimensions (DataCoordinate.hasFull returns True), but will not contain DimensionRecord objects (DataCoordinate.hasRecords returns False). Call expanded on the returned object to fetch those (and consider using materialize on the returned object first if the expected number of rows is very large). See documentation for those methods for additional information.

Raises:

lsst.daf.butler.registry.DataIdError: Raised when data_id or keyword arguments specify unknown dimensions or values, or when they contain inconsistent values.
lsst.daf.butler.registry.UserExpressionError: Raised when where expression is invalid.

abstract datasets(dataset_type: Any, collections: CollectionArgType | None = None, *, find_first: bool = True, data_id: DataId | None = None, where: str = '', bind: Mapping[str, Any] | None = None, **kwargs: Any) → DatasetQueryResults¶

Query for and iterate over dataset references matching user-provided criteria.

Parameters:

dataset_typedataset type expression: An expression that fully or partially identifies the dataset types to be queried. Allowed types include DatasetType, str, re.Pattern, and iterables thereof. The special value ... can be used to query all dataset types. See DatasetType expressions for more information.
collectionscollection expression, optional: An expression that identifies the collections to search, such as a str (for full matches or partial matches via globs), re.Pattern (for partial matches), or iterable thereof. ... can be used to search all collections (actually just all RUN collections, because this will still find all datasets). If not provided, the default collections are used. See Collection expressions for more information.
find_firstbool, optional: If True (default), for each result data ID, only yield one DatasetRef of each DatasetType, from the first collection in which a dataset of that dataset type appears (according to the order of collections passed in). If True, collections must not contain regular expressions and may not be ....
data_iddict or DataCoordinate, optional: A data ID whose key-value pairs are used as equality constraints in the query.
wherestr, optional: A string expression similar to a SQL WHERE clause. May involve any column of a dimension table or (as a shortcut for the primary key column of a dimension table) dimension name. See Dimension expressions for more information.
bindMapping, optional: Mapping containing literal values that should be injected into the where expression, keyed by the identifiers they replace. Values of collection type can be expanded in some cases; see Identifiers for more information.
**kwargs: Additional keyword arguments are forwarded to DataCoordinate.standardize when processing the data_id argument (and may be used to provide a constraining data ID even when the data_id argument is None).

Returns:

refsqueries.DatasetQueryResults: Dataset references matching the given query criteria. Nested data IDs are guaranteed to include values for all implied dimensions (i.e. DataCoordinate.hasFull will return True), but will not include dimension records (DataCoordinate.hasRecords will be False) unless expanded is called on the result object (which returns a new one).

Raises:

lsst.daf.butler.registry.DatasetTypeExpressionError: Raised when dataset_type expression is invalid.
TypeError: Raised when the arguments are incompatible, such as when a collection wildcard is passed when find_first is True, or when collections is None and default butler collections are not defined.
lsst.daf.butler.registry.DataIdError: Raised when data_id or keyword arguments specify unknown dimensions or values, or when they contain inconsistent values.
lsst.daf.butler.registry.UserExpressionError: Raised when where expression is invalid.

Notes

When multiple dataset types are queried in a single call, the results of this operation are equivalent to querying for each dataset type separately in turn, and no information about the relationships between datasets of different types is included.

abstract dimension_records(element: str, *, data_id: DataId | None = None, where: str = '', bind: Mapping[str, Any] | None = None, **kwargs: Any) → DimensionRecordQueryResults¶

Query for dimension information matching user-provided criteria.

Parameters:

elementstr: The name of a dimension element to obtain records for.
data_iddict or DataCoordinate, optional: A data ID whose key-value pairs are used as equality constraints in the query.
wherestr, optional: A string expression similar to a SQL WHERE clause. See queryDataIds and Dimension expressions for more information.
bindMapping, optional: Mapping containing literal values that should be injected into the where expression, keyed by the identifiers they replace. Values of collection type can be expanded in some cases; see Identifiers for more information.
**kwargs: Additional keyword arguments are forwarded to DataCoordinate.standardize when processing the data_id argument (and may be used to provide a constraining data ID even when the data_id argument is None).

Returns:

recordsqueries.DimensionRecordQueryResults: Data IDs matching the given query parameters.

Raises:

lsst.daf.butler.registry.NoDefaultCollectionError: Raised if collections is None and self.defaults.collections is None.
lsst.daf.butler.registry.CollectionExpressionError: Raised when collections expression is invalid.
lsst.daf.butler.registry.DataIdError: Raised when data_id or keyword arguments specify unknown dimensions or values, or when they contain inconsistent values.
lsst.daf.butler.registry.DatasetTypeExpressionError: Raised when datasetType expression is invalid.
lsst.daf.butler.registry.UserExpressionError: Raised when where expression is invalid.

Navigation

Query¶