Query

class lsst.daf.butler.registry.queries.Query(*, sql: sqlalchemy.sql.selectable.FromClause, summary: lsst.daf.butler.registry.queries._structs.QuerySummary, columns: lsst.daf.butler.registry.queries._structs.QueryColumns, collections: lsst.daf.butler.registry.interfaces._collections.CollectionManager)

Bases: object

A wrapper for a SQLAlchemy query that knows how to transform result rows into data IDs and dataset references.

A Query should almost always be constructed directly by a call to QueryBuilder.finish; direct construction will make it difficult to be able to maintain invariants between arguments (see the documentation for QueryColumns for more information).

Parameters:

sql : sqlalchemy.sql.FromClause

A complete SELECT query, including at least SELECT, FROM, and WHERE clauses.

summary : QuerySummary

Struct that organizes the dimensions involved in the query.

columns : QueryColumns

Columns that are referenced in the query in any clause.

collections : CollectionsManager,

Manager object for collection tables.

Notes

SQLAlchemy is used in the public interface of Query rather than just its implementation simply because avoiding this would entail writing wrappers for the sqlalchemy.engine.RowProxy and sqlalchemy.engine.ResultProxy classes that are themselves generic wrappers for lower-level Python DBAPI classes. Another layer would entail another set of computational overheads, but the only reason we would seriously consider not using SQLAlchemy here in the future would be to reduce computational overheads.

Methods Summary

extractDataId(row, *, graph)	Extract a data ID from a result row.
extractDatasetRef(row, datasetType, dataId)	Extract a DatasetRef from a result row.
extractDimensionsTuple(row, dimensions)	Extract a tuple of data ID values from a result row.
predicate(region)	Return a callable that can perform extra Python-side filtering of query results.

Methods Documentation

extractDataId(row: sqlalchemy.engine.result.RowProxy, *, graph: Optional[lsst.daf.butler.core.dimensions.graph.DimensionGraph] = None) → lsst.daf.butler.core.dimensions.coordinate.DataCoordinate

Extract a data ID from a result row.

Parameters:

row : sqlalchemy.engine.RowProxy

A result row from a SQLAlchemy SELECT query.

graph : DimensionGraph, optional

The dimensions the returned data ID should identify. If not provided, this will be all dimensions in QuerySummary.requested.

Returns:

dataId : DataCoordinate

A data ID that identifies all required and implied dimensions.

extractDatasetRef(row: sqlalchemy.engine.result.RowProxy, datasetType: lsst.daf.butler.core.datasets.type.DatasetType, dataId: Optional[lsst.daf.butler.core.dimensions.coordinate.DataCoordinate] = None) → Tuple[lsst.daf.butler.core.datasets.ref.DatasetRef, Optional[int]]

Extract a DatasetRef from a result row.

Parameters:

row : sqlalchemy.engine.RowProxy

A result row from a SQLAlchemy SELECT query.

datasetType : DatasetType

Type of the dataset to extract. Must have been included in the Query via a call to QueryBuilder.joinDataset with isResult=True, or otherwise included in QueryColumns.datasets.

dataId : DataCoordinate

Data ID to attach to the DatasetRef. A minimal (i.e. base class) DataCoordinate is constructed from row if None.

Returns:

ref : DatasetRef

Reference to the dataset; guaranteed to have DatasetRef.id not None.

rank : int or None

Integer index of the collection in which this dataset was found, within the sequence of collections passed when constructing the query. None if QueryBuilder.joinDataset was called with addRank=False.

extractDimensionsTuple(row: sqlalchemy.engine.result.RowProxy, dimensions: Iterable[lsst.daf.butler.core.dimensions.elements.Dimension]) → tuple

Extract a tuple of data ID values from a result row.

Parameters:

row : sqlalchemy.engine.RowProxy

A result row from a SQLAlchemy SELECT query.

dimensions : Iterable [ Dimension ]

The dimensions to include in the returned tuple, in order.

Returns:

values : tuple

A tuple of dimension primary key values.

predicate(region: Optional[lsst.sphgeom._sphgeom.Region] = None) → Callable[[sqlalchemy.engine.result.RowProxy], bool]

Return a callable that can perform extra Python-side filtering of query results.

To get the expected results from a query, the returned predicate must be used to ignore rows for which it returns False; this permits the QueryBuilder implementation to move logic from the database to Python without changing the public interface.

Parameters:

region : sphgeom.Region, optional

A region that any result-row regions must overlap in order for the predicate to return True. If not provided, this will be the region in QuerySummary.dataId, if there is one.

Returns:

func : Callable

A callable that takes a single sqlalchemy.engine.RowProxy argmument and returns bool.