postgresql/doc/src/sgml/json.sgml

<!-- doc/src/sgml/json.sgml -->

<sect1 id="datatype-json">
 <title><acronym>JSON</> Types</title>

 <indexterm zone="datatype-json">
  <primary>JSON</primary>
 </indexterm>

 <indexterm zone="datatype-json">
  <primary>JSONB</primary>
 </indexterm>

 <para>
  JSON data types are for storing JSON (JavaScript Object Notation)
  data, as specified in <ulink url="http://rfc7159.net/rfc7159">RFC
  7159</ulink>. Such data can also be stored as <type>text</type>, but
  the JSON data types have the advantage of enforcing that each
  stored value is valid according to the JSON rules.  There are also
  assorted JSON-specific functions available for data stored in these
  data types; see <xref linkend="functions-json">.
 </para>

 <para>
  There are two JSON data types: <type>json</> and <type>jsonb</>.
  They accept <emphasis>almost</> identical sets of values as
  input.  The major practical difference is one of efficiency.  The
  <type>json</> data type stores an exact copy of the input text,
  which processing functions must reparse on each execution; while
  <type>jsonb</> data is stored in a decomposed binary format that
  makes it slightly slower to input due to added conversion
  overhead, but significantly faster to process, since it never needs
  reparsing.  <type>jsonb</> also supports indexing, which can be a
  significant advantage.
 </para>

 <para>
  Because the <type>json</> type stores an exact copy of the input text, it
  will preserve semantically-insignificant white space between tokens, as
  well as the order of keys within JSON objects. Also, if a JSON object
  within the value contains the same key more than once, all the key/value
  pairs are kept.  (The processing functions consider the last value as the
  operative one.)  By contrast, <type>jsonb</> does not preserve white
  space, does not preserve the order of object keys, and does not keep
  duplicate object keys.  Only the last value for a key specified in the
  input is kept.  <type>jsonb</> will preserve trailing zeros within a JSON
  number, even though those are semantically insignificant for purposes such
  as equality checks.
 </para>

 <para>
  In general, most applications should prefer to store JSON data as
  <type>jsonb</>, unless there are quite specialized needs, such as
  legacy assumptions about ordering of object keys.
 </para>

 <para>
  <productname>PostgreSQL</productname> allows only one character set
  encoding per database.  It is therefore not possible for the JSON
  types to conform rigidly to the JSON specification unless the database
  encoding is UTF-8. Attempts to directly include characters which
  cannot be represented in the database encoding will fail; conversely,
  characters which can be represented in the database encoding but not
  in UTF-8 will be allowed.  <literal>\uXXXX</literal> escapes are
  allowed regardless of the database encoding, and are checked only for
  syntactic correctness.
 </para>

 <sect2 id="json-types">
  <title>Mapping of RFC-7159/JSON Primitive Types to <productname>PostgreSQL</productname> Types</title>
  <table id="json-type-mapping-table">
     <title>JSON scalar types and corresponding <productname>PostgreSQL</productname> types</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>RFC-7159/JSON primitive type</entry>
        <entry><productname>PostgreSQL</productname> type</entry>
        <entry>Notes</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><type>string</></entry>
        <entry><type>text</></entry>
        <entry>See introductory notes on JSON and encoding</entry>
       </row>
       <row>
        <entry><type>number</></entry>
        <entry><type>numeric</></entry>
        <entry><literal>NaN</literal> and <literal>infinity</literal> values are disallowed</entry>
       </row>
       <row>
        <entry><type>boolean</></entry>
        <entry><type>boolean</></entry>
        <entry>Only lowercase <literal>true</literal> and <literal>false</literal> spellings are accepted</entry>
       </row>
       <row>
        <entry><type>null</></entry>
        <entry>(none)</entry>
        <entry>SQL <literal>NULL</literal> is a different concept</entry>
       </row>
      </tbody>
     </tgroup>
   </table>
  <para>
    When converting textual JSON input into <type>jsonb</>,
    the primitive types described by <acronym>RFC</> 7159 are effectively
    mapped onto native
    <productname>PostgreSQL</productname> types, as shown in
    <xref linkend="json-type-mapping-table">.  Therefore, there are
    some very minor additional constraints on what constitutes valid
    <type>jsonb</type> that do not apply to the <type>json</type>
    type, nor to JSON in the abstract, corresponding to limits on what
    can be represented by the underlying data type.  Specifically,
    <type>jsonb</> will reject numbers that are outside the range of
    the <productname>PostgreSQL</productname> <type>numeric</> data type,
    while <type>json</> will not.  Such
    implementation-defined restrictions are permitted by
    <acronym>RFC</> 7159.  However, in practice such problems are far more
    likely to occur in other implementations, as it is common to
    represent the <type>number</> JSON primitive type as IEEE 754
    double precision floating point (which <acronym>RFC</> 7159
    explicitly anticipates and allows for).  When using JSON as an
    interchange format with such systems, the danger of losing numeric
    precision compared to data originally stored by
    <productname>PostgreSQL</productname> should be considered.
  </para>

  <para>
    Conversely, as noted in the table there are some minor restrictions on
    the input format of JSON primitive types that do not apply to
    the corresponding <productname>PostgreSQL</productname> types.
  </para>
 </sect2>

 <sect2 id="json-keys-elements">
  <title><type>jsonb</> Input and Output Syntax</title>
  <para>
   The input/output syntax for the JSON data types is as specified in
   <acronym>RFC</> 7159.
  </para>
  <para>
   The following are all valid <type>json</> (or <type>jsonb</>) expressions:
  <programlisting>
-- Simple scalar/primitive value (explicitly required by RFC-7159)
SELECT '5'::json;

-- Array of heterogeneous, primitive-typed elements
SELECT '[1, 2, "foo", null]'::json;

-- Object of heterogeneous key/value pairs of primitive types
-- Note that key values are always strings
SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::json;
  </programlisting>
  </para>
  <para>
   Note the distinction between scalar/primitive values as array elements,
   keys and values.
  </para>
 </sect2>

 <sect2 id="json-querying">
  <title>Querying <type>jsonb</type> documents effectively</title>
  <para>
   Representing data as JSON can be considerably more flexible than
   the traditional relational data model, which is compelling in
   environments where requirements are fluid.  It is quite possible
   for both approaches to co-exist and complement each other within
   the same application.  However, even for applications where maximal
   flexibility is desired, it is still recommended that JSON documents
   have a somewhat fixed structure.  This structure is typically
   unenforced (though enforcing some business rules declaratively is
   possible), but makes it easier to write queries that usefully
   summarize a set of <quote>documents</> (datums) in a table.
  </para>
  <para>
   <type>json</> data is subject to the same concurrency control
   considerations as any other datatype when stored in a table.
   Although storing large documents is practicable, in order to ensure
   correct behavior row-level locks are, quite naturally, acquired as
   rows are updated.  Consider keeping <type>json</> documents at a
   manageable size in order to decrease lock contention among updating
   transactions.  Ideally, <type>json</> documents should each
   represent an atomic datum that business rules dictate cannot
   reasonably be further subdivided into smaller atomic datums that
   can be independently modified.
  </para>
 </sect2>

 <sect2 id="json-containment">
  <title><type>jsonb</> containment</title>
  <indexterm>
    <primary>jsonb</primary>
    <secondary>containment</secondary>
  </indexterm>
  <para>
    Testing <quote>containment</> is an important capability of
    <type>jsonb</>.  There is no parallel set of facilities for the
    <type>json</> type.  Containment is the ability to determine if
    one <type>jsonb</> document has contained within it another one.
    <type>jsonb</> is nested, and so containment semantics are nested;
    technically, top-down, unordered <emphasis>subtree isomorphism</>
    may be tested.  Containment is conventionally tested using the
    <literal>@&gt;</> operator, which is made indexable by various
    operator classes discussed below.
  </para>
  <programlisting>
-- Simple scalar/primitive values may contain only each other:
SELECT '"foo"'::jsonb @> '"foo"'::jsonb;

-- The array on the right hand side is contained within the one on the
-- left hand side:
SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb;

-- The object with a single pair on the right hand side is contained
-- within the object on the left hand side:
SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb":true}'::jsonb @> '{"version":9.4}'::jsonb;

-- The array on the right hand side is not contained within the array
-- containing a nested array on the left hand side:
SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb;

-- But with a layer of nesting, it is:
SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb;
  </programlisting>
  <para>
    It is both a sufficient and a necessary condition for nesting
    levels to <quote>line up</> for one <type>jsonb</> to contain
    within it another.  Under this definition, objects and arrays
    cannot <quote>line up</>, not least because objects contain
    key/value pairs, while arrays contain elements.
  </para>
  <para>
    As a special exception to the general principle that nesting
    levels should <quote>line up</>, an array may contain a raw scalar:
  </para>
  <programlisting>
-- This array contains the raw scalar value:
SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb;
-- The special exception is not reciprocated -- non-containment is indicated here:
SELECT '"bar"'::jsonb @> '["bar"]'::jsonb;
  </programlisting>
  <para>
    Objects are better suited for testing containment when there is a
    great deal of nesting involved, because unlike arrays they are
    internally optimized for searching, and do not need to be searched
    linearly within a single <type>jsonb</> document.
  </para>
  <programlisting>
-- The right-hand side object is contained in this example:
SELECT '{"p":1, "a":{"b":3, "q":11}, "i":77}'::jsonb @> '{"a":{"b":3}}'::jsonb;
  </programlisting>
  <para>
    The various containment operators, along with all other JSON
    operators and support functions are documented in <xref
    linkend="functions-json">.
  </para>
 </sect2>

 <sect2 id="json-indexing">
  <title><type>jsonb</> Indexing</title>
  <indexterm>
    <primary>jsonb</primary>
    <secondary>indexes on</secondary>
  </indexterm>

  <para>
    <type>jsonb</> GIN indexes can be used to efficiently search for
    keys or key/value pairs occurring within a large number of
    <type>jsonb</> documents (datums).
    Two GIN <quote>operator classes</> are provided, offering different
    performance and flexibility tradeoffs.
  </para>
  <para>
    The default GIN operator class supports queries with the
    <literal>@&gt;</>, <literal>?</>, <literal>?&amp;</> and <literal>?|</>
    operators.
    (For details of the semantics that these operators
    implement, see <xref linkend="functions-jsonb-op-table">.)
    An example of creating an index with this operator class is:
  <programlisting>
CREATE INDEX idxgin ON api USING gin (jdoc);
  </programlisting>
    The non-default GIN operator class <literal>jsonb_hash_ops</>
    supports indexing the <literal>@&gt;</> operator only.
    An example of creating an index with this operator class is:
  <programlisting>
CREATE INDEX idxginh ON api USING gin (jdoc jsonb_hash_ops);
  </programlisting>
  </para>

  <para>
    Consider the example of a table that stores JSON documents
    retrieved from a third-party web service, with a documented schema
    definition.  A typical document is:
    <programlisting>
{
    "guid": "9c36adc1-7fb5-4d5b-83b4-90356a46061a",
    "name": "Angela Barton",
    "is_active": true,
    "company": "Magnafone",
    "address": "178 Howard Place, Gulf, Washington, 702",
    "registered": "2009-11-07T08:53:22 +08:00",
    "latitude": 19.793713,
    "longitude": 86.513373,
    "tags": [
        "enim",
        "aliquip",
        "qui"
    ]
}
    </programlisting>
    We store these documents in a table named <structname>api</>,
    in a <type>jsonb</> column named <structfield>jdoc</>.
    If a GIN index is created on this column,
    queries like the following can make use of the index:
    <programlisting>
-- Note that both key and value have been specified
SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"company": "Magnafone"}';
    </programlisting>
    However, the index could not be used for queries like the
    following, because though the operator <literal>?</> is indexable,
    it is not applied directly to the indexed column <structfield>jdoc</>:
    <programlisting>
SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc -&gt; 'tags' ? 'qui';
    </programlisting>
    Still, with judicious use of expression indexes, the above
    query can use an index scan.  If there is a requirement to find
    those records with a particular tag quickly, and the tags have a
    high cardinality across all documents, defining an index as
    follows is an effective approach to indexing:
  <programlisting>
-- Note that the "jsonb -&gt; text" operator can only be called on an
-- object, so as a consequence of creating this index the root of each
-- "jdoc" value must be an object.  This is enforced during insertion.
CREATE INDEX idxgintags ON api USING gin ((jdoc -&gt; 'tags'));
  </programlisting>
    Now, the <literal>WHERE</> clause <literal>jdoc -&gt; 'tags' ? 'qui'</>
    will be recognized as an application of the indexable
    operator <literal>?</> to the indexed
    expression <literal>jdoc -&gt; 'tags'</>.
    (More information on expression indexes can be found in <xref
    linkend="indexes-expressional">.)
  </para>
  <para>
    Another approach to querying is to exploit containment, for example:
  <programlisting>
SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"tags": ["qui"]}';
  </programlisting>
    This approach uses a single GIN index covering everything in the
    <literal>jdoc</> column, whereas our expression index stored only
    data found under the <literal>tags</> key.  While the single-index
    approach is certainly more flexible, targeted expression indexes
    are likely to be smaller and faster to search than a single index.
  </para>

  <para>
    Although the <literal>jsonb_hash_ops</literal> operator class supports
    only queries with the <literal>@&gt;</> operator, it has notable
    performance advantages over the default operator
    class <literal>jsonb_ops</literal>.  A <literal>jsonb_hash_ops</literal>
    GIN index is usually much smaller than a <literal>jsonb_ops</literal>
    index over the same data, and the specificity of searches is better,
    particularly when queries contain tags that appear frequently in the
    data.  Therefore search operations typically perform considerably better
    than with the default operator class.
  </para>

  <para>
    <type>jsonb</> also supports <literal>btree</> and <literal>hash</>
    indexes.  These are usually useful only if it's important to check
    equality of complete JSON documents.
    The <literal>btree</> ordering for <type>jsonb</> datums is:
    <synopsis>
      <replaceable>Object</replaceable> > <replaceable>Array</replaceable> > <replaceable>Boolean</replaceable> > <replaceable>Number</replaceable> > <replaceable>String</replaceable> > <replaceable>Null</replaceable>

      <replaceable>Object with n pairs</replaceable> > <replaceable>object with n - 1 pairs</replaceable>

      <replaceable>Array with n elements</replaceable> > <replaceable>array with n - 1 elements</replaceable>
    </synopsis>
      Objects with equal numbers of pairs are compared in the order:
    <synopsis>
      <replaceable>key-1</replaceable>, <replaceable>value-1</replaceable>, <replaceable>key-2</replaceable> ...
    </synopsis>
      Note however that object keys are compared in their storage order, and
      in particular, since shorter keys are stored before longer keys, this
      can lead to results that might be unintuitive, such as:
<programlisting>
{ "aa": 1, "c": 1} > {"b": 1, "d": 1}
</programlisting>
      Similarly, arrays with equal numbers of elements are compared:
    <synopsis>
      <replaceable>element-1</replaceable>, <replaceable>element-2</replaceable> ...
    </synopsis>
      Primitive JSON values are compared using the same
      comparison rules as for the underlying
      <productname>PostgreSQL</productname> data type.  Strings are
      compared using the default database collation.
  </para>
 </sect2>
</sect1>