QueryBuilder

class lsst.daf.butler.registry.queries.QueryBuilder(connection: sqlalchemy.engine.base.Connection, summary: lsst.daf.butler.registry.queries._structs.QuerySummary, dimensionStorage: lsst.daf.butler.core.utils.NamedKeyDict[lsst.daf.butler.core.dimensions.elements.DimensionElement, lsst.daf.butler.core.dimensions.storage.DimensionRecordStorage][lsst.daf.butler.core.dimensions.elements.DimensionElement, lsst.daf.butler.core.dimensions.storage.DimensionRecordStorage], datasetStorage: lsst.daf.butler.registry.queries._datasets.DatasetRegistryStorage)

Bases: object

A builder for potentially complex queries that join tables based on dimension relationships.

Parameters:

connection : sqlalchemy.engine.Connection

SQLAlchemy connection object. This is only used to pass through to the Query object returned by finish.

summary : QuerySummary

Struct organizing the dimensions involved in the query.

dimensionStorage : NamedKeyDict

Storage backend objects that abstract access to dimension tables, organized as a NamedKeyDict mapping DimensionElement to DimensionRecordStorage.

datasetStorage : DatasetRegistryStorage

Storage backend object that abstracts access to dataset tables.

Methods Summary

finish()	Finish query constructing, returning a new Query instance.
joinDataset(datasetType, collections, …)	Add a dataset search or constraint to the query.
joinDimensionElement(element)	Add the table for a DimensionElement to the query.
joinTable(table, dimensions)	Join an arbitrary table to the query via dimension relationships.
joinToCommonSkyPix(element)	Add the table relating a spatial DimensionElement to the universe’s commonSkyPix dimension to the query.

Methods Documentation

finish() → lsst.daf.butler.registry.queries._query.Query

Finish query constructing, returning a new Query instance.

This automatically joins any missing dimension element tables (according to the categorization of the QuerySummary the builder was constructed with).

This consumes the QueryBuilder; no other methods should be called after this one.

Returns:

query : Query

A Query object that can be executed (possibly multiple times with different bind parameter values) and used to interpret result rows.

joinDataset(datasetType: lsst.daf.butler.core.datasets.type.DatasetType, collections: Union[Sequence[Union[str, lsst.daf.butler.registry.queries._datasets.Like]], ellipsis], *, isResult: bool = True, addRank: bool = False)

Add a dataset search or constraint to the query.

Unlike other QueryBuilder join methods, this must be called directly to search for datasets of a particular type or constrain the query results based on the exists of datasets. However, all dimensions used to identify the dataset type must have already been included in QuerySummary.requested when initializing the QueryBuilder.

Parameters:

datasetType : DatasetType

The type of datasets to search for.

collections : sequence of str or Like, or ...

An expression describing the collections in which to search for the datasets. ... indicates that all collections should be searched.

isResult : bool, optional

If True (default), include the dataset_id column in the result columns of the query, allowing complete DatasetRef instances to be produced from the query results for this dataset type. If False, the existence of datasets of this type is used only to constrain the data IDs returned by the query.

addRank : bool, optional

If True (False is default), also include a calculated column that ranks the collection in which the dataset was found (lower is better). Requires that all entries in collections be regular strings, so there is a clear search order. Ignored if isResult is False.

joinDimensionElement(element: lsst.daf.butler.core.dimensions.elements.DimensionElement)

Add the table for a DimensionElement to the query.

This automatically joins the element table to all other tables in the query with which it is related, via both dimension keys and spatial and temporal relationships.

External calls to this method should rarely be necessary; finish will automatically call it if the DimensionElement has been identified as one that must be included.

Parameters:

element : DimensionElement

Element for which a table should be added. The element must be associated with a database table (see DimensionElement.hasTable).

joinTable(table: sqlalchemy.sql.selectable.FromClause, dimensions: Iterable[lsst.daf.butler.core.dimensions.elements.Dimension])

Join an arbitrary table to the query via dimension relationships.

External calls to this method should only be necessary for tables whose records represent neither dataset nor dimension elements (i.e. extensions to the standard Registry schema).

Parameters:

table : sqlalchemy.sql.FromClause

SQLAlchemy object representing the logical table (which may be a join or subquery expression) to be joined.

dimensions : iterable of Dimension

The dimensions that relate this table to others that may be in the query. The table must have columns with the names of the dimensions.

joinToCommonSkyPix(element: lsst.daf.butler.core.dimensions.elements.DimensionElement)

Add the table relating a spatial DimensionElement to the universe’s commonSkyPix dimension to the query.

External calls to this method should rarely be necessary; finish will automatically call it if the DimensionElement has been identified as one that must be included.

Parameters:

element : DimensionElement

Element for which the relationship should be added. The element must be associated with a database table (see DimensionElement.hasTable) and must have Dimensionelement.spatial True.