DM-46389: Update query documentation for new query system #1082
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1082 +/- ##
=======================================
Coverage 89.69% 89.69%
=======================================
Files 360 360
Lines 47061 47061
Branches 9661 9661
=======================================
Hits 42213 42213
Misses 3480 3480
Partials 1368 1368 ☔ View full report in Codecov by Sentry. |
timj
approved these changes
Sep 19, 2024
doc/lsst.daf.butler/queries.rst
Outdated
| @@ -41,8 +49,7 @@ Collection expressions | |||
| Arguments that specify one or more collections are similar to those for dataset types; they can take: | |||
|
|
|||
| - `str` values (the full collection name); | |||
| - `str` values using glob wildcard syntax which will be converted to `re.Pattern`; | |||
| - `re.Pattern` values (matched to the collection name, via `~re.Pattern.fullmatch`); | |||
| - `str` values using glob wildcard syntax (like ``u/someone/*`` to find all collections starting with "u/someone/".) | |||
| - iterables of any of the above, empty collection cannot match anything, methods always return an empty result set in this case; | |||
| - the special value "``...``", which matches all collections; | |||
doc/lsst.daf.butler/queries.rst
Outdated
|
|
||
| - The definitions of `~CollectionType.CHAINED` collections | ||
| - `Butler.get` | ||
| - `Butler.put` |
There was a problem hiding this comment.
Doesn't this only take a single RUN collection?
doc/lsst.daf.butler/queries.rst
Outdated
| @@ -441,23 +442,26 @@ Few examples of valid expressions using some of the constructs: | |||
| Query result ordering | |||
| --------------------- | |||
|
|
|||
| Few query methods (`~Registry.queryDataIds` and `~Registry.queryDimensionRecords`) support special constructs for ordering and limiting the number of the returned records. These methods return iterable objects which have ``order_by()`` and ``limit()`` methods. Methods modify the iterable object and should be used before iterating over resulting records, for convenience the methods can be chained, see example below. | |||
| Butler query methods (`Butler.query_datasets`, `Butler.query_data_ids`, and | |||
There was a problem hiding this comment.
General comment that RST preferred style is one sentence per line rather than line breaks mid sentence.
|
|
||
| - A dimension name, corresponding to the value of the dimension primary key, e.g. ``"visit"`` | ||
| - A dimension name and a field name separated bey a dot. Field name can refer to any of the dimension's metadata or key, e.g. ``"visit.name"``, ``"detector.raft"``. Special field names ``"timespan.begin"`` and ``"timespan.end"`` can be used for temporal dimensions (visit and exposure). | ||
| - A field name without dimension name, in that case field is searched in all dimensions used by the query, and it has to be unique. E.g. ``"cell_x"`` means the same as ``"patch.cell_x"``. | ||
| - To reverse ordering for the field it is prefixed with a minus sign, e.g. ``"-visit.timespan.begin"``. | ||
|
|
||
| The ``limit()`` method accepts two positional integer arguments - limit for the number of returned records and offset (number of records to skip). The offset argument is optional, if not provided it is equivalent to offset 0. | ||
| The ``limit`` parameter accepts an integer specifying the maximum number of results to return. |
There was a problem hiding this comment.
Maybe mention the difference between positive and negative limit and what happens by default if no results are returned (but limit=0 does not complain for no results since you asked for none).
There was a problem hiding this comment.
I considered that originally but decided it was Too Much Information for an overview document -- the parameter description into the API documentation covers that in detail already.
Updated the query documentation to prefer the use of methods from the new query system where available, and reflect the current status of the code. Some effort was also made to add examples and remove verbose technical information that isn't relevant to most users.
dhirving
force-pushed
the
tickets/DM-46389
branch
from
b0dbfa8
to
480ba3e
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updated the query documentation to prefer the use of methods from the new query system where available, and reflect the current status of the code.
Some effort was also made to add examples and remove verbose technical information that isn't relevant to most users.
Checklist
doc/changesconfigs/old_dimensions