From f4b8f4b8f861e5539297c8cd7c6321a79fa7137a Mon Sep 17 00:00:00 2001 From: Krzysztof Findeisen Date: Thu, 23 Jan 2025 10:23:08 -0800 Subject: [PATCH] Clarify requirements for using dataset fields in advanced queries. The previous description referred to table joins and other implementation details, which are not (and need not be) visible to users. --- python/lsst/daf/butler/queries/_base.py | 8 ++++---- python/lsst/daf/butler/queries/_query.py | 12 +++++++----- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/python/lsst/daf/butler/queries/_base.py b/python/lsst/daf/butler/queries/_base.py index 023af9d53d..e9445a5ae2 100644 --- a/python/lsst/daf/butler/queries/_base.py +++ b/python/lsst/daf/butler/queries/_base.py @@ -138,10 +138,10 @@ def where( Notes ----- - If an expression references a dimension or dimension element that is - not already present in the query, it will be joined in, but dataset - searches must already be joined into a query in order to reference - their fields in expressions. + Expressions referring to dimensions or dimension elements are resolved + automatically. References to dataset fields (see `expression_factory` + for the distinction) may or may not be resolvable, depending on the + implementation class. Data ID values are not checked for consistency; they are extracted from ``args`` and then ``kwargs`` and combined, with later values overriding diff --git a/python/lsst/daf/butler/queries/_query.py b/python/lsst/daf/butler/queries/_query.py index d1104721e3..a2f66118fc 100644 --- a/python/lsst/daf/butler/queries/_query.py +++ b/python/lsst/daf/butler/queries/_query.py @@ -659,15 +659,17 @@ def where( Notes ----- - If an expression references a dimension or dimension element that is - not already present in the query, it will be joined in, but dataset - searches must already be joined into a query in order to reference - their fields in expressions. + Expressions referring to dimensions or dimension elements are resolved + automatically. References to dataset fields (see `expression_factory` + for the distinction) cannot be resolved by default; they must either be + preceded by a call to `join_dataset_search` or must be passed to + `DatasetRefQueryResults.where ` + instead. Data ID values are not checked for consistency; they are extracted from ``args`` and then ``kwargs`` and combined, with later values overriding earlier ones. - """ + """ # noqa: W505, long docstrings return Query( tree=self._tree.where( convert_where_args(