QueryBuilder

class lsst.daf.butler.registry.queries.QueryBuilder(summary: lsst.daf.butler.registry.queries._structs.QuerySummary, backend: lsst.daf.butler.registry.queries._query_backend.QueryBackend, context: Optional[lsst.daf.butler.registry.queries._query_context.QueryContext, None] = None, relation: Optional[lsst.daf.relation._relation.Relation, None] = None)

Bases: object

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

Parameters:

summary : QuerySummary

Struct organizing the dimensions involved in the query.

backend : QueryBackend

Backend object that represents the Registry implementation.

context : QueryContext, optional

Object that manages relation engines and database-side state (e.g. temporary tables) for the query. Must have been created by backend.context(), which is used if context is not provided.

relation : Relation, optional

Initial relation for the query.

Methods Summary

finish(joinMissing)	Finish query constructing, returning a new Query instance.
joinDataset(datasetType, collections, *, …)	Add a dataset search or constraint to the query.

Methods Documentation

finish(joinMissing: bool = True) → lsst.daf.butler.registry.queries._query.Query

Finish query constructing, returning a new Query instance.

Parameters:

joinMissing : bool, optional

If True (default), automatically join any missing dimension element tables (according to the categorization of the QuerySummary the builder was constructed with). False should only be passed if the caller can independently guarantee that all dimension relationships are already captured in non-dimension tables that have been manually included in the query.

Returns:

query : Query

A Query object that can be executed and used to interpret result rows.

joinDataset(datasetType: lsst.daf.butler.core.datasets.type.DatasetType, collections: Any, *, isResult: bool = True, findFirst: bool = False) → bool

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 : Any

An expression that fully or partially identifies the collections to search for datasets, such as a str, re.Pattern, or iterable thereof. can be used to return all collections. See Collection expressions for more information.

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. joinDataset may be called with isResult=True at most one time on a particular QueryBuilder instance.

findFirst : bool, optional

If True (False is default), only include the first match for each data ID, searching the given collections in order. Requires that all entries in collections be regular strings, so there is a clear search order. Ignored if isResult is False.

Returns:

anyRecords : bool

If True, joining the dataset table was successful and the query should proceed. If False, we were able to determine (from the combination of datasetType and collections) that there would be no results joined in from this dataset, and hence (due to the inner join that would normally be present), the full query will return no results.