Merge #144006

144006: builtins: add `jsonb_path_query_array`, `jsonb_path_query_first`, `jsonb_path_match` r=normanchenn a=normanchenn

#### builtins: add jsonb_path_query_array

This commit adds the `jsonb_path_query_array` function, which wraps
`jsonb_path_query` and returns a json array containing all the items
returned from the query.

Informs: #22513
Release note (sql change): Add the `jsonb_path_query_array` function,
which returns the result of `jsonb_path_query` wrapped in a JSON array.

#### builtins: add jsonb_path_query_first

This commit adds the `jsonb_path_query_first` function, which wraps
`jsonb_path_query` and returns the first element that was returned from
the function.

Informs: #22513
Release note (sql change): Add the `jsonb_path_query_first` function,
which returns the first result from `jsonb_path_query`.

#### builtins: add jsonb_path_match

This commit adds the `jsonb_path_match` function, which returns a
boolean that evaluates the predicate query, and returns null if the
query result isn't a predicate.

Informs: #22513
Release note (sql change): Add the `jsonb_path_match` function, which
returns the result of a predicate query.


Co-authored-by: Norman Chen <[email protected]>

Author: craig[bot]

docs/generated/sql/functions.md

@@ -1280,6 +1280,29 @@ argument is true, the function suppresses the following errors:
 missing object field or array element, unexpected JSON item type,
 datetime and numeric errors.</p>
 </span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_match"></a><code>jsonb_path_match(target: jsonb, path: jsonpath) &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>Returns the SQL boolean result of a JSON path predicate check
+for the specified JSON value. (This is useful only with predicate check
+expressions, not SQL-standard JSON path expressions, since it will
+either fail or return NULL if the path result is not a single boolean
+value.)</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_match"></a><code>jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>Returns the SQL boolean result of a JSON path predicate check
+for the specified JSON value. (This is useful only with predicate check
+expressions, not SQL-standard JSON path expressions, since it will
+either fail or return NULL if the path result is not a single boolean
+value.) The vars argument must be a JSON object, and its fields provide
+named values to be substituted into the jsonpath expression.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_match"></a><code>jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: <a href="bool.html">bool</a>) &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>Returns the SQL boolean result of a JSON path predicate check
+for the specified JSON value. (This is useful only with predicate check
+expressions, not SQL-standard JSON path expressions, since it will
+either fail or return NULL if the path result is not a single boolean
+value.) The vars argument must be a JSON object, and its fields provide
+named values to be substituted into the jsonpath expression. If the
+silent argument is true, the function suppresses the following errors:
+missing object field or array element, unexpected JSON item type,
+datetime and numeric errors.</p>
+</span></td><td>Immutable</td></tr>
 <tr><td><a name="jsonb_path_query"></a><code>jsonb_path_query(target: jsonb, path: jsonpath) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns all JSON items returned by the JSON path for the specified JSON value.</p>
 </span></td><td>Immutable</td></tr>
 <tr><td><a name="jsonb_path_query"></a><code>jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns all JSON items returned by the JSON path for the specified JSON value.
@@ -1291,6 +1314,36 @@ The vars argument must be a JSON object, and its fields provide named values
 to be substituted into the jsonpath expression. If the silent argument is true,
 the function suppresses the following errors: missing object field or array
 element, unexpected JSON item type, datetime and numeric errors.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_array"></a><code>jsonb_path_query_array(target: jsonb, path: jsonpath) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns all JSON items returned by the JSON path for the
+specified JSON value, as a JSON array.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_array"></a><code>jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns all JSON items returned by the JSON path for the
+specified JSON value, as a JSON array. The vars argument must be a
+JSON object, and its fields provide named values to be substituted
+into the jsonpath expression.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_array"></a><code>jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: <a href="bool.html">bool</a>) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns all JSON items returned by the JSON path for the
+specified JSON value, as a JSON array. The vars argument must be a
+JSON object, and its fields provide named values to be substituted
+into the jsonpath expression. If the silent argument is true, the
+function suppresses the following errors: missing object field or
+array element, unexpected JSON item type, datetime and numeric errors.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_first"></a><code>jsonb_path_query_first(target: jsonb, path: jsonpath) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns the first JSON item returned by the JSON path for the
+specified JSON value, or NULL if there are no results.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_first"></a><code>jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns the first JSON item returned by the JSON path for the
+specified JSON value, or NULL if there are no results. The vars
+argument must be a JSON object, and its fields provide named values
+to be substituted into the jsonpath expression.</p>
+</span></td><td>Immutable</td></tr>
+<tr><td><a name="jsonb_path_query_first"></a><code>jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: <a href="bool.html">bool</a>) &rarr; jsonb</code></td><td><span class="funcdesc"><p>Returns the first JSON item returned by the JSON path for the
+specified JSON value, or NULL if there are no results. The vars
+argument must be a JSON object, and its fields provide named values
+to be substituted into the jsonpath expression. If the silent argument is true, the
+function suppresses the following errors: missing object field or
+array element, unexpected JSON item type, datetime and numeric errors.</p>
 </span></td><td>Immutable</td></tr></tbody>
 </table>
 

pkg/ccl/logictestccl/tests/3node-tenant/generated_test.go

@@ -0,0 +1,27 @@
+# LogicTest: !local-mixed-24.3 !local-mixed-25.1
+
+query B
+SELECT jsonb_path_match('{}', '1 + 1 == 2');
+----
+true
+
+query B
+SELECT jsonb_path_match('{}', '"abc" starts with "b"');
+----
+false
+
+query T
+SELECT jsonb_path_match('{}', 'strict $', '{}', true);
+----
+NULL
+
+statement error pgcode 22038 pq: jsonb_path_match\(\): single boolean result is expected
+SELECT jsonb_path_match('{}', 'strict $', '{}', false);
+
+query T
+SELECT jsonb_path_match('{}', '$', '{}', true);
+----
+NULL
+
+statement error pgcode 22038 pq: jsonb_path_match\(\): single boolean result is expected
+SELECT jsonb_path_match('{}', '$', '{}', false);

pkg/ccl/logictestccl/tests/local-read-committed/generated_test.go

@@ -0,0 +1,34 @@
+# LogicTest: !local-mixed-24.3 !local-mixed-25.1
+
+query T
+SELECT jsonb_path_query_array('{}', '$')
+----
+[{}]
+
+query T
+SELECT jsonb_path_query_array('{"a": [1, 2, {"b": [4, 5]}, null, [true, false]]}', '$.a[*]')
+----
+[1, 2, {"b": [4, 5]}, null, [true, false]]
+
+query T
+SELECT jsonb_path_query_array('{"a": [[{"b": 1, "c": "hello"}, {"b": 2, "c": "world"}, {"b": 1, "c": "!"}], [{"b": 1, "c": "hello"}, {"b": 2, "c": "world"}, {"b": 1, "c": "!"}]]}', '$.a ? (@.b == 1)');
+----
+[[{"b": 1, "c": "hello"}, {"b": 2, "c": "world"}, {"b": 1, "c": "!"}], [{"b": 1, "c": "hello"}, {"b": 2, "c": "world"}, {"b": 1, "c": "!"}]]
+
+query T
+SELECT jsonb_path_query_array('{}', 'strict $.a', '{}', true);
+----
+[]
+
+statement error pgcode 2203A pq: jsonb_path_query_array\(\): JSON object does not contain key "a"
+SELECT jsonb_path_query_array('{}', 'strict $.a', '{}', false);
+
+query T
+SELECT jsonb_path_query_array('{}', '$.a', '{}', true);
+----
+[]
+
+query T
+SELECT jsonb_path_query_array('{}', '$.a', '{}', false);
+----
+[]

pkg/ccl/logictestccl/tests/local-repeatable-read/generated_test.go

@@ -0,0 +1,34 @@
+# LogicTest: !local-mixed-24.3 !local-mixed-25.1
+
+query T
+SELECT jsonb_path_query_first('[1, 2, 3]', '$[*]');
+----
+1
+
+query T
+SELECT jsonb_path_query_first('[2, 3]', '$[*]');
+----
+2
+
+query T
+SELECT jsonb_path_query_first('[]', '$[*]');
+----
+NULL
+
+query T
+SELECT jsonb_path_query_first('{}', 'strict $.a', '{}', true);
+----
+NULL
+
+statement error pgcode 2203A pq: jsonb_path_query_first\(\): JSON object does not contain key "a"
+SELECT jsonb_path_query_first('{}', 'strict $.a', '{}', false);
+
+query T
+SELECT jsonb_path_query_first('{}', '$.a', '{}', true);
+----
+NULL
+
+query T
+SELECT jsonb_path_query_first('{}', '$.a', '{}', false);
+----
+NULL