draft JSONPath documentation #19580
draft JSONPath documentation #19580
Conversation
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify site configuration. |
src/current/v25.2/jsonpath.md
Outdated
| A JSONPath expression has the following generic structure: | ||
|
|
||
| ~~~ | ||
| [mode] $[.key] [? (filter_exp)].[key].[method] |
There was a problem hiding this comment.
Is this diagram meant to show the allowed syntax for JSONPath? If it's just meant to be an example, maybe we should note that somewhere. Otherwise, it's not quite correct - for example, these are all valid JSONPath expressions:
root@localhost:26257/defaultdb> select '1'::jsonpath;
jsonpath
------------
1
(1 row)
root@localhost:26257/defaultdb> select '1 == 2'::jsonpath;
jsonpath
------------
(1 == 2)
(1 row)
root@localhost:26257/defaultdb> select '(100 * 200) ? ($foo > 100)'::jsonpath;
jsonpath
------------------------------
(100 * 200)?($"foo" > 100)
(1 row)
root@localhost:26257/defaultdb> select 'exists($)'::jsonpath;
jsonpath
--------------
exists ($)
(1 row)
Following the optional mode is a sequence of scalar expressions/predicates separated by accessors ., [...], and ?, with some restrictions about what can be in/following an accessor. The $ symbol is just a special expression referring to the root JSONB expression being queried.
src/current/v25.2/jsonpath.md
Outdated
|
|
||
| - `mode` is an optional mode (`lax` or `strict`) that determines how structural mismatches are tolerated. If not specified, the mode is `lax`. Refer to [Structural error handling](#structural-error-handling). | ||
| - `$` is the root of the JSONPath, and must be the first element in a JSONPath expression. For an example, refer to [Access entire document](#access-entire-document). | ||
| - `.key` is an optional key accessor that refers to a named field in a `JSONB` object. To access array elements, use `.key[index]` or `.key[*]`. Each successive key accessor navigates one level deeper into the structure. `.*` matches all fields in the current object. |
There was a problem hiding this comment.
We should make mention of the array accessor as it's own thing, I think. For example, you can do this:
root@localhost:26257/defaultdb> SELECT jsonb_path_query('[1, 2, 3]', '$[0]');
jsonb_path_query
--------------------
1
(1 row)
src/current/v25.2/jsonpath.md
Outdated
| [mode] $[.key] [? (filter_exp)].[key].[method] | ||
| ~~~ | ||
|
|
||
| - `mode` is an optional mode (`lax` or `strict`) that determines how structural mismatches are tolerated. If not specified, the mode is `lax`. Refer to [Structural error handling](#structural-error-handling). |
There was a problem hiding this comment.
There are some other keywords/expressions we're missing:
@is the "current" expression, representing the current result of path evaluation and only usable within a filter. Ex:
-- '@' will be set to 300, and the filter will pass.
root@localhost:26257/defaultdb> SELECT jsonb_path_query('{}', '(100 + 200) ? (@ * 2 == 600)');
jsonb_path_query
--------------------
300
(1 row)
LASTevaluates to the last element of the array currently being evaluated. Only usable within an array subscript. Ex:
root@localhost:26257/defaultdb> SELECT jsonb_path_query('[1, 2, 3]', '$[last]');
jsonb_path_query
--------------------
3
(1 row)
(After reading further) I see we have some examples using these keywords below - maybe we could make note that the ones here are the ones allowed in the root JSONPath expression, while there are others allowed in the context of an array or filter.
There was a problem hiding this comment.
@DrewKimball Thanks, I was struggling with this section overall. I completely reworked how it presents the syntax -- please have a look!
DOC-13202