Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation for the elementFilter annotation / element-index filtering across the YQL and JSON query language reference docs, plus an additional CLI query example.
Changes:
- Document
elementFilterusage withsameElement()in the YQL reference, including the single-index shorthand syntax. - Add JSON Query Language documentation for the
equalsoperator, including anindexparameter for matching a specific multivalue element. - Add a Query Language page example that links to the
elementFilterdocumentation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| en/reference/querying/yql.html | Adds elementFilter narrative + adds elementFilter to the annotations table. |
| en/reference/querying/json-query-language.md | Adds an equals section and documents the index parameter for element-index matching. |
| en/querying/query-language.html | Adds a CLI example for matching a specific multivalue element, linking to elementFilter. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| struct-field value { indexing: attribute } | ||
| } | ||
| </pre> | ||
| <p id="element-index">Element index: Match a specific element in a multivalue field: |
There was a problem hiding this comment.
Can the syntax be used for any multivalue field or just arrays?
More generally, do we want this example here? Since there are only three examples here, I am not sure if this is important enough to be added here.
| } | ||
| ``` | ||
|
|
||
| Short form using an array — `[field, value]` is shorthand for `{ "field": field, "value": value }`: |
There was a problem hiding this comment.
This sentence is hard to read. The " Short form using an array — [field, value]" was hard to parse in my head.
Once could say something like "This can also be expressed using the following shorthand form:"
Edit: I suggested "shorthand form" while you later use "shorthand syntax". Imo "shorthand form" sounds better, but it does not matter what we use as long as we are consistent.
|
|
||
| The `equals` operator supports boolean and integer values. | ||
|
|
||
| To match at a specific element index in a multivalue field, add the `index` parameter. |
There was a problem hiding this comment.
(Unsure about multivalue fields as above)
| <pre> | ||
| where my_numbers contains ({elementFilter:[2]}sameElement("42")) | ||
| </pre> | ||
| <p>This only matches in the element at index 2. |
There was a problem hiding this comment.
"matches in the element at index 2" sounds wrong. (Matching in an element, can you say that?)
"matches in the field at index 2" or "matches the element at index 2" makes more sense imo.
| <p>This only matches in the element at index 2. | ||
| Multiple indices can be given: <code>{elementFilter:[0, 2, 5]}</code>.</p> | ||
|
|
||
| <p>A shorthand syntax is also available for matching a single element index:</p> |
There was a problem hiding this comment.
"for matching at a single element index" maybe? Since we are not matching the index itself but the element at that index.
Edit: Or just use "A shorthand syntax is also available:" since you already have the remark below.
| <p>The shorthand only supports a single index. | ||
| Use the annotation form with <code>elementFilter</code> to match multiple indices.</p> |
There was a problem hiding this comment.
This repeats what was said before.
| Only the elements at the given indices are required to match. | ||
| </p> | ||
| <pre> | ||
| where my_numbers contains ({elementFilter:[2]}sameElement("42")) |
There was a problem hiding this comment.
I would use multiple indices here.
| <td> | ||
| <p id="elementfilter"> | ||
| Used with <a href="#sameelement">sameElement</a>. | ||
| Restricts matching to specific element indices in a multivalue field. |
| <p id="elementfilter"> | ||
| Used with <a href="#sameelement">sameElement</a>. | ||
| Restricts matching to specific element indices in a multivalue field. | ||
| Only the elements at the given indices are required to match. |
There was a problem hiding this comment.
What does this sentence mean? I would be very explicit: "Makes sameElement match if and only if there is a match at one or more of the specified indicies."
|
Thanks! I will take a look👍🏻 |
I confirm that this contribution is made under the terms of the license found in the root directory of this repository's source tree and that I have the authority necessary to make this contribution on behalf of its copyright owner.
@havardpe please review
@boeker please review