Skip to content

Document JSON value constructors #12677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kasiafi merged 1 commit into from
Jun 8, 2022
Merged

Document JSON value constructors #12677

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 248 additions & 0 deletions docs/src/main/sphinx/functions/json.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Trino supports three functions for querying JSON data:
is based on the same mechanism of exploring and processing JSON input using
JSON path.

Trino also supports two functions for generating JSON data --
:ref:`json_array<json_array>`, and :ref:`json_object<json_object>`.

JSON path language
------------------

Expand Down Expand Up @@ -1163,6 +1166,251 @@ id child
103 'missing'
========== ================

.. _json_array:

json_array
----------

The ``json_array`` function creates a JSON array containing given elements.

.. code-block:: text

JSON_ARRAY(
[ array_element [, ...]
[ { NULL ON NULL | ABSENT ON NULL } ] ],
[ RETURNING type [ FORMAT JSON [ ENCODING { UTF8 | UTF16 | UTF32 } ] ] ]
)

Argument types
^^^^^^^^^^^^^^

The array elements can be arbitrary expressions. Each passed value is converted
into a JSON item according to its type, and optional ``FORMAT`` and
``ENCODING`` specification.

You can pass SQL values of types boolean, numeric, and character string. They
are converted to corresponding JSON literals::

SELECT json_array(true, 12e-1, 'text')
--> '[true,1.2,"text"]'

Additionally to SQL values, you can pass JSON values. They are character or
binary strings with a specified format and optional encoding::

SELECT json_array(
'[ "text" ] ' FORMAT JSON,
X'5B0035005D00' FORMAT JSON ENCODING UTF16
)
--> '[["text"],[5]]'

You can also nest other JSON-returning functions. In that case, the ``FORMAT``
option is implicit::

SELECT json_array(
json_query('{"key" : [ "value" ]}', 'lax $.key')
)
--> '[["value"]]'

Other passed values are cast to varchar, and they become JSON text literals::

SELECT json_array(
DATE '2001-01-31',
UUID '12151fd2-7586-11e9-8f9e-2a86e4085a59'
)
--> '["2001-01-31","12151fd2-7586-11e9-8f9e-2a86e4085a59"]'

You can omit the arguments altogether to get an empty array::

SELECT json_array() --> '[]'

Null handling
^^^^^^^^^^^^^

If a value passed for an array element is ``null``, it is treated according to
the specified null treatment option. If ``ABSENT ON NULL`` is specified, the
null element is omitted in the result. If ``NULL ON NULL`` is specified, JSON
``null`` is added to the result. ``ABSENT ON NULL`` is the default
configuration::

SELECT json_array(true, null, 1)
--> '[true,1]'

SELECT json_array(true, null, 1 ABSENT ON NULL)
--> '[true,1]'

SELECT json_array(true, null, 1 NULL ON NULL)
--> '[true,null,1]'

Returned type
^^^^^^^^^^^^^

The SQL standard imposes that there is no dedicated data type to represent JSON
data in SQL. Instead, JSON data is represented as character or binary strings.
By default, the ``json_array`` function returns varchar containing the textual
representation of the JSON array. With the ``RETURNING`` clause, you can
specify other character string type::

SELECT json_array(true, 1 RETURNING VARCHAR(100))
--> '[true,1]'

You can also specify to use varbinary and the required encoding as return type.
The default encoding is UTF8::

SELECT json_array(true, 1 RETURNING VARBINARY)
--> X'5b 74 72 75 65 2c 31 5d'

SELECT json_array(true, 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF8)
--> X'5b 74 72 75 65 2c 31 5d'

SELECT json_array(true, 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF16)
--> X'5b 00 74 00 72 00 75 00 65 00 2c 00 31 00 5d 00'

SELECT json_array(true, 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF32)
--> X'5b 00 00 00 74 00 00 00 72 00 00 00 75 00 00 00 65 00 00 00 2c 00 00 00 31 00 00 00 5d 00 00 00'

.. _json_object:

json_object
-----------

The ``json_object`` function creates a JSON object containing given key-value pairs.

.. code-block:: text

JSON_OBJECT(
[ key_value [, ...]
[ { NULL ON NULL | ABSENT ON NULL } ] ],
[ { WITH UNIQUE [ KEYS ] | WITHOUT UNIQUE [ KEYS ] } ]
[ RETURNING type [ FORMAT JSON [ ENCODING { UTF8 | UTF16 | UTF32 } ] ] ]
)

Argument passing conventions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are two conventions for passing keys and values::

SELECT json_object('key1' : 1, 'key2' : true)
--> '{"key1":1,"key2":true}'

SELECT json_object(KEY 'key1' VALUE 1, KEY 'key2' VALUE true)
--> '{"key1":1,"key2":true}'

In the second convention, you can omit the ``KEY`` keyword::

SELECT json_object('key1' VALUE 1, 'key2' VALUE true)
--> '{"key1":1,"key2":true}'

Argument types
^^^^^^^^^^^^^^

The keys can be arbitrary expressions. They must be of character string type.
Each key is converted into a JSON text item, and it becomes a key in the
created JSON object. Keys must not be null.

The values can be arbitrary expressions. Each passed value is converted
into a JSON item according to its type, and optional ``FORMAT`` and
``ENCODING`` specification.

You can pass SQL values of types boolean, numeric, and character string. They
are converted to corresponding JSON literals::

SELECT json_object('x' : true, 'y' : 12e-1, 'z' : 'text')
--> '{"x":true,"y":1.2,"z":"text"}'

Additionally to SQL values, you can pass JSON values. They are character or
binary strings with a specified format and optional encoding::

SELECT json_object(
'x' : '[ "text" ] ' FORMAT JSON,
'y' : X'5B0035005D00' FORMAT JSON ENCODING UTF16
)
--> '{"x":["text"],"y":[5]}'

You can also nest other JSON-returning functions. In that case, the ``FORMAT``
option is implicit::

SELECT json_object(
'x' : json_query('{"key" : [ "value" ]}', 'lax $.key')
)
--> '{"x":["value"]}'

Other passed values are cast to varchar, and they become JSON text literals::

SELECT json_object(
'x' : DATE '2001-01-31',
'y' : UUID '12151fd2-7586-11e9-8f9e-2a86e4085a59'
)
--> '{"x":"2001-01-31","y":"12151fd2-7586-11e9-8f9e-2a86e4085a59"}'

You can omit the arguments altogether to get an empty object::

SELECT json_object() --> '{}'

Null handling
^^^^^^^^^^^^^

The values passed for JSON object keys must not be null. It is allowed to pass
``null`` for JSON object values. A null value is treated according to the
specified null treatment option. If ``NULL ON NULL`` is specified, a JSON
object entry with ``null`` value is added to the result. If ``ABSENT ON NULL``
is specified, the entry is omitted in the result. ``NULL ON NULL`` is the
default configuration.::

SELECT json_object('x' : null, 'y' : 1)
--> '{"x":null,"y":1}'

SELECT json_object('x' : null, 'y' : 1 NULL ON NULL)
--> '{"x":null,"y":1}'

SELECT json_object('x' : null, 'y' : 1 ABSENT ON NULL)
--> '{"y":1}'

Key uniqueness
^^^^^^^^^^^^^^

If a duplicate key is encountered, it is handled according to the specified key
uniqueness constraint.

If ``WITH UNIQUE KEYS`` is specified, a duplicate key results in a query
failure::

SELECT json_object('x' : null, 'x' : 1 WITH UNIQUE KEYS)
--> failure: "duplicate key passed to JSON_OBJECT function"

Note that this option is not supported if any of the arguments has a
``FORMAT`` specification.

If ``WITHOUT UNIQUE KEYS`` is specified, duplicate keys are not supported due
to implementation limitation. ``WITHOUT UNIQUE KEYS`` is the default
configuration.

Returned type
^^^^^^^^^^^^^

The SQL standard imposes that there is no dedicated data type to represent JSON
data in SQL. Instead, JSON data is represented as character or binary strings.
By default, the ``json_object`` function returns varchar containing the textual
representation of the JSON object. With the ``RETURNING`` clause, you can
specify other character string type::

SELECT json_object('x' : 1 RETURNING VARCHAR(100))
--> '{"x":1}'

You can also specify to use varbinary and the required encoding as return type.
The default encoding is UTF8::

SELECT json_object('x' : 1 RETURNING VARBINARY)
--> X'7b 22 78 22 3a 31 7d'

SELECT json_object('x' : 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF8)
--> X'7b 22 78 22 3a 31 7d'

SELECT json_object('x' : 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF16)
--> X'7b 00 22 00 78 00 22 00 3a 00 31 00 7d 00'

SELECT json_object('x' : 1 RETURNING VARBINARY FORMAT JSON ENCODING UTF32)
--> X'7b 00 00 00 22 00 00 00 78 00 00 00 22 00 00 00 3a 00 00 00 31 00 00 00 7d 00 00 00'

.. warning::

The following functions and operators are not compliant with the SQL
Expand Down