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.

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

Author: normanchenn

docs/generated/sql/functions.md

@@ -1306,6 +1306,21 @@ 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,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