Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Watch 1
Star 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 626a38f103
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '626a38f103'
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/functions-json.html

785 lines
68KB
Raw Blame History 

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.15. JSON Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="functions-xml.html" title="9.14. XML Functions" /><link rel="next" href="functions-sequence.html" title="9.16. Sequence Manipulation Functions" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.15. JSON Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-xml.html" title="9.14. XML Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-sequence.html" title="9.16. Sequence Manipulation Functions">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="FUNCTIONS-JSON"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.15. JSON Functions and Operators</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-JSON-PROCESSING">9.15.1. Processing and Creating JSON Data</a></span></dt><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-SQLJSON-PATH">9.15.2. The SQL/JSON Path Language</a></span></dt></dl></div><a id="id-1.5.8.20.2" class="indexterm"></a><p>

  3.    This section describes:

  4. 

  5.    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>

  6.       functions and operators for processing and creating JSON data

  7.      </p></li><li class="listitem"><p>

  8.       the SQL/JSON path language

  9.      </p></li></ul></div><p>

  10.   </p><p>

  11.    To learn more about the SQL/JSON standard, see

  12.    <a class="xref" href="biblio.html#SQLTR-19075-6" title="SQL Technical Report">[sqltr-19075-6]</a>. For details on JSON types

  13.    supported in <span class="productname">PostgreSQL</span>,

  14.    see <a class="xref" href="datatype-json.html" title="8.14. JSON Types">Section 8.14</a>.

  15.   </p><div class="sect2" id="FUNCTIONS-JSON-PROCESSING"><div class="titlepage"><div><div><h3 class="title">9.15.1. Processing and Creating JSON Data</h3></div></div></div><p>

  16.    <a class="xref" href="functions-json.html#FUNCTIONS-JSON-OP-TABLE" title="Table 9.44. json and jsonb Operators">Table 9.44</a> shows the operators that

  17.    are available for use with JSON data types (see <a class="xref" href="datatype-json.html" title="8.14. JSON Types">Section 8.14</a>).

  18.   </p><div class="table" id="FUNCTIONS-JSON-OP-TABLE"><p class="title"><strong>Table 9.44. <code class="type">json</code> and <code class="type">jsonb</code> Operators</strong></p><div class="table-contents"><table class="table" summary="json and jsonb Operators" border="1"><colgroup><col /><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Operator</th><th>Right Operand Type</th><th>Return type</th><th>Description</th><th>Example</th><th>Example Result</th></tr></thead><tbody><tr><td><code class="literal">-&gt;</code></td><td><code class="type">int</code></td><td><code class="type">json</code> or <code class="type">jsonb</code></td><td>Get JSON array element (indexed from zero, negative

  19.         integers count from the end)</td><td><code class="literal">'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json-&gt;2</code></td><td><code class="literal">{"c":"baz"}</code></td></tr><tr><td><code class="literal">-&gt;</code></td><td><code class="type">text</code></td><td><code class="type">json</code> or <code class="type">jsonb</code></td><td>Get JSON object field by key</td><td><code class="literal">'{"a": {"b":"foo"}}'::json-&gt;'a'</code></td><td><code class="literal">{"b":"foo"}</code></td></tr><tr><td><code class="literal">-&gt;&gt;</code></td><td><code class="type">int</code></td><td><code class="type">text</code></td><td>Get JSON array element as <code class="type">text</code></td><td><code class="literal">'[1,2,3]'::json-&gt;&gt;2</code></td><td><code class="literal">3</code></td></tr><tr><td><code class="literal">-&gt;&gt;</code></td><td><code class="type">text</code></td><td><code class="type">text</code></td><td>Get JSON object field as <code class="type">text</code></td><td><code class="literal">'{"a":1,"b":2}'::json-&gt;&gt;'b'</code></td><td><code class="literal">2</code></td></tr><tr><td><code class="literal">#&gt;</code></td><td><code class="type">text[]</code></td><td><code class="type">json</code> or <code class="type">jsonb</code></td><td>Get JSON object at the specified path</td><td><code class="literal">'{"a": {"b":{"c": "foo"}}}'::json#&gt;'{a,b}'</code></td><td><code class="literal">{"c": "foo"}</code></td></tr><tr><td><code class="literal">#&gt;&gt;</code></td><td><code class="type">text[]</code></td><td><code class="type">text</code></td><td>Get JSON object at the specified path as <code class="type">text</code></td><td><code class="literal">'{"a":[1,2,3],"b":[4,5,6]}'::json#&gt;&gt;'{a,2}'</code></td><td><code class="literal">3</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>

  20.     There are parallel variants of these operators for both the

  21.     <code class="type">json</code> and <code class="type">jsonb</code> types.

  22.     The field/element/path extraction operators

  23.     return the same type as their left-hand input (either <code class="type">json</code>

  24.     or <code class="type">jsonb</code>), except for those specified as

  25.     returning <code class="type">text</code>, which coerce the value to text.

  26.     The field/element/path extraction operators return NULL, rather than

  27.     failing, if the JSON input does not have the right structure to match

  28.     the request; for example if no such element exists.  The

  29.     field/element/path extraction operators that accept integer JSON

  30.     array subscripts all support negative subscripting from the end of

  31.     arrays.

  32.    </p></div><p>

  33.    The standard comparison operators shown in  <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for

  34.    <code class="type">jsonb</code>, but not for <code class="type">json</code>. They follow the

  35.    ordering rules for B-tree operations outlined at <a class="xref" href="datatype-json.html#JSON-INDEXING" title="8.14.4. jsonb Indexing">Section 8.14.4</a>.

  36.   </p><p>

  37.    Some further operators also exist only for <code class="type">jsonb</code>, as shown

  38.    in <a class="xref" href="functions-json.html#FUNCTIONS-JSONB-OP-TABLE" title="Table 9.45. Additional jsonb Operators">Table 9.45</a>.

  39.    Many of these operators can be indexed by

  40.    <code class="type">jsonb</code> operator classes.  For a full description of

  41.    <code class="type">jsonb</code> containment and existence semantics, see <a class="xref" href="datatype-json.html#JSON-CONTAINMENT" title="8.14.3. jsonb Containment and Existence">Section 8.14.3</a>.  <a class="xref" href="datatype-json.html#JSON-INDEXING" title="8.14.4. jsonb Indexing">Section 8.14.4</a>

  42.    describes how these operators can be used to effectively index

  43.    <code class="type">jsonb</code> data.

  44.   </p><div class="table" id="FUNCTIONS-JSONB-OP-TABLE"><p class="title"><strong>Table 9.45. Additional <code class="type">jsonb</code> Operators</strong></p><div class="table-contents"><table class="table" summary="Additional jsonb Operators" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Operator</th><th>Right Operand Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code class="literal">@&gt;</code></td><td><code class="type">jsonb</code></td><td>Does the left JSON value contain the right JSON

  45.         path/value entries at the top level?</td><td><code class="literal">'{"a":1, "b":2}'::jsonb @&gt; '{"b":2}'::jsonb</code></td></tr><tr><td><code class="literal">&lt;@</code></td><td><code class="type">jsonb</code></td><td>Are the left JSON path/value entries contained at the top level within

  46.         the right JSON value?</td><td><code class="literal">'{"b":2}'::jsonb &lt;@ '{"a":1, "b":2}'::jsonb</code></td></tr><tr><td><code class="literal">?</code></td><td><code class="type">text</code></td><td>Does the <span class="emphasis"><em>string</em></span> exist as a top-level

  47.         key within the JSON value?</td><td><code class="literal">'{"a":1, "b":2}'::jsonb ? 'b'</code></td></tr><tr><td><code class="literal">?|</code></td><td><code class="type">text[]</code></td><td>Do any of these array <span class="emphasis"><em>strings</em></span>

  48.         exist as top-level keys?</td><td><code class="literal">'{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'c']</code></td></tr><tr><td><code class="literal">?&amp;</code></td><td><code class="type">text[]</code></td><td>Do all of these array <span class="emphasis"><em>strings</em></span> exist

  49.         as top-level keys?</td><td><code class="literal">'["a", "b"]'::jsonb ?&amp; array['a', 'b']</code></td></tr><tr><td><code class="literal">||</code></td><td><code class="type">jsonb</code></td><td>Concatenate two <code class="type">jsonb</code> values into a new <code class="type">jsonb</code> value</td><td><code class="literal">'["a", "b"]'::jsonb || '["c", "d"]'::jsonb</code></td></tr><tr><td><code class="literal">-</code></td><td><code class="type">text</code></td><td>Delete key/value pair or <span class="emphasis"><em>string</em></span>

  50.         element from left operand.  Key/value pairs are matched based

  51.         on their key value.</td><td><code class="literal">'{"a": "b"}'::jsonb - 'a' </code></td></tr><tr><td><code class="literal">-</code></td><td><code class="type">text[]</code></td><td>Delete multiple key/value pairs or <span class="emphasis"><em>string</em></span>

  52.         elements from left operand.  Key/value pairs are matched based

  53.         on their key value.</td><td><code class="literal">'{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[] </code></td></tr><tr><td><code class="literal">-</code></td><td><code class="type">integer</code></td><td>Delete the array element with specified index (Negative

  54.         integers count from the end).  Throws an error if top level

  55.         container is not an array.</td><td><code class="literal">'["a", "b"]'::jsonb - 1 </code></td></tr><tr><td><code class="literal">#-</code></td><td><code class="type">text[]</code></td><td>Delete the field or element with specified path (for

  56.         JSON arrays, negative integers count from the end)</td><td><code class="literal">'["a", {"b":1}]'::jsonb #- '{1,b}'</code></td></tr><tr><td><code class="literal">@?</code></td><td><code class="type">jsonpath</code></td><td>Does JSON path return any item for the specified JSON value?</td><td><code class="literal">'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ &gt; 2)'</code></td></tr><tr><td><code class="literal">@@</code></td><td><code class="type">jsonpath</code></td><td>Returns the result of JSON path predicate check for the specified JSON value.

  57.         Only the first item of the result is taken into account.  If the

  58.         result is not Boolean, then <code class="literal">null</code> is returned.</td><td><code class="literal">'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] &gt; 2'</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>

  59.     The <code class="literal">||</code> operator concatenates the elements at the top level of

  60.     each of its operands. It does not operate recursively. For example, if

  61.     both operands are objects with a common key field name, the value of the

  62.     field in the result will just be the value from the right hand operand.

  63.    </p></div><div class="note"><h3 class="title">Note</h3><p>

  64.     The <code class="literal">@?</code> and <code class="literal">@@</code> operators suppress

  65.     the following errors: lacking object field or array element, unexpected

  66.     JSON item type, and numeric errors.

  67.     This behavior might be helpful while searching over JSON document

  68.     collections of varying structure.

  69.    </p></div><p>

  70.    <a class="xref" href="functions-json.html#FUNCTIONS-JSON-CREATION-TABLE" title="Table 9.46. JSON Creation Functions">Table 9.46</a> shows the functions that are

  71.    available for creating <code class="type">json</code> and <code class="type">jsonb</code> values.

  72.    (There are no equivalent functions for <code class="type">jsonb</code>, of the <code class="literal">row_to_json</code>

  73.    and <code class="literal">array_to_json</code> functions. However, the <code class="literal">to_jsonb</code>

  74.    function supplies much the same functionality as these functions would.)

  75.   </p><a id="id-1.5.8.20.5.11" class="indexterm"></a><a id="id-1.5.8.20.5.12" class="indexterm"></a><a id="id-1.5.8.20.5.13" class="indexterm"></a><a id="id-1.5.8.20.5.14" class="indexterm"></a><a id="id-1.5.8.20.5.15" class="indexterm"></a><a id="id-1.5.8.20.5.16" class="indexterm"></a><a id="id-1.5.8.20.5.17" class="indexterm"></a><a id="id-1.5.8.20.5.18" class="indexterm"></a><a id="id-1.5.8.20.5.19" class="indexterm"></a><a id="id-1.5.8.20.5.20" class="indexterm"></a><div class="table" id="FUNCTIONS-JSON-CREATION-TABLE"><p class="title"><strong>Table 9.46. JSON Creation Functions</strong></p><div class="table-contents"><table class="table" summary="JSON Creation Functions" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Function</th><th>Description</th><th>Example</th><th>Example Result</th></tr></thead><tbody><tr><td><p><code class="literal">to_json(anyelement)</code>

  76.           </p><p><code class="literal">to_jsonb(anyelement)</code>

  77.        </p></td><td>

  78.          Returns the value as <code class="type">json</code> or <code class="type">jsonb</code>.

  79.          Arrays and composites are converted

  80.          (recursively) to arrays and objects; otherwise, if there is a cast

  81.          from the type to <code class="type">json</code>, the cast function will be used to

  82.          perform the conversion; otherwise, a scalar value is produced.

  83.          For any scalar type other than a number, a Boolean, or a null value,

  84.          the text representation will be used, in such a fashion that it is a

  85.          valid <code class="type">json</code> or <code class="type">jsonb</code> value.

  86.        </td><td><code class="literal">to_json('Fred said "Hi."'::text)</code></td><td><code class="literal">"Fred said \"Hi.\""</code></td></tr><tr><td>

  87.          <code class="literal">array_to_json(anyarray [, pretty_bool])</code>

  88.        </td><td>

  89.          Returns the array as a JSON array. A PostgreSQL multidimensional array

  90.          becomes a JSON array of arrays. Line feeds will be added between

  91.          dimension-1 elements if <em class="parameter"><code>pretty_bool</code></em> is true.

  92.        </td><td><code class="literal">array_to_json('{{1,5},{99,100}}'::int[])</code></td><td><code class="literal">[[1,5],[99,100]]</code></td></tr><tr><td>

  93.          <code class="literal">row_to_json(record [, pretty_bool])</code>

  94.        </td><td>

  95.          Returns the row as a JSON object. Line feeds will be added between

  96.          level-1 elements if <em class="parameter"><code>pretty_bool</code></em> is true.

  97.        </td><td><code class="literal">row_to_json(row(1,'foo'))</code></td><td><code class="literal">{"f1":1,"f2":"foo"}</code></td></tr><tr><td><p><code class="literal">json_build_array(VARIADIC "any")</code>

  98.           </p><p><code class="literal">jsonb_build_array(VARIADIC "any")</code>

  99.        </p></td><td>

  100.          Builds a possibly-heterogeneously-typed JSON array out of a variadic

  101.          argument list.

  102.        </td><td><code class="literal">json_build_array(1,2,'3',4,5)</code></td><td><code class="literal">[1, 2, "3", 4, 5]</code></td></tr><tr><td><p><code class="literal">json_build_object(VARIADIC "any")</code>

  103.           </p><p><code class="literal">jsonb_build_object(VARIADIC "any")</code>

  104.        </p></td><td>

  105.          Builds a JSON object out of a variadic argument list.  By

  106.          convention, the argument list consists of alternating

  107.          keys and values.

  108.        </td><td><code class="literal">json_build_object('foo',1,'bar',2)</code></td><td><code class="literal">{"foo": 1, "bar": 2}</code></td></tr><tr><td><p><code class="literal">json_object(text[])</code>

  109.           </p><p><code class="literal">jsonb_object(text[])</code>

  110.        </p></td><td>

  111.          Builds a JSON object out of a text array.  The array must have either

  112.          exactly one dimension with an even number of members, in which case

  113.          they are taken as alternating key/value pairs, or two dimensions

  114.          such that each inner array has exactly two elements, which

  115.          are taken as a key/value pair.

  116.        </td><td><p><code class="literal">json_object('{a, 1, b, "def", c, 3.5}')</code></p>

  117.         <p><code class="literal">json_object('{{a, 1},{b, "def"},{c, 3.5}}')</code></p></td><td><code class="literal">{"a": "1", "b": "def", "c": "3.5"}</code></td></tr><tr><td><p><code class="literal">json_object(keys text[], values text[])</code>

  118.           </p><p><code class="literal">jsonb_object(keys text[], values text[])</code>

  119.        </p></td><td>

  120.          This form of <code class="function">json_object</code> takes keys and values pairwise from two separate

  121.          arrays. In all other respects it is identical to the one-argument form.

  122.        </td><td><code class="literal">json_object('{a, b}', '{1,2}')</code></td><td><code class="literal">{"a": "1", "b": "2"}</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>

  123.      <code class="function">array_to_json</code> and <code class="function">row_to_json</code> have the same

  124.      behavior as <code class="function">to_json</code> except for offering a pretty-printing

  125.      option.  The behavior described for <code class="function">to_json</code> likewise applies

  126.      to each individual value converted by the other JSON creation functions.

  127.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  128.      The <a class="xref" href="hstore.html" title="F.16. hstore">hstore</a> extension has a cast

  129.      from <code class="type">hstore</code> to <code class="type">json</code>, so that

  130.      <code class="type">hstore</code> values converted via the JSON creation functions

  131.      will be represented as JSON objects, not as primitive string values.

  132.     </p></div><p>

  133.    <a class="xref" href="functions-json.html#FUNCTIONS-JSON-PROCESSING-TABLE" title="Table 9.47. JSON Processing Functions">Table 9.47</a> shows the functions that

  134.    are available for processing <code class="type">json</code> and <code class="type">jsonb</code> values.

  135.   </p><a id="id-1.5.8.20.5.25" class="indexterm"></a><a id="id-1.5.8.20.5.26" class="indexterm"></a><a id="id-1.5.8.20.5.27" class="indexterm"></a><a id="id-1.5.8.20.5.28" class="indexterm"></a><a id="id-1.5.8.20.5.29" class="indexterm"></a><a id="id-1.5.8.20.5.30" class="indexterm"></a><a id="id-1.5.8.20.5.31" class="indexterm"></a><a id="id-1.5.8.20.5.32" class="indexterm"></a><a id="id-1.5.8.20.5.33" class="indexterm"></a><a id="id-1.5.8.20.5.34" class="indexterm"></a><a id="id-1.5.8.20.5.35" class="indexterm"></a><a id="id-1.5.8.20.5.36" class="indexterm"></a><a id="id-1.5.8.20.5.37" class="indexterm"></a><a id="id-1.5.8.20.5.38" class="indexterm"></a><a id="id-1.5.8.20.5.39" class="indexterm"></a><a id="id-1.5.8.20.5.40" class="indexterm"></a><a id="id-1.5.8.20.5.41" class="indexterm"></a><a id="id-1.5.8.20.5.42" class="indexterm"></a><a id="id-1.5.8.20.5.43" class="indexterm"></a><a id="id-1.5.8.20.5.44" class="indexterm"></a><a id="id-1.5.8.20.5.45" class="indexterm"></a><a id="id-1.5.8.20.5.46" class="indexterm"></a><a id="id-1.5.8.20.5.47" class="indexterm"></a><a id="id-1.5.8.20.5.48" class="indexterm"></a><a id="id-1.5.8.20.5.49" class="indexterm"></a><a id="id-1.5.8.20.5.50" class="indexterm"></a><a id="id-1.5.8.20.5.51" class="indexterm"></a><a id="id-1.5.8.20.5.52" class="indexterm"></a><a id="id-1.5.8.20.5.53" class="indexterm"></a><a id="id-1.5.8.20.5.54" class="indexterm"></a><a id="id-1.5.8.20.5.55" class="indexterm"></a><a id="id-1.5.8.20.5.56" class="indexterm"></a><a id="id-1.5.8.20.5.57" class="indexterm"></a><a id="id-1.5.8.20.5.58" class="indexterm"></a><a id="id-1.5.8.20.5.59" class="indexterm"></a><a id="id-1.5.8.20.5.60" class="indexterm"></a><div class="table" id="FUNCTIONS-JSON-PROCESSING-TABLE"><p class="title"><strong>Table 9.47. JSON Processing Functions</strong></p><div class="table-contents"><table class="table" summary="JSON Processing Functions" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Function</th><th>Return Type</th><th>Description</th><th>Example</th><th>Example Result</th></tr></thead><tbody><tr><td><p><code class="literal">json_array_length(json)</code>

  136.          </p><p><code class="literal">jsonb_array_length(jsonb)</code>

  137.        </p></td><td><code class="type">int</code></td><td>

  138.          Returns the number of elements in the outermost JSON array.

  139.        </td><td><code class="literal">json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]')</code></td><td><code class="literal">5</code></td></tr><tr><td><p><code class="literal">json_each(json)</code>

  140.          </p><p><code class="literal">jsonb_each(jsonb)</code>

  141.        </p></td><td><p><code class="literal">setof key text, value json</code>

  142.          </p><p><code class="literal">setof key text, value jsonb</code>

  143.        </p></td><td>

  144.          Expands the outermost JSON object into a set of key/value pairs.

  145.        </td><td><code class="literal">select * from json_each('{"a":"foo", "b":"bar"}')</code></td><td>

  146. <pre class="programlisting">

  147.  key | value

  148. -----+-------

  149.  a   | "foo"

  150.  b   | "bar"

  151. </pre>

  152.        </td></tr><tr><td><p><code class="literal">json_each_text(json)</code>

  153.          </p><p><code class="literal">jsonb_each_text(jsonb)</code>

  154.        </p></td><td><code class="type">setof key text, value text</code></td><td>

  155.          Expands the outermost JSON object into a set of key/value pairs. The

  156.          returned values will be of type <code class="type">text</code>.

  157.        </td><td><code class="literal">select * from json_each_text('{"a":"foo", "b":"bar"}')</code></td><td>

  158. <pre class="programlisting">

  159.  key | value

  160. -----+-------

  161.  a   | foo

  162.  b   | bar

  163. </pre>

  164.        </td></tr><tr><td><p><code class="literal">json_extract_path(from_json json, VARIADIC path_elems text[])</code>

  165.         </p><p><code class="literal">jsonb_extract_path(from_json jsonb, VARIADIC path_elems text[])</code>

  166.        </p></td><td><p><code class="type">json</code></p><p><code class="type">jsonb</code>

  167.        </p></td><td>

  168.          Returns JSON value pointed to by <em class="replaceable"><code>path_elems</code></em>

  169.          (equivalent to <code class="literal">#&gt;</code> operator).

  170.        </td><td><code class="literal">json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4')</code></td><td><code class="literal">{"f5":99,"f6":"foo"}</code></td></tr><tr><td><p><code class="literal">json_extract_path_text(from_json json, VARIADIC path_elems text[])</code>

  171.          </p><p><code class="literal">jsonb_extract_path_text(from_json jsonb, VARIADIC path_elems text[])</code>

  172.        </p></td><td><code class="type">text</code></td><td>

  173.          Returns JSON value pointed to by <em class="replaceable"><code>path_elems</code></em>

  174.          as <code class="type">text</code>

  175.          (equivalent to <code class="literal">#&gt;&gt;</code> operator).

  176.        </td><td><code class="literal">json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4', 'f6')</code></td><td><code class="literal">foo</code></td></tr><tr><td><p><code class="literal">json_object_keys(json)</code>

  177.          </p><p><code class="literal">jsonb_object_keys(jsonb)</code>

  178.        </p></td><td><code class="type">setof text</code></td><td>

  179.           Returns set of keys in the outermost JSON object.

  180.        </td><td><code class="literal">json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}')</code></td><td>

  181. <pre class="programlisting">

  182.  json_object_keys

  183. ------------------

  184.  f1

  185.  f2

  186. </pre>

  187.        </td></tr><tr><td><p><code class="literal">json_populate_record(base anyelement, from_json json)</code>

  188.          </p><p><code class="literal">jsonb_populate_record(base anyelement, from_json jsonb)</code>

  189.        </p></td><td><code class="type">anyelement</code></td><td>

  190.          Expands the object in <em class="replaceable"><code>from_json</code></em> to a row

  191.          whose columns match the record type defined by <em class="replaceable"><code>base</code></em>

  192.          (see note below).

  193.        </td><td><code class="literal">select * from json_populate_record(null::myrowtype, '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a  b c"}}')</code></td><td>

  194. <pre class="programlisting">

  195.  a |   b       |      c

  196. ---+-----------+-------------

  197.  1 | {2,"a b"} | (4,"a b c")

  198. </pre>

  199.        </td></tr><tr><td><p><code class="literal">json_populate_recordset(base anyelement, from_json json)</code>

  200.          </p><p><code class="literal">jsonb_populate_recordset(base anyelement, from_json jsonb)</code>

  201.        </p></td><td><code class="type">setof anyelement</code></td><td>

  202.          Expands the outermost array of objects

  203.          in <em class="replaceable"><code>from_json</code></em> to a set of rows whose

  204.          columns match the record type defined by <em class="replaceable"><code>base</code></em> (see

  205.          note below).

  206.        </td><td><code class="literal">select * from json_populate_recordset(null::myrowtype, '[{"a":1,"b":2},{"a":3,"b":4}]')</code></td><td>

  207. <pre class="programlisting">

  208.  a | b

  209. ---+---

  210.  1 | 2

  211.  3 | 4

  212. </pre>

  213.        </td></tr><tr><td><p><code class="literal">json_array_elements(json)</code>

  214.          </p><p><code class="literal">jsonb_array_elements(jsonb)</code>

  215.        </p></td><td><p><code class="type">setof json</code>

  216.          </p><p><code class="type">setof jsonb</code>

  217.        </p></td><td>

  218.          Expands a JSON array to a set of JSON values.

  219.        </td><td><code class="literal">select * from json_array_elements('[1,true, [2,false]]')</code></td><td>

  220. <pre class="programlisting">

  221.    value

  222. -----------

  223.  1

  224.  true

  225.  [2,false]

  226. </pre>

  227.        </td></tr><tr><td><p><code class="literal">json_array_elements_text(json)</code>

  228.          </p><p><code class="literal">jsonb_array_elements_text(jsonb)</code>

  229.        </p></td><td><code class="type">setof text</code></td><td>

  230.          Expands a JSON array to a set of <code class="type">text</code> values.

  231.        </td><td><code class="literal">select * from json_array_elements_text('["foo", "bar"]')</code></td><td>

  232. <pre class="programlisting">

  233.    value

  234. -----------

  235.  foo

  236.  bar

  237. </pre>

  238.        </td></tr><tr><td><p><code class="literal">json_typeof(json)</code>

  239.          </p><p><code class="literal">jsonb_typeof(jsonb)</code>

  240.        </p></td><td><code class="type">text</code></td><td>

  241.          Returns the type of the outermost JSON value as a text string.

  242.          Possible types are

  243.          <code class="literal">object</code>, <code class="literal">array</code>, <code class="literal">string</code>, <code class="literal">number</code>,

  244.          <code class="literal">boolean</code>, and <code class="literal">null</code>.

  245.        </td><td><code class="literal">json_typeof('-123.4')</code></td><td><code class="literal">number</code></td></tr><tr><td><p><code class="literal">json_to_record(json)</code>

  246.           </p><p><code class="literal">jsonb_to_record(jsonb)</code>

  247.        </p></td><td><code class="type">record</code></td><td>

  248.          Builds an arbitrary record from a JSON object (see note below).  As

  249.          with all functions returning <code class="type">record</code>, the caller must

  250.          explicitly define the structure of the record with an <code class="literal">AS</code>

  251.          clause.

  252.        </td><td><code class="literal">select * from json_to_record('{"a":1,"b":[1,2,3],"c":[1,2,3],"e":"bar","r": {"a": 123, "b": "a b c"}}') as x(a int, b text, c int[], d text, r myrowtype) </code></td><td>

  253. <pre class="programlisting">

  254.  a |    b    |    c    | d |       r

  255. ---+---------+---------+---+---------------

  256.  1 | [1,2,3] | {1,2,3} |   | (123,"a b c")

  257. </pre>

  258.        </td></tr><tr><td><p><code class="literal">json_to_recordset(json)</code>

  259.          </p><p><code class="literal">jsonb_to_recordset(jsonb)</code>

  260.        </p></td><td><code class="type">setof record</code></td><td>

  261.          Builds an arbitrary set of records from a JSON array of objects (see

  262.          note below).  As with all functions returning <code class="type">record</code>, the

  263.          caller must explicitly define the structure of the record with

  264.          an <code class="literal">AS</code> clause.

  265.        </td><td><code class="literal">select * from json_to_recordset('[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]') as x(a int, b text);</code></td><td>

  266. <pre class="programlisting">

  267.  a |  b

  268. ---+-----

  269.  1 | foo

  270.  2 |

  271. </pre>

  272.        </td></tr><tr><td><p><code class="literal">json_strip_nulls(from_json json)</code>

  273.          </p><p><code class="literal">jsonb_strip_nulls(from_json jsonb)</code>

  274.        </p></td><td><p><code class="type">json</code></p><p><code class="type">jsonb</code></p></td><td>

  275.          Returns <em class="replaceable"><code>from_json</code></em>

  276.          with all object fields that have null values omitted. Other null values

  277.          are untouched.

  278.        </td><td><code class="literal">json_strip_nulls('[{"f1":1,"f2":null},2,null,3]')</code></td><td><code class="literal">[{"f1":1},2,null,3]</code></td></tr><tr><td><p><code class="literal">jsonb_set(target jsonb, path text[], new_value jsonb [<span class="optional">, create_missing boolean</span>])</code>

  279.          </p></td><td><p><code class="type">jsonb</code></p></td><td>

  280.          Returns <em class="replaceable"><code>target</code></em>

  281.          with the section designated by <em class="replaceable"><code>path</code></em>

  282.          replaced by <em class="replaceable"><code>new_value</code></em>, or with

  283.          <em class="replaceable"><code>new_value</code></em> added if

  284.          <em class="replaceable"><code>create_missing</code></em> is true (default is

  285.          <code class="literal">true</code>) and the item

  286.          designated by <em class="replaceable"><code>path</code></em> does not exist.

  287.          As with the path oriented operators, negative integers that

  288.          appear in <em class="replaceable"><code>path</code></em> count from the end

  289.          of JSON arrays.

  290.        </td><td><p><code class="literal">jsonb_set('[{"f1":1,"f2":null},2,null,3]', '{0,f1}','[2,3,4]', false)</code>

  291.          </p><p><code class="literal">jsonb_set('[{"f1":1,"f2":null},2]', '{0,f3}','[2,3,4]')</code>

  292.          </p></td><td><p><code class="literal">[{"f1":[2,3,4],"f2":null},2,null,3]</code>

  293.          </p><p><code class="literal">[{"f1": 1, "f2": null, "f3": [2, 3, 4]}, 2]</code>

  294.         </p></td></tr><tr><td>

  295.            <p><code class="literal">

  296.            jsonb_insert(target jsonb, path text[], new_value jsonb [<span class="optional">, insert_after boolean</span>])

  297.            </code></p>

  298.        </td><td><p><code class="type">jsonb</code></p></td><td>

  299.          Returns <em class="replaceable"><code>target</code></em> with

  300.          <em class="replaceable"><code>new_value</code></em> inserted. If

  301.          <em class="replaceable"><code>target</code></em> section designated by

  302.          <em class="replaceable"><code>path</code></em> is in a JSONB array,

  303.          <em class="replaceable"><code>new_value</code></em> will be inserted before target or

  304.          after if <em class="replaceable"><code>insert_after</code></em> is true (default is

  305.          <code class="literal">false</code>). If <em class="replaceable"><code>target</code></em> section

  306.          designated by <em class="replaceable"><code>path</code></em> is in JSONB object,

  307.          <em class="replaceable"><code>new_value</code></em> will be inserted only if

  308.          <em class="replaceable"><code>target</code></em> does not exist. As with the path

  309.          oriented operators, negative integers that appear in

  310.          <em class="replaceable"><code>path</code></em> count from the end of JSON arrays.

  311.        </td><td>

  312.            <p><code class="literal">

  313.                jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"')

  314.            </code></p>

  315.            <p><code class="literal">

  316.                jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"', true)

  317.            </code></p>

  318.        </td><td><p><code class="literal">{"a": [0, "new_value", 1, 2]}</code>

  319.          </p><p><code class="literal">{"a": [0, 1, "new_value", 2]}</code>

  320.         </p></td></tr><tr><td><p><code class="literal">jsonb_pretty(from_json jsonb)</code>

  321.          </p></td><td><p><code class="type">text</code></p></td><td>

  322.          Returns <em class="replaceable"><code>from_json</code></em>

  323.          as indented JSON text.

  324.        </td><td><code class="literal">jsonb_pretty('[{"f1":1,"f2":null},2,null,3]')</code></td><td>

  325. <pre class="programlisting">

  326. [

  327.     {

  328.         "f1": 1,

  329.         "f2": null

  330.     },

  331.     2,

  332.     null,

  333.     3

  334. ]

  335. </pre>

  336.         </td></tr><tr><td>

  337.          <p><code class="literal">

  338.            jsonb_path_exists(target jsonb, path jsonpath [<span class="optional">, vars jsonb [<span class="optional">, silent bool</span>]</span>])

  339.          </code></p>

  340.         </td><td><code class="type">boolean</code></td><td>

  341.           Checks whether JSON path returns any item for the specified JSON

  342.           value.

  343.         </td><td>

  344.          <p><code class="literal">

  345.            jsonb_path_exists('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2,"max":4}')

  346.          </code></p>

  347.         </td><td>

  348.           <p><code class="literal">true</code></p>

  349.         </td></tr><tr><td>

  350.          <p><code class="literal">

  351.            jsonb_path_match(target jsonb, path jsonpath [<span class="optional">, vars jsonb [<span class="optional">, silent bool</span>]</span>])

  352.          </code></p>

  353.         </td><td><code class="type">boolean</code></td><td>

  354.           Returns the result of JSON path predicate check for the specified JSON value.

  355.           Only the first item of the result is taken into account.  If the

  356.           result is not Boolean, then <code class="literal">null</code> is returned.

  357.         </td><td>

  358.          <p><code class="literal">

  359.            jsonb_path_match('{"a":[1,2,3,4,5]}', 'exists($.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max))', '{"min":2,"max":4}')

  360.         </code></p>

  361.         </td><td>

  362.           <p><code class="literal">true</code></p>

  363.         </td></tr><tr><td>

  364.          <p><code class="literal">

  365.            jsonb_path_query(target jsonb, path jsonpath [<span class="optional">, vars jsonb [<span class="optional">, silent bool</span>]</span>])

  366.          </code></p>

  367.         </td><td><code class="type">setof jsonb</code></td><td>

  368.           Gets all JSON items returned by JSON path for the specified JSON

  369.           value.

  370.         </td><td>

  371.          <p><code class="literal">

  372.            select * from jsonb_path_query('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2,"max":4}');

  373.          </code></p>

  374.         </td><td>

  375.          <p>

  376. </p><pre class="programlisting">

  377.  jsonb_path_query

  378. ------------------

  379.  2

  380.  3

  381.  4

  382. </pre><p>

  383.          </p>

  384.         </td></tr><tr><td>

  385.          <p><code class="literal">

  386.            jsonb_path_query_array(target jsonb, path jsonpath [<span class="optional">, vars jsonb [<span class="optional">, silent bool</span>]</span>])

  387.          </code></p>

  388.         </td><td><code class="type">jsonb</code></td><td>

  389.           Gets all JSON items returned by JSON path for the specified JSON

  390.           value and wraps result into an array.

  391.         </td><td>

  392.          <p><code class="literal">

  393.            jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2,"max":4}')

  394.          </code></p>

  395.         </td><td>

  396.           <p><code class="literal">[2, 3, 4]</code></p>

  397.         </td></tr><tr><td>

  398.          <p><code class="literal">

  399.            jsonb_path_query_first(target jsonb, path jsonpath [<span class="optional">, vars jsonb [<span class="optional">, silent bool</span>]</span>])

  400.          </code></p>

  401.         </td><td><code class="type">jsonb</code></td><td>

  402.           Gets the first JSON item returned by JSON path for the specified JSON

  403.           value.  Returns <code class="literal">NULL</code> on no results.

  404.         </td><td>

  405.          <p><code class="literal">

  406.            jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2,"max":4}')

  407.          </code></p>

  408.         </td><td>

  409.           <p><code class="literal">2</code></p>

  410.         </td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>

  411.       Many of these functions and operators will convert Unicode escapes in

  412.       JSON strings to the appropriate single character.  This is a non-issue

  413.       if the input is type <code class="type">jsonb</code>, because the conversion was already

  414.       done; but for <code class="type">json</code> input, this may result in throwing an error,

  415.       as noted in <a class="xref" href="datatype-json.html" title="8.14. JSON Types">Section 8.14</a>.

  416.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  417.     The functions

  418.     <code class="function">json[b]_populate_record</code>,

  419.     <code class="function">json[b]_populate_recordset</code>,

  420.     <code class="function">json[b]_to_record</code> and

  421.     <code class="function">json[b]_to_recordset</code>

  422.     operate on a JSON object, or array of objects, and extract the values

  423.     associated with keys whose names match column names of the output row

  424.     type.

  425.     Object fields that do not correspond to any output column name are

  426.     ignored, and output columns that do not match any object field will be

  427.     filled with nulls.

  428.     To convert a JSON value to the SQL type of an output column, the

  429.     following rules are applied in sequence:

  430.     </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>

  431.        A JSON null value is converted to a SQL null in all cases.

  432.       </p></li><li class="listitem"><p>

  433.        If the output column is of type <code class="type">json</code>

  434.        or <code class="type">jsonb</code>, the JSON value is just reproduced exactly.

  435.       </p></li><li class="listitem"><p>

  436.        If the output column is a composite (row) type, and the JSON value is

  437.        a JSON object, the fields of the object are converted to columns of

  438.        the output row type by recursive application of these rules.

  439.       </p></li><li class="listitem"><p>

  440.        Likewise, if the output column is an array type and the JSON value is

  441.        a JSON array, the elements of the JSON array are converted to elements

  442.        of the output array by recursive application of these rules.

  443.       </p></li><li class="listitem"><p>

  444.        Otherwise, if the JSON value is a string literal, the contents of the

  445.        string are fed to the input conversion function for the column's data

  446.        type.

  447.       </p></li><li class="listitem"><p>

  448.        Otherwise, the ordinary text representation of the JSON value is fed

  449.        to the input conversion function for the column's data type.

  450.       </p></li></ul></div><p>

  451.    </p><p>

  452.     While the examples for these functions use constants, the typical use

  453.     would be to reference a table in the <code class="literal">FROM</code> clause

  454.     and use one of its <code class="type">json</code> or <code class="type">jsonb</code> columns

  455.     as an argument to the function.  Extracted key values can then be

  456.     referenced in other parts of the query, like <code class="literal">WHERE</code>

  457.     clauses and target lists.  Extracting multiple values in this

  458.     way can improve performance over extracting them separately with

  459.     per-key operators.

  460.    </p></div><div class="note"><h3 class="title">Note</h3><p>

  461.       All the items of the <code class="literal">path</code> parameter of <code class="literal">jsonb_set</code>

  462.       as well as <code class="literal">jsonb_insert</code> except the last item must be present

  463.       in the <code class="literal">target</code>. If <code class="literal">create_missing</code> is false, all

  464.       items of the <code class="literal">path</code> parameter of <code class="literal">jsonb_set</code> must be

  465.       present. If these conditions are not met the <code class="literal">target</code> is

  466.       returned unchanged.

  467.     </p><p>

  468.       If the last path item is an object key, it will be created if it

  469.       is absent and given the new value. If the last path item is an array

  470.       index, if it is positive the item to set is found by counting from

  471.       the left, and if negative by counting from the right - <code class="literal">-1</code>

  472.       designates the rightmost element, and so on.

  473.       If the item is out of the range -array_length .. array_length -1,

  474.       and create_missing is true, the new value is added at the beginning

  475.       of the array if the item is negative, and at the end of the array if

  476.       it is positive.

  477.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  478.       The <code class="literal">json_typeof</code> function's <code class="literal">null</code> return value

  479.       should not be confused with a SQL NULL.  While

  480.       calling <code class="literal">json_typeof('null'::json)</code> will

  481.       return <code class="literal">null</code>, calling <code class="literal">json_typeof(NULL::json)</code>

  482.       will return a SQL NULL.

  483.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  484.       If the argument to <code class="literal">json_strip_nulls</code> contains duplicate

  485.       field names in any object, the result could be semantically somewhat

  486.       different, depending on the order in which they occur. This is not an

  487.       issue for <code class="literal">jsonb_strip_nulls</code> since <code class="type">jsonb</code> values never have

  488.       duplicate object field names.

  489.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  490.     The <code class="literal">jsonb_path_exists</code>, <code class="literal">jsonb_path_match</code>,

  491.     <code class="literal">jsonb_path_query</code>, <code class="literal">jsonb_path_query_array</code>, and

  492.     <code class="literal">jsonb_path_query_first</code>

  493.     functions have optional <code class="literal">vars</code> and <code class="literal">silent</code>

  494.     arguments.

  495.    </p><p>

  496.     If the <em class="parameter"><code>vars</code></em> argument is specified, it provides an

  497.     object containing named variables to be substituted into a

  498.     <code class="literal">jsonpath</code> expression.

  499.    </p><p>

  500.     If the <em class="parameter"><code>silent</code></em> argument is specified and has the

  501.     <code class="literal">true</code> value, these functions suppress the same errors

  502.     as the <code class="literal">@?</code> and <code class="literal">@@</code> operators.

  503.    </p></div><p>

  504.     See also <a class="xref" href="functions-aggregate.html" title="9.20. Aggregate Functions">Section 9.20</a> for the aggregate

  505.     function <code class="function">json_agg</code> which aggregates record

  506.     values as JSON, and the aggregate function

  507.     <code class="function">json_object_agg</code> which aggregates pairs of values

  508.     into a JSON object, and their <code class="type">jsonb</code> equivalents,

  509.     <code class="function">jsonb_agg</code> and <code class="function">jsonb_object_agg</code>.

  510.   </p></div><div class="sect2" id="FUNCTIONS-SQLJSON-PATH"><div class="titlepage"><div><div><h3 class="title">9.15.2. The SQL/JSON Path Language</h3></div></div></div><a id="id-1.5.8.20.6.2" class="indexterm"></a><p>

  511.    SQL/JSON path expressions specify the items to be retrieved

  512.    from the JSON data, similar to XPath expressions used

  513.    for SQL access to XML. In <span class="productname">PostgreSQL</span>,

  514.    path expressions are implemented as the <code class="type">jsonpath</code>

  515.    data type and can use any elements described in

  516.    <a class="xref" href="datatype-json.html#DATATYPE-JSONPATH" title="8.14.6. jsonpath Type">Section 8.14.6</a>.

  517.   </p><p>JSON query functions and operators

  518.    pass the provided path expression to the <em class="firstterm">path engine</em>

  519.    for evaluation. If the expression matches the queried JSON data,

  520.    the corresponding SQL/JSON item is returned.

  521.    Path expressions are written in the SQL/JSON path language

  522.    and can also include arithmetic expressions and functions.

  523.    Query functions treat the provided expression as a

  524.    text string, so it must be enclosed in single quotes.

  525.   </p><p>

  526.    A path expression consists of a sequence of elements allowed

  527.    by the <code class="type">jsonpath</code> data type.

  528.    The path expression is evaluated from left to right, but

  529.    you can use parentheses to change the order of operations.

  530.    If the evaluation is successful, a sequence of SQL/JSON items

  531.    (<em class="firstterm">SQL/JSON sequence</em>) is produced,

  532.    and the evaluation result is returned to the JSON query function

  533.    that completes the specified computation.

  534.   </p><p>

  535.    To refer to the JSON data to be queried (the

  536.    <em class="firstterm">context item</em>), use the <code class="literal">$</code> sign

  537.    in the path expression. It can be followed by one or more

  538.    <a class="link" href="datatype-json.html#TYPE-JSONPATH-ACCESSORS" title="Table 8.25. jsonpath Accessors">accessor operators</a>,

  539.    which go down the JSON structure level by level to retrieve the

  540.    content of context item. Each operator that follows deals with the

  541.    result of the previous evaluation step.

  542.   </p><p>

  543.    For example, suppose you have some JSON data from a GPS tracker that you

  544.    would like to parse, such as:

  545. </p><pre class="programlisting">

  546. {

  547.   "track": {

  548.     "segments": [

  549.       {

  550.         "location":   [ 47.763, 13.4034 ],

  551.         "start time": "2018-10-14 10:05:14",

  552.         "HR": 73

  553.       },

  554.       {

  555.         "location":   [ 47.706, 13.2635 ],

  556.         "start time": "2018-10-14 10:39:21",

  557.         "HR": 135

  558.       }

  559.     ]

  560.   }

  561. }

  562. </pre><p>

  563.   </p><p>

  564.    To retrieve the available track segments, you need to use the

  565.    <code class="literal">.<em class="replaceable"><code>key</code></em></code> accessor

  566.    operator for all the preceding JSON objects:

  567. </p><pre class="programlisting">

  568. '$.track.segments'

  569. </pre><p>

  570.   </p><p>

  571.    If the item to retrieve is an element of an array, you have

  572.    to unnest this array using the <code class="literal">[*]</code> operator. For example,

  573.    the following path will return location coordinates for all

  574.    the available track segments:

  575. </p><pre class="programlisting">

  576. '$.track.segments[*].location'

  577. </pre><p>

  578.   </p><p>

  579.    To return the coordinates of the first segment only, you can

  580.    specify the corresponding subscript in the <code class="literal">[]</code>

  581.    accessor operator. Note that the SQL/JSON arrays are 0-relative:

  582. </p><pre class="programlisting">

  583. '$.track.segments[0].location'

  584. </pre><p>

  585.   </p><p>

  586.    The result of each path evaluation step can be processed

  587.    by one or more <code class="type">jsonpath</code> operators and methods

  588.    listed in <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS" title="9.15.2.3. SQL/JSON Path Operators and Methods">Section 9.15.2.3</a>.

  589.    Each method name must be preceded by a dot. For example,

  590.    you can get an array size:

  591. </p><pre class="programlisting">

  592. '$.track.segments.size()'

  593. </pre><p>

  594.    For more examples of using <code class="type">jsonpath</code> operators

  595.    and methods within path expressions, see

  596.    <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS" title="9.15.2.3. SQL/JSON Path Operators and Methods">Section 9.15.2.3</a>.

  597.   </p><p>

  598.    When defining the path, you can also use one or more

  599.    <em class="firstterm">filter expressions</em> that work similar to the

  600.    <code class="literal">WHERE</code> clause in SQL. A filter expression begins with

  601.    a question mark and provides a condition in parentheses:

  602. 

  603. </p><pre class="programlisting">

  604. ? (<em class="replaceable"><code>condition</code></em>)

  605. </pre><p>

  606.   </p><p>

  607.    Filter expressions must be specified right after the path evaluation step

  608.    to which they are applied. The result of this step is filtered to include

  609.    only those items that satisfy the provided condition. SQL/JSON defines

  610.    three-valued logic, so the condition can be <code class="literal">true</code>, <code class="literal">false</code>,

  611.    or <code class="literal">unknown</code>. The <code class="literal">unknown</code> value

  612.    plays the same role as SQL <code class="literal">NULL</code> and can be tested

  613.    for with the <code class="literal">is unknown</code> predicate. Further path

  614.    evaluation steps use only those items for which filter expressions

  615.    return <code class="literal">true</code>.

  616.   </p><p>

  617.    Functions and operators that can be used in filter expressions are listed

  618.    in <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-FILTER-EX-TABLE" title="Table 9.49. jsonpath Filter Expression Elements">Table 9.49</a>. The path

  619.    evaluation result to be filtered is denoted by the <code class="literal">@</code>

  620.    variable. To refer to a JSON element stored at a lower nesting level,

  621.    add one or more accessor operators after <code class="literal">@</code>.

  622.   </p><p>

  623.    Suppose you would like to retrieve all heart rate values higher

  624.    than 130. You can achieve this using the following expression:

  625. </p><pre class="programlisting">

  626. '$.track.segments[*].HR ? (@ &gt; 130)'

  627. </pre><p>

  628.   </p><p>

  629.    To get the start time of segments with such values instead, you have to

  630.    filter out irrelevant segments before returning the start time, so the

  631.    filter expression is applied to the previous step, and the path used

  632.    in the condition is different:

  633. </p><pre class="programlisting">

  634. '$.track.segments[*] ? (@.HR &gt; 130)."start time"'

  635. </pre><p>

  636.   </p><p>

  637.    You can use several filter expressions on the same nesting level, if

  638.    required. For example, the following expression selects all segments

  639.    that contain locations with relevant coordinates and high heart rate values:

  640. </p><pre class="programlisting">

  641. '$.track.segments[*] ? (@.location[1] &lt; 13.4) ? (@.HR &gt; 130)."start time"'

  642. </pre><p>

  643.   </p><p>

  644.    Using filter expressions at different nesting levels is also allowed.

  645.    The following example first filters all segments by location, and then

  646.    returns high heart rate values for these segments, if available:

  647. </p><pre class="programlisting">

  648. '$.track.segments[*] ? (@.location[1] &lt; 13.4).HR ? (@ &gt; 130)'

  649. </pre><p>

  650.   </p><p>

  651.    You can also nest filter expressions within each other:

  652. </p><pre class="programlisting">

  653. '$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size()'

  654. </pre><p>

  655.    This expression returns the size of the track if it contains any

  656.    segments with high heart rate values, or an empty sequence otherwise.

  657.   </p><p>

  658.    <span class="productname">PostgreSQL</span>'s implementation of SQL/JSON path

  659.    language has the following deviations from the SQL/JSON standard:

  660.   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>

  661.      <code class="literal">.datetime()</code> item method is not implemented yet

  662.      mainly because immutable <code class="type">jsonpath</code> functions and operators

  663.      cannot reference session timezone, which is used in some datetime

  664.      operations.  Datetime support will be added to <code class="type">jsonpath</code>

  665.      in future versions of <span class="productname">PostgreSQL</span>.

  666.     </p></li><li class="listitem"><p>

  667.      A path expression can be a Boolean predicate, although the SQL/JSON

  668.      standard allows predicates only in filters.  This is necessary for

  669.      implementation of the <code class="literal">@@</code> operator. For example,

  670.      the following <code class="type">jsonpath</code> expression is valid in

  671.      <span class="productname">PostgreSQL</span>:

  672. </p><pre class="programlisting">

  673. '$.track.segments[*].HR &lt; 70'

  674. </pre><p>

  675.     </p></li><li class="listitem"><p>

  676.      There are minor differences in the interpretation of regular

  677.      expression patterns used in <code class="literal">like_regex</code> filters, as

  678.      described in <a class="xref" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS" title="9.15.2.2. Regular Expressions">Section 9.15.2.2</a>.

  679.     </p></li></ul></div><div class="sect3" id="STRICT-AND-LAX-MODES"><div class="titlepage"><div><div><h4 class="title">9.15.2.1. Strict and Lax Modes</h4></div></div></div><p>

  680.      When you query JSON data, the path expression may not match the

  681.      actual JSON data structure. An attempt to access a non-existent

  682.      member of an object or element of an array results in a

  683.      structural error. SQL/JSON path expressions have two modes

  684.      of handling structural errors:

  685.     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>

  686.       lax (default) — the path engine implicitly adapts

  687.       the queried data to the specified path.

  688.       Any remaining structural errors are suppressed and converted

  689.       to empty SQL/JSON sequences.

  690.      </p></li><li class="listitem"><p>

  691.       strict — if a structural error occurs, an error is raised.

  692.      </p></li></ul></div><p>

  693.     The lax mode facilitates matching of a JSON document structure and path

  694.     expression if the JSON data does not conform to the expected schema.

  695.     If an operand does not match the requirements of a particular operation,

  696.     it can be automatically wrapped as an SQL/JSON array or unwrapped by

  697.     converting its elements into an SQL/JSON sequence before performing

  698.     this operation. Besides, comparison operators automatically unwrap their

  699.     operands in the lax mode, so you can compare SQL/JSON arrays

  700.     out-of-the-box. An array of size 1 is considered equal to its sole element.

  701.     Automatic unwrapping is not performed only when:

  702.     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>

  703.        The path expression contains <code class="literal">type()</code> or

  704.        <code class="literal">size()</code> methods that return the type

  705.        and the number of elements in the array, respectively.

  706.       </p></li><li class="listitem"><p>

  707.        The queried JSON data contain nested arrays. In this case, only

  708.        the outermost array is unwrapped, while all the inner arrays

  709.        remain unchanged. Thus, implicit unwrapping can only go one

  710.        level down within each path evaluation step.

  711.       </p></li></ul></div><p>

  712.    </p><p>

  713.     For example, when querying the GPS data listed above, you can

  714.     abstract from the fact that it stores an array of segments

  715.     when using the lax mode:

  716. </p><pre class="programlisting">

  717. 'lax $.track.segments.location'

  718. </pre><p>

  719.    </p><p>

  720.     In the strict mode, the specified path must exactly match the structure of

  721.     the queried JSON document to return an SQL/JSON item, so using this

  722.     path expression will cause an error. To get the same result as in

  723.     the lax mode, you have to explicitly unwrap the

  724.     <code class="literal">segments</code> array:

  725. </p><pre class="programlisting">

  726. 'strict $.track.segments[*].location'

  727. </pre><p>

  728.    </p></div><div class="sect3" id="JSONPATH-REGULAR-EXPRESSIONS"><div class="titlepage"><div><div><h4 class="title">9.15.2.2. Regular Expressions</h4></div></div></div><a id="id-1.5.8.20.6.23.2" class="indexterm"></a><p>

  729.      SQL/JSON path expressions allow matching text to a regular expression

  730.      with the <code class="literal">like_regex</code> filter.  For example, the

  731.      following SQL/JSON path query would case-insensitively match all

  732.      strings in an array that start with an English vowel:

  733. </p><pre class="programlisting">

  734. '$[*] ? (@ like_regex "^[aeiou]" flag "i")'

  735. </pre><p>

  736.     </p><p>

  737.      The optional <code class="literal">flag</code> string may include one or more of

  738.      the characters

  739.      <code class="literal">i</code> for case-insensitive match,

  740.      <code class="literal">m</code> to allow <code class="literal">^</code>

  741.      and <code class="literal">$</code> to match at newlines,

  742.      <code class="literal">s</code> to allow <code class="literal">.</code> to match a newline,

  743.      and <code class="literal">q</code> to quote the whole pattern (reducing the

  744.      behavior to a simple substring match).

  745.     </p><p>

  746.      The SQL/JSON standard borrows its definition for regular expressions

  747.      from the <code class="literal">LIKE_REGEX</code> operator, which in turn uses the

  748.      XQuery standard.  PostgreSQL does not currently support the

  749.      <code class="literal">LIKE_REGEX</code> operator.  Therefore,

  750.      the <code class="literal">like_regex</code> filter is implemented using the

  751.      POSIX regular expression engine described in

  752.      <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.  This leads to various minor

  753.      discrepancies from standard SQL/JSON behavior, which are cataloged in

  754.      <a class="xref" href="functions-matching.html#POSIX-VS-XQUERY" title="9.7.3.8. Differences From XQuery (LIKE_REGEX)">Section 9.7.3.8</a>.

  755.      Note, however, that the flag-letter incompatibilities described there

  756.      do not apply to SQL/JSON, as it translates the XQuery flag letters to

  757.      match what the POSIX engine expects.

  758.     </p><p>

  759.      Keep in mind that the pattern argument of <code class="literal">like_regex</code>

  760.      is a JSON path string literal, written according to the rules given in

  761.      <a class="xref" href="datatype-json.html#DATATYPE-JSONPATH" title="8.14.6. jsonpath Type">Section 8.14.6</a>.  This means in particular that any

  762.      backslashes you want to use in the regular expression must be doubled.

  763.      For example, to match strings that contain only digits:

  764. </p><pre class="programlisting">

  765. '$ ? (@ like_regex "^\\d+$")'

  766. </pre><p>

  767.     </p></div><div class="sect3" id="FUNCTIONS-SQLJSON-PATH-OPERATORS"><div class="titlepage"><div><div><h4 class="title">9.15.2.3. SQL/JSON Path Operators and Methods</h4></div></div></div><p>

  768.     <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-OP-TABLE" title="Table 9.48. jsonpath Operators and Methods">Table 9.48</a> shows the operators and

  769.     methods available in <code class="type">jsonpath</code>.  <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-FILTER-EX-TABLE" title="Table 9.49. jsonpath Filter Expression Elements">Table 9.49</a> shows the available filter

  770.     expression elements.

  771.    </p><div class="table" id="FUNCTIONS-SQLJSON-OP-TABLE"><p class="title"><strong>Table 9.48. <code class="type">jsonpath</code> Operators and Methods</strong></p><div class="table-contents"><table class="table" summary="jsonpath Operators and Methods" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Operator/Method</th><th>Description</th><th>Example JSON</th><th>Example Query</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">+</code> (unary)</td><td>Plus operator that iterates over the SQL/JSON sequence</td><td><code class="literal">{"x": [2.85, -14.7, -9.4]}</code></td><td><code class="literal">+ $.x.floor()</code></td><td><code class="literal">2, -15, -10</code></td></tr><tr><td><code class="literal">-</code> (unary)</td><td>Minus operator that iterates over the SQL/JSON sequence</td><td><code class="literal">{"x": [2.85, -14.7, -9.4]}</code></td><td><code class="literal">- $.x.floor()</code></td><td><code class="literal">-2, 15, 10</code></td></tr><tr><td><code class="literal">+</code> (binary)</td><td>Addition</td><td><code class="literal">[2]</code></td><td><code class="literal">2 + $[0]</code></td><td><code class="literal">4</code></td></tr><tr><td><code class="literal">-</code> (binary)</td><td>Subtraction</td><td><code class="literal">[2]</code></td><td><code class="literal">4 - $[0]</code></td><td><code class="literal">2</code></td></tr><tr><td><code class="literal">*</code></td><td>Multiplication</td><td><code class="literal">[4]</code></td><td><code class="literal">2 * $[0]</code></td><td><code class="literal">8</code></td></tr><tr><td><code class="literal">/</code></td><td>Division</td><td><code class="literal">[8]</code></td><td><code class="literal">$[0] / 2</code></td><td><code class="literal">4</code></td></tr><tr><td><code class="literal">%</code></td><td>Modulus</td><td><code class="literal">[32]</code></td><td><code class="literal">$[0] % 10</code></td><td><code class="literal">2</code></td></tr><tr><td><code class="literal">type()</code></td><td>Type of the SQL/JSON item</td><td><code class="literal">[1, "2", {}]</code></td><td><code class="literal">$[*].type()</code></td><td><code class="literal">"number", "string", "object"</code></td></tr><tr><td><code class="literal">size()</code></td><td>Size of the SQL/JSON item</td><td><code class="literal">{"m": [11, 15]}</code></td><td><code class="literal">$.m.size()</code></td><td><code class="literal">2</code></td></tr><tr><td><code class="literal">double()</code></td><td>Approximate floating-point number converted from an SQL/JSON number or a string</td><td><code class="literal">{"len": "1.9"}</code></td><td><code class="literal">$.len.double() * 2</code></td><td><code class="literal">3.8</code></td></tr><tr><td><code class="literal">ceiling()</code></td><td>Nearest integer greater than or equal to the SQL/JSON number</td><td><code class="literal">{"h": 1.3}</code></td><td><code class="literal">$.h.ceiling()</code></td><td><code class="literal">2</code></td></tr><tr><td><code class="literal">floor()</code></td><td>Nearest integer less than or equal to the SQL/JSON number</td><td><code class="literal">{"h": 1.3}</code></td><td><code class="literal">$.h.floor()</code></td><td><code class="literal">1</code></td></tr><tr><td><code class="literal">abs()</code></td><td>Absolute value of the SQL/JSON number</td><td><code class="literal">{"z": -0.3}</code></td><td><code class="literal">$.z.abs()</code></td><td><code class="literal">0.3</code></td></tr><tr><td><code class="literal">keyvalue()</code></td><td>

  772.           Sequence of object's key-value pairs represented as array of items

  773.           containing three fields (<code class="literal">"key"</code>,

  774.           <code class="literal">"value"</code>, and <code class="literal">"id"</code>).

  775.           <code class="literal">"id"</code> is a unique identifier of the object

  776.           key-value pair belongs to.

  777.         </td><td><code class="literal">{"x": "20", "y": 32}</code></td><td><code class="literal">$.keyvalue()</code></td><td><code class="literal">{"key": "x", "value": "20", "id": 0}, {"key": "y", "value": 32, "id": 0}</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-SQLJSON-FILTER-EX-TABLE"><p class="title"><strong>Table 9.49. <code class="type">jsonpath</code> Filter Expression Elements</strong></p><div class="table-contents"><table class="table" summary="jsonpath Filter Expression Elements" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Value/Predicate</th><th>Description</th><th>Example JSON</th><th>Example Query</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">==</code></td><td>Equality operator</td><td><code class="literal">[1, 2, 1, 3]</code></td><td><code class="literal">$[*] ? (@ == 1)</code></td><td><code class="literal">1, 1</code></td></tr><tr><td><code class="literal">!=</code></td><td>Non-equality operator</td><td><code class="literal">[1, 2, 1, 3]</code></td><td><code class="literal">$[*] ? (@ != 1)</code></td><td><code class="literal">2, 3</code></td></tr><tr><td><code class="literal">&lt;&gt;</code></td><td>Non-equality operator (same as <code class="literal">!=</code>)</td><td><code class="literal">[1, 2, 1, 3]</code></td><td><code class="literal">$[*] ? (@ &lt;&gt; 1)</code></td><td><code class="literal">2, 3</code></td></tr><tr><td><code class="literal">&lt;</code></td><td>Less-than operator</td><td><code class="literal">[1, 2, 3]</code></td><td><code class="literal">$[*] ? (@ &lt; 2)</code></td><td><code class="literal">1</code></td></tr><tr><td><code class="literal">&lt;=</code></td><td>Less-than-or-equal-to operator</td><td><code class="literal">[1, 2, 3]</code></td><td><code class="literal">$[*] ? (@ &lt;= 2)</code></td><td><code class="literal">1, 2</code></td></tr><tr><td><code class="literal">&gt;</code></td><td>Greater-than operator</td><td><code class="literal">[1, 2, 3]</code></td><td><code class="literal">$[*] ? (@ &gt; 2)</code></td><td><code class="literal">3</code></td></tr><tr><td><code class="literal">&gt;=</code></td><td>Greater-than-or-equal-to operator</td><td><code class="literal">[1, 2, 3]</code></td><td><code class="literal">$[*] ? (@ &gt;= 2)</code></td><td><code class="literal">2, 3</code></td></tr><tr><td><code class="literal">true</code></td><td>Value used to perform comparison with JSON <code class="literal">true</code> literal</td><td><code class="literal">[{"name": "John", "parent": false},

  778.                            {"name": "Chris", "parent": true}]</code></td><td><code class="literal">$[*] ? (@.parent == true)</code></td><td><code class="literal">{"name": "Chris", "parent": true}</code></td></tr><tr><td><code class="literal">false</code></td><td>Value used to perform comparison with JSON <code class="literal">false</code> literal</td><td><code class="literal">[{"name": "John", "parent": false},

  779.                            {"name": "Chris", "parent": true}]</code></td><td><code class="literal">$[*] ? (@.parent == false)</code></td><td><code class="literal">{"name": "John", "parent": false}</code></td></tr><tr><td><code class="literal">null</code></td><td>Value used to perform comparison with JSON <code class="literal">null</code> value</td><td><code class="literal">[{"name": "Mary", "job": null},

  780.                          {"name": "Michael", "job": "driver"}]</code></td><td><code class="literal">$[*] ? (@.job == null) .name</code></td><td><code class="literal">"Mary"</code></td></tr><tr><td><code class="literal">&amp;&amp;</code></td><td>Boolean AND</td><td><code class="literal">[1, 3, 7]</code></td><td><code class="literal">$[*] ? (@ &gt; 1 &amp;&amp; @ &lt; 5)</code></td><td><code class="literal">3</code></td></tr><tr><td><code class="literal">||</code></td><td>Boolean OR</td><td><code class="literal">[1, 3, 7]</code></td><td><code class="literal">$[*] ? (@ &lt; 1 || @ &gt; 5)</code></td><td><code class="literal">7</code></td></tr><tr><td><code class="literal">!</code></td><td>Boolean NOT</td><td><code class="literal">[1, 3, 7]</code></td><td><code class="literal">$[*] ? (!(@ &lt; 5))</code></td><td><code class="literal">7</code></td></tr><tr><td><code class="literal">like_regex</code></td><td>

  781.           Tests whether the first operand matches the regular expression

  782.           given by the second operand, optionally with modifications

  783.           described by a string of <code class="literal">flag</code> characters (see

  784.           <a class="xref" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS" title="9.15.2.2. Regular Expressions">Section 9.15.2.2</a>)

  785.         </td><td><code class="literal">["abc", "abd", "aBdC", "abdacb", "babc"]</code></td><td><code class="literal">$[*] ? (@ like_regex "^ab.*c" flag "i")</code></td><td><code class="literal">"abc", "aBdC", "abdacb"</code></td></tr><tr><td><code class="literal">starts with</code></td><td>Tests whether the second operand is an initial substring of the first operand</td><td><code class="literal">["John Smith", "Mary Stone", "Bob Johnson"]</code></td><td><code class="literal">$[*] ? (@ starts with "John")</code></td><td><code class="literal">"John Smith"</code></td></tr><tr><td><code class="literal">exists</code></td><td>Tests whether a path expression matches at least one SQL/JSON item</td><td><code class="literal">{"x": [1, 2], "y": [2, 4]}</code></td><td><code class="literal">strict $.* ? (exists (@ ? (@[*] &gt; 2)))</code></td><td><code class="literal">2, 4</code></td></tr><tr><td><code class="literal">is unknown</code></td><td>Tests whether a Boolean condition is <code class="literal">unknown</code></td><td><code class="literal">[-1, 2, 7, "infinity"]</code></td><td><code class="literal">$[*] ? ((@ &gt; 0) is unknown)</code></td><td><code class="literal">"infinity"</code></td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-xml.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-sequence.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.14. XML Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 9.16. Sequence Manipulation Functions</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1