Waiting for PostgreSQL 15 – SQL/JSON query functions

On 29th of March 2022, Andrew Dunstan committed patch:

SQL/JSON query functions
 
This introduces the SQL/JSON functions for querying JSON data using
jsonpath expressions. The functions are:
 
JSON_EXISTS()
JSON_QUERY()
JSON_VALUE()
 
All of these functions only operate on jsonb. The workaround for now is
to cast the argument to jsonb.
 
JSON_EXISTS() tests if the jsonpath expression applied to the jsonb
value yields any values. JSON_VALUE() must return a single value, and an
error occurs if it tries to return multiple values. JSON_QUERY() must
return a json object or array, and there are various WRAPPER options for
handling scalar or multi-value results. Both these functions have
options for handling EMPTY and ERROR conditions.
 
Nikita Glukhov
 
Reviewers have included (in no particular order) Andres Freund, Alexander
Korotkov, Pavel Stehule, Andrew Alsup, Erik Rijkers, Zihong Yu,
Himanshu Upadhyaya, Daniel Gustafsson, Justin Pryzby.
 
Discussion: https://postgr.es/m/cd0bb935-0158-78a7-08b5-904886deac4b@postgrespro.ru

And another patch improving json support.

Let's start with JSON_EXISTS() – this is simple it returns true/false based on given json (well, jsonb), and jsonpath expression:

=$ select JSON_EXISTS( '{"a":123}'::jsonb, '$.a' ), JSON_EXISTS( '{"a":123}'::jsonb, '$.b' );
 json_exists | json_exists 
-------------+-------------
 t           | f
(1 row)

Looks simple enough.

This means that it will be easy to write, and read, constraints on jsonb:

=$ create table user_profiles (
    ...
    addresses jsonb not null,
    check (json_exists( addresses, '$.main' ))
);

Next is JSON_QUERY – this simply returns what we match, based on jsonb value and jsonpath.

Let's assume you have such jsonb:

[ {"x": "aaa"}, {"x": "bbb"}, {"x": "ccc"} ]

I can get 2nd element's x property by:

=$ select json_query('[{"x": "aaa"},{"x": "bbb"},{"x": "ccc"}]'::jsonb, '$[1].x' );
 json_query 
------------
 "bbb"
(1 row)

What's more, I can make the jsonpath parametrized:

=$ select i,
json_query(
    '[{"x": "aaa"},{"x": "bbb"},{"x": "ccc"}]'::jsonb,
    '$[$i].x'
    passing i as i
)
FROM generate_series(0,3) i;
 i | json_query 
---+------------
 0 | "aaa"
 1 | "bbb"
 2 | "ccc"
 3 | 
(4 rows)

I can also make it omit quotes, and even return the values as text datatype:

=$ select i,
json_query(
    '[{"x": "aaa"},{"x": "bbb"},{"x": "ccc"}]'::jsonb,
    '$[$i].x'
    passing i as i
    returning text
    omit quotes
)
FROM generate_series(0,3) i;
 i | json_query 
---+------------
 0 | aaa
 1 | bbb
 2 | ccc
 3 | 
(4 rows)

Pretty cool.

There are also clauses, in JSON_QUERY() for handling errors (… ON ERROR), and adding wrappers in case jsonpath would return multiple values.

Can't tell more about JSON_VALUE, aside form the fact that it seems to be similar to JSON_QUERY.

Unfortunately lack of docs makes it rather hard to figure out all potential options, params, and so on. If you'd want to read more on this, the only source of information, right now, that I can find, is this file in sources, which contains some queries, and what will happen with Pg15 when you run them.

As I understand docs are coming, so this is not a big deal.

As with previous patches: great work, thanks to all involved.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.