Skip to content

Commit 1056399

Browse files
adunstanadunstan
committed
New json functions.
json_build_array() and json_build_object allow for the construction of arbitrarily complex json trees. json_object() turns a one or two dimensional array, or two separate arrays, into a json_object of name/value pairs, similarly to the hstore() function. json_object_agg() aggregates its two arguments into a single json object as name value pairs. Catalog version bumped. Andrew Dunstan, reviewed by Marko Tiikkaja.
1 parent 9132b18 commit 1056399

File tree

10 files changed

+1219
-69
lines changed

10 files changed

+1219
-69
lines changed

‎doc/src/sgml/func.sgml

+158
Original file line numberDiff line numberDiff line change
@@ -10300,6 +10300,137 @@ table2-mapping
1030010300
<entry><literal>json_typeof('-123.4')</literal></entry>
1030110301
<entry><literal>number</literal></entry>
1030210302
</row>
10303+
<row>
10304+
<entry>
10305+
<indexterm>
10306+
<primary>json_build_array</primary>
10307+
</indexterm>
10308+
<literal>json_build_array(VARIADIC "any")</literal>
10309+
</entry>
10310+
<entry><type>json</type></entry>
10311+
<entry>
10312+
Builds a heterogeneously typed json array out of a variadic argument list.
10313+
</entry>
10314+
<entry><literal>SELECT json_build_array(1,2,'3',4,5);</literal></entry>
10315+
<entry>
10316+
<programlisting>
10317+
json_build_array
10318+
-------------------
10319+
[1, 2, "3", 4, 5]
10320+
</programlisting>
10321+
</entry>
10322+
</row>
10323+
<row>
10324+
<entry>
10325+
<indexterm>
10326+
<primary>json_build_object</primary>
10327+
</indexterm>
10328+
<literal>json_build_object(VARIADIC "any")</literal>
10329+
</entry>
10330+
<entry><type>json</type></entry>
10331+
<entry>
10332+
Builds a JSON array out of a variadic agument list. By convention, the object is
10333+
constructed out of alternating name/value arguments.
10334+
</entry>
10335+
<entry><literal>SELECT json_build_object('foo',1,'bar',2);</literal></entry>
10336+
<entry>
10337+
<programlisting>
10338+
json_build_object
10339+
------------------------
10340+
{"foo" : 1, "bar" : 2}
10341+
</programlisting>
10342+
</entry>
10343+
</row>
10344+
<row>
10345+
<entry>
10346+
<indexterm>
10347+
<primary>json_object</primary>
10348+
</indexterm>
10349+
<literal>json_object(text[])</literal>
10350+
</entry>
10351+
<entry><type>json</type></entry>
10352+
<entry>
10353+
Builds a JSON object out of a text array. The array must have either
10354+
exactly one dimension with an even number of members, in which case
10355+
they are taken as alternating name/value pairs, or two dimensions
10356+
such that each inner array has exactly two elements, which
10357+
are taken as a name/value pair.
10358+
</entry>
10359+
<entry><literal>select * from json_object('{a, 1, b, "def", c, 3.5}') or <literal>select * from json_object('{{a, 1},{b, "def"},{c, 3.5}}')</literal></literal></entry>
10360+
<entry>
10361+
<programlisting>
10362+
json_object
10363+
---------------------------------------
10364+
{"a" : "1", "b" : "def", "c" : "3.5"}
10365+
</programlisting>
10366+
</entry>
10367+
</row>
10368+
<row>
10369+
<entry>
10370+
<literal>json_object(keys text[], values text[])</literal>
10371+
</entry>
10372+
<entry><type>json</type></entry>
10373+
<entry>
10374+
The two argument form of JSON object takes keys and values pairwise from two separate
10375+
arrays. In all other respects it is identical to the one argument form.
10376+
</entry>
10377+
<entry><literal>select * from json_object('{a, b}', '{1,2}');</literal></entry>
10378+
<entry>
10379+
<programlisting>
10380+
json_object
10381+
------------------------
10382+
{"a" : "1", "b" : "2"}
10383+
</programlisting>
10384+
</entry>
10385+
</row>
10386+
<row>
10387+
<entry>
10388+
<indexterm>
10389+
<primary>json_to_record</primary>
10390+
</indexterm>
10391+
<literal>json_to_record(json, nested_as_text bool)</literal>
10392+
</entry>
10393+
<entry><type>record</type></entry>
10394+
<entry>
10395+
json_to_record returns an arbitrary record from a JSON object. As with all functions
10396+
returning 'record', the caller must explicitly define the structure of the record
10397+
when making the call. The input JSON must be an object, not a scalar or an array.
10398+
If nested_as_text is true, the function coerces nested complex elements to text.
10399+
Also, see notes below on columns and types.
10400+
</entry>
10401+
<entry><literal>select * from json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}',true) as x(a int, b text, d text) </literal></entry>
10402+
<entry>
10403+
<programlisting>
10404+
a | b | d
10405+
---+---------+---
10406+
1 | [1,2,3] |
10407+
</programlisting>
10408+
</entry>
10409+
</row>
10410+
<row>
10411+
<entry>
10412+
<indexterm>
10413+
<primary>json_to_recordset</primary>
10414+
</indexterm>
10415+
<literal>json_to_recordset(json, nested_as_text bool)</literal>
10416+
</entry>
10417+
<entry><type>setof record</type></entry>
10418+
<entry>
10419+
json_to_recordset returns an arbitrary set of records from a JSON object. As with
10420+
json_to_record, the structure of the record must be explicitly defined when making the
10421+
call. However, with json_to_recordset the input JSON must be an array containing
10422+
objects. nested_as_text works as with json_to_record.
10423+
</entry>
10424+
<entry><literal>select * from json_to_recordset('[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]',true) as x(a int, b text);</literal></entry>
10425+
<entry>
10426+
<programlisting>
10427+
a | b
10428+
---+-----
10429+
1 | foo
10430+
2 |
10431+
</programlisting>
10432+
</entry>
10433+
</row>
1030310434
</tbody>
1030410435
</tgroup>
1030510436
</table>
@@ -10324,6 +10455,17 @@ table2-mapping
1032410455
</para>
1032510456
</note>
1032610457

10458+
<note>
10459+
<para>
10460+
In json_to_record and json_to_recordset, type coercion from the JSON is
10461+
"best effort" and may not result in desired values for some types. JSON
10462+
elements are matched to identical field names in the record definition,
10463+
and elements which do not exist in the JSON will simply be NULL. JSON
10464+
elements which are not defined in the record template will
10465+
be omitted from the output.
10466+
</para>
10467+
</note>
10468+
1032710469
<note>
1032810470
<para>
1032910471
The <xref linkend="hstore"> extension has a cast from <type>hstore</type> to
@@ -11772,6 +11914,22 @@ NULL baz</literallayout>(3 rows)</entry>
1177211914
<entry>aggregates records as a JSON array of objects</entry>
1177311915
</row>
1177411916

11917+
<row>
11918+
<entry>
11919+
<indexterm>
11920+
<primary>json_object_agg</primary>
11921+
</indexterm>
11922+
<function>json_object_agg(<replaceable class="parameter">expression</replaceable>)</function>
11923+
</entry>
11924+
<entry>
11925+
<type>("any", "any")</type>
11926+
</entry>
11927+
<entry>
11928+
<type>json</type>
11929+
</entry>
11930+
<entry>aggregates name/value pairs as a JSON object</entry>
11931+
</row>
11932+
1177511933
<row>
1177611934
<entry>
1177711935
<indexterm>

0 commit comments

Comments
 (0)