Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<!-- doc/src/sgml/json.sgml -->
|
|
|
|
|
|
|
|
<sect1 id="datatype-json">
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><acronym>JSON</acronym> Types</title>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
|
|
|
<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)
|
2017-08-17 17:39:00 +02:00
|
|
|
data, as specified in <ulink url="https://tools.ietf.org/html/rfc7159">RFC
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
7159</ulink>. Such data can also be stored as <type>text</type>, but
|
2014-05-09 22:33:25 +02:00
|
|
|
the JSON data types have the advantage of enforcing that each
|
|
|
|
stored value is valid according to the JSON rules. There are also
|
2014-05-11 00:56:52 +02:00
|
|
|
assorted JSON-specific functions and operators available for data stored
|
2017-11-23 15:39:47 +01:00
|
|
|
in these data types; see <xref linkend="functions-json"/>.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
There are two JSON data types: <type>json</type> and <type>jsonb</type>.
|
|
|
|
They accept <emphasis>almost</emphasis> identical sets of values as
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
input. The major practical difference is one of efficiency. The
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>json</type> data type stores an exact copy of the input text,
|
2014-05-09 22:33:25 +02:00
|
|
|
which processing functions must reparse on each execution; while
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>jsonb</type> data is stored in a decomposed binary format that
|
2014-05-09 22:33:25 +02:00
|
|
|
makes it slightly slower to input due to added conversion
|
2014-05-11 00:56:52 +02:00
|
|
|
overhead, but significantly faster to process, since no reparsing
|
2017-10-09 03:44:17 +02:00
|
|
|
is needed. <type>jsonb</type> also supports indexing, which can be a
|
2014-05-09 22:33:25 +02:00
|
|
|
significant advantage.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Because the <type>json</type> type stores an exact copy of the input text, it
|
2014-05-09 22:33:25 +02:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
operative one.) By contrast, <type>jsonb</type> does not preserve white
|
2014-05-09 22:33:25 +02:00
|
|
|
space, does not preserve the order of object keys, and does not keep
|
2014-05-11 00:56:52 +02:00
|
|
|
duplicate object keys. If duplicate keys are specified in the input,
|
|
|
|
only the last value is kept.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-05-09 22:33:25 +02:00
|
|
|
In general, most applications should prefer to store JSON data as
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>jsonb</type>, unless there are quite specialized needs, such as
|
2014-05-09 22:33:25 +02:00
|
|
|
legacy assumptions about ordering of object keys.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-05-09 22:33:25 +02:00
|
|
|
<productname>PostgreSQL</productname> allows only one character set
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
encoding per database. It is therefore not possible for the JSON
|
2014-05-09 22:33:25 +02:00
|
|
|
types to conform rigidly to the JSON specification unless the database
|
2014-05-11 00:56:52 +02:00
|
|
|
encoding is UTF8. Attempts to directly include characters that
|
2014-05-09 22:33:25 +02:00
|
|
|
cannot be represented in the database encoding will fail; conversely,
|
2014-05-11 00:56:52 +02:00
|
|
|
characters that can be represented in the database encoding but not
|
|
|
|
in UTF8 will be allowed.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
RFC 7159 permits JSON strings to contain Unicode escape sequences
|
2017-10-09 03:44:17 +02:00
|
|
|
denoted by <literal>\u<replaceable>XXXX</replaceable></literal>. In the input
|
|
|
|
function for the <type>json</type> type, Unicode escapes are allowed
|
2014-05-11 00:56:52 +02:00
|
|
|
regardless of the database encoding, and are checked only for syntactic
|
2017-10-09 03:44:17 +02:00
|
|
|
correctness (that is, that four hex digits follow <literal>\u</literal>).
|
|
|
|
However, the input function for <type>jsonb</type> is stricter: it disallows
|
|
|
|
Unicode escapes for non-ASCII characters (those above <literal>U+007F</literal>)
|
|
|
|
unless the database encoding is UTF8. The <type>jsonb</type> type also
|
|
|
|
rejects <literal>\u0000</literal> (because that cannot be represented in
|
|
|
|
<productname>PostgreSQL</productname>'s <type>text</type> type), and it insists
|
Fix jsonb Unicode escape processing, and in consequence disallow \u0000.
We've been trying to support \u0000 in JSON values since commit
78ed8e03c67d7333, and have introduced increasingly worse hacks to try to
make it work, such as commit 0ad1a816320a2b53. However, it fundamentally
can't work in the way envisioned, because the stored representation looks
the same as for \\u0000 which is not the same thing at all. It's also
entirely bogus to output \u0000 when de-escaped output is called for.
The right way to do this would be to store an actual 0x00 byte, and then
throw error only if asked to produce de-escaped textual output. However,
getting to that point seems likely to take considerable work and may well
never be practical in the 9.4.x series.
To preserve our options for better behavior while getting rid of the nasty
side-effects of 0ad1a816320a2b53, revert that commit in toto and instead
throw error if \u0000 is used in a context where it needs to be de-escaped.
(These are the same contexts where non-ASCII Unicode escapes throw error
if the database encoding isn't UTF8, so this behavior is by no means
without precedent.)
In passing, make both the \u0000 case and the non-ASCII Unicode case report
ERRCODE_UNTRANSLATABLE_CHARACTER / "unsupported Unicode escape sequence"
rather than claiming there's something wrong with the input syntax.
Back-patch to 9.4, where we have to do something because 0ad1a816320a2b53
broke things for many cases having nothing to do with \u0000. 9.3 also has
bogus behavior, but only for that specific escape value, so given the lack
of field complaints it seems better to leave 9.3 alone.
2015-01-30 20:44:46 +01:00
|
|
|
that any use of Unicode surrogate pairs to designate characters outside
|
|
|
|
the Unicode Basic Multilingual Plane be correct. Valid Unicode escapes
|
|
|
|
are converted to the equivalent ASCII or UTF8 character for storage;
|
|
|
|
this includes folding surrogate pairs into a single character.
|
2014-05-11 00:56:52 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Many of the JSON processing functions described
|
2017-11-23 15:39:47 +01:00
|
|
|
in <xref linkend="functions-json"/> will convert Unicode escapes to
|
2014-05-11 00:56:52 +02:00
|
|
|
regular characters, and will therefore throw the same types of errors
|
2017-10-09 03:44:17 +02:00
|
|
|
just described even if their input is of type <type>json</type>
|
|
|
|
not <type>jsonb</type>. The fact that the <type>json</type> input function does
|
2014-05-11 00:56:52 +02:00
|
|
|
not make these checks may be considered a historical artifact, although
|
|
|
|
it does allow for simple storage (without processing) of JSON Unicode
|
|
|
|
escapes in a non-UTF8 database encoding. In general, it is best to
|
|
|
|
avoid mixing Unicode escapes in JSON with a non-UTF8 database encoding,
|
|
|
|
if possible.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
When converting textual JSON input into <type>jsonb</type>, the primitive
|
|
|
|
types described by <acronym>RFC</acronym> 7159 are effectively mapped onto
|
2014-05-11 00:56:52 +02:00
|
|
|
native <productname>PostgreSQL</productname> types, as shown
|
2017-11-23 15:39:47 +01:00
|
|
|
in <xref linkend="json-type-mapping-table"/>.
|
2014-05-11 00:56:52 +02:00
|
|
|
Therefore, there are some minor additional constraints on what
|
|
|
|
constitutes valid <type>jsonb</type> data 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.
|
2017-10-09 03:44:17 +02:00
|
|
|
Notably, <type>jsonb</type> will reject numbers that are outside the
|
|
|
|
range of the <productname>PostgreSQL</productname> <type>numeric</type> data
|
|
|
|
type, while <type>json</type> will not. Such implementation-defined
|
|
|
|
restrictions are permitted by <acronym>RFC</acronym> 7159. However, in
|
2014-05-11 00:56:52 +02:00
|
|
|
practice such problems are far more likely to occur in other
|
2017-10-09 03:44:17 +02:00
|
|
|
implementations, as it is common to represent JSON's <type>number</type>
|
2014-05-11 00:56:52 +02:00
|
|
|
primitive type as IEEE 754 double precision floating point
|
2017-10-09 03:44:17 +02:00
|
|
|
(which <acronym>RFC</acronym> 7159 explicitly anticipates and allows for).
|
2014-05-11 00:56:52 +02:00
|
|
|
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.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<table id="json-type-mapping-table">
|
2014-05-11 00:56:52 +02:00
|
|
|
<title>JSON primitive types and corresponding <productname>PostgreSQL</productname> types</title>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<tgroup cols="3">
|
|
|
|
<thead>
|
|
|
|
<row>
|
2014-05-11 00:56:52 +02:00
|
|
|
<entry>JSON primitive type</entry>
|
2014-05-09 22:33:25 +02:00
|
|
|
<entry><productname>PostgreSQL</productname> type</entry>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<entry>Notes</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
2017-10-09 03:44:17 +02:00
|
|
|
<entry><type>string</type></entry>
|
|
|
|
<entry><type>text</type></entry>
|
|
|
|
<entry><literal>\u0000</literal> is disallowed, as are non-ASCII Unicode
|
Fix jsonb Unicode escape processing, and in consequence disallow \u0000.
We've been trying to support \u0000 in JSON values since commit
78ed8e03c67d7333, and have introduced increasingly worse hacks to try to
make it work, such as commit 0ad1a816320a2b53. However, it fundamentally
can't work in the way envisioned, because the stored representation looks
the same as for \\u0000 which is not the same thing at all. It's also
entirely bogus to output \u0000 when de-escaped output is called for.
The right way to do this would be to store an actual 0x00 byte, and then
throw error only if asked to produce de-escaped textual output. However,
getting to that point seems likely to take considerable work and may well
never be practical in the 9.4.x series.
To preserve our options for better behavior while getting rid of the nasty
side-effects of 0ad1a816320a2b53, revert that commit in toto and instead
throw error if \u0000 is used in a context where it needs to be de-escaped.
(These are the same contexts where non-ASCII Unicode escapes throw error
if the database encoding isn't UTF8, so this behavior is by no means
without precedent.)
In passing, make both the \u0000 case and the non-ASCII Unicode case report
ERRCODE_UNTRANSLATABLE_CHARACTER / "unsupported Unicode escape sequence"
rather than claiming there's something wrong with the input syntax.
Back-patch to 9.4, where we have to do something because 0ad1a816320a2b53
broke things for many cases having nothing to do with \u0000. 9.3 also has
bogus behavior, but only for that specific escape value, so given the lack
of field complaints it seems better to leave 9.3 alone.
2015-01-30 20:44:46 +01:00
|
|
|
escapes if database encoding is not UTF8</entry>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</row>
|
|
|
|
<row>
|
2017-10-09 03:44:17 +02:00
|
|
|
<entry><type>number</type></entry>
|
|
|
|
<entry><type>numeric</type></entry>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<entry><literal>NaN</literal> and <literal>infinity</literal> values are disallowed</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
2017-10-09 03:44:17 +02:00
|
|
|
<entry><type>boolean</type></entry>
|
|
|
|
<entry><type>boolean</type></entry>
|
2014-05-09 22:33:25 +02:00
|
|
|
<entry>Only lowercase <literal>true</literal> and <literal>false</literal> spellings are accepted</entry>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</row>
|
|
|
|
<row>
|
2017-10-09 03:44:17 +02:00
|
|
|
<entry><type>null</type></entry>
|
2014-05-09 22:33:25 +02:00
|
|
|
<entry>(none)</entry>
|
|
|
|
<entry>SQL <literal>NULL</literal> is a different concept</entry>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
|
|
|
<sect2 id="json-keys-elements">
|
2014-05-11 18:06:04 +02:00
|
|
|
<title>JSON Input and Output Syntax</title>
|
2014-05-09 22:33:25 +02:00
|
|
|
<para>
|
|
|
|
The input/output syntax for the JSON data types is as specified in
|
2017-10-09 03:44:17 +02:00
|
|
|
<acronym>RFC</acronym> 7159.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-09 22:33:25 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The following are all valid <type>json</type> (or <type>jsonb</type>) expressions:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Simple scalar/primitive value
|
|
|
|
-- Primitive values can be numbers, quoted strings, true, false, or null
|
2014-05-09 22:33:25 +02:00
|
|
|
SELECT '5'::json;
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Array of zero or more elements (elements need not be of same type)
|
2014-05-09 22:33:25 +02:00
|
|
|
SELECT '[1, 2, "foo", null]'::json;
|
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Object containing pairs of keys and values
|
|
|
|
-- Note that object keys must always be quoted strings
|
|
|
|
SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json;
|
|
|
|
|
|
|
|
-- Arrays and objects can be nested arbitrarily
|
|
|
|
SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json;
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2014-05-09 22:33:25 +02:00
|
|
|
</para>
|
2014-05-11 00:56:52 +02:00
|
|
|
|
2014-05-09 22:33:25 +02:00
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
As previously stated, when a JSON value is input and then printed without
|
2017-10-09 03:44:17 +02:00
|
|
|
any additional processing, <type>json</type> outputs the same text that was
|
|
|
|
input, while <type>jsonb</type> does not preserve semantically-insignificant
|
2014-05-11 00:56:52 +02:00
|
|
|
details such as whitespace. For example, note the differences here:
|
|
|
|
<programlisting>
|
|
|
|
SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::json;
|
|
|
|
json
|
|
|
|
-------------------------------------------------
|
|
|
|
{"bar": "baz", "balance": 7.77, "active":false}
|
|
|
|
(1 row)
|
|
|
|
|
|
|
|
SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::jsonb;
|
|
|
|
jsonb
|
|
|
|
--------------------------------------------------
|
|
|
|
{"bar": "baz", "active": false, "balance": 7.77}
|
|
|
|
(1 row)
|
|
|
|
</programlisting>
|
|
|
|
One semantically-insignificant detail worth noting is that
|
2017-10-09 03:44:17 +02:00
|
|
|
in <type>jsonb</type>, numbers will be printed according to the behavior of the
|
|
|
|
underlying <type>numeric</type> type. In practice this means that numbers
|
|
|
|
entered with <literal>E</literal> notation will be printed without it, for
|
2014-05-11 00:56:52 +02:00
|
|
|
example:
|
|
|
|
<programlisting>
|
|
|
|
SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb;
|
|
|
|
json | jsonb
|
|
|
|
-----------------------+-------------------------
|
|
|
|
{"reading": 1.230e-5} | {"reading": 0.00001230}
|
|
|
|
(1 row)
|
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
However, <type>jsonb</type> will preserve trailing fractional zeroes, as seen
|
2014-05-11 00:56:52 +02:00
|
|
|
in this example, even though those are semantically insignificant for
|
|
|
|
purposes such as equality checks.
|
2014-05-09 22:33:25 +02:00
|
|
|
</para>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</sect2>
|
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
<sect2 id="json-doc-design">
|
|
|
|
<title>Designing JSON documents effectively</title>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<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
|
2014-05-11 00:56:52 +02:00
|
|
|
have a somewhat fixed structure. The structure is typically
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
unenforced (though enforcing some business rules declaratively is
|
2014-05-11 00:56:52 +02:00
|
|
|
possible), but having a predictable structure makes it easier to write
|
2017-10-09 03:44:17 +02:00
|
|
|
queries that usefully summarize a set of <quote>documents</quote> (datums)
|
2014-05-11 00:56:52 +02:00
|
|
|
in a table.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
JSON data is subject to the same concurrency-control
|
|
|
|
considerations as any other data type when stored in a table.
|
|
|
|
Although storing large documents is practicable, keep in mind that
|
|
|
|
any update acquires a row-level lock on the whole row.
|
|
|
|
Consider limiting JSON documents to a
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
manageable size in order to decrease lock contention among updating
|
2014-05-11 00:56:52 +02:00
|
|
|
transactions. Ideally, JSON documents should each
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
represent an atomic datum that business rules dictate cannot
|
2014-05-11 00:56:52 +02:00
|
|
|
reasonably be further subdivided into smaller datums that
|
|
|
|
could be modified independently.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="json-containment">
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><type>jsonb</type> Containment and Existence</title>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<indexterm>
|
|
|
|
<primary>jsonb</primary>
|
|
|
|
<secondary>containment</secondary>
|
|
|
|
</indexterm>
|
2014-05-11 00:56:52 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>jsonb</primary>
|
|
|
|
<secondary>existence</secondary>
|
|
|
|
</indexterm>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Testing <firstterm>containment</firstterm> is an important capability of
|
|
|
|
<type>jsonb</type>. There is no parallel set of facilities for the
|
|
|
|
<type>json</type> type. Containment tests whether
|
|
|
|
one <type>jsonb</type> document has contained within it another one.
|
2014-05-11 00:56:52 +02:00
|
|
|
These examples return true except as noted:
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Simple scalar/primitive values contain only the identical value:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '"foo"'::jsonb @> '"foo"'::jsonb;
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
-- The array on the right side is contained within the one on the left:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb;
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-10-11 20:29:51 +02:00
|
|
|
-- Order of array elements is not significant, so this is also true:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb;
|
2014-10-11 20:29:51 +02:00
|
|
|
|
|
|
|
-- Duplicate array elements don't matter either:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb;
|
2014-10-11 20:29:51 +02:00
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
-- The object with a single pair on the right side is contained
|
|
|
|
-- within the object on the left side:
|
2015-10-07 16:30:54 +02:00
|
|
|
SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb;
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2017-10-09 03:44:17 +02:00
|
|
|
-- The array on the right side is <emphasis>not</emphasis> considered contained within the
|
2014-05-11 00:56:52 +02:00
|
|
|
-- array on the left, even though a similar array is nested within it:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- yields false
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-05-11 00:56:52 +02:00
|
|
|
-- But with a layer of nesting, it is contained:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb;
|
2014-05-11 00:56:52 +02:00
|
|
|
|
|
|
|
-- Similarly, containment is not reported here:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false
|
2015-10-07 16:30:54 +02:00
|
|
|
|
|
|
|
-- A top-level key and an empty object is contained:
|
|
|
|
SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb;
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
The general principle is that the contained object must match the
|
|
|
|
containing object as to structure and data contents, possibly after
|
|
|
|
discarding some non-matching array elements or object key/value pairs
|
2014-10-11 20:29:51 +02:00
|
|
|
from the containing object.
|
|
|
|
But remember that the order of array elements is not significant when
|
|
|
|
doing a containment match, and duplicate array elements are effectively
|
|
|
|
considered only once.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-11 00:56:52 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
As a special exception to the general principle that the structures
|
|
|
|
must match, an array may contain a primitive value:
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- This array contains the primitive string value:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb;
|
2014-05-11 00:56:52 +02:00
|
|
|
|
|
|
|
-- This exception is not reciprocal -- non-containment is reported here:
|
2015-10-07 15:42:26 +02:00
|
|
|
SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>jsonb</type> also has an <firstterm>existence</firstterm> operator, which is
|
2014-05-11 00:56:52 +02:00
|
|
|
a variation on the theme of containment: it tests whether a string
|
2017-10-09 03:44:17 +02:00
|
|
|
(given as a <type>text</type> value) appears as an object key or array
|
|
|
|
element at the top level of the <type>jsonb</type> value.
|
2014-05-11 00:56:52 +02:00
|
|
|
These examples return true except as noted:
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-11 00:56:52 +02:00
|
|
|
<programlisting>
|
|
|
|
-- String exists as array element:
|
|
|
|
SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar';
|
|
|
|
|
|
|
|
-- String exists as object key:
|
|
|
|
SELECT '{"foo": "bar"}'::jsonb ? 'foo';
|
|
|
|
|
|
|
|
-- Object values are not considered:
|
|
|
|
SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false
|
|
|
|
|
|
|
|
-- As with containment, existence must match at the top level:
|
|
|
|
SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false
|
|
|
|
|
|
|
|
-- A string is considered to exist if it matches a primitive JSON string:
|
|
|
|
SELECT '"foo"'::jsonb ? 'foo';
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
JSON objects are better suited than arrays for testing containment or
|
|
|
|
existence when there are many keys or elements involved, because
|
|
|
|
unlike arrays they are internally optimized for searching, and do not
|
|
|
|
need to be searched linearly.
|
|
|
|
</para>
|
|
|
|
|
2015-10-29 23:54:35 +01:00
|
|
|
<tip>
|
|
|
|
<para>
|
|
|
|
Because JSON containment is nested, an appropriate query can skip
|
|
|
|
explicit selection of sub-objects. As an example, suppose that we have
|
2017-10-09 03:44:17 +02:00
|
|
|
a <structfield>doc</structfield> column containing objects at the top level, with
|
|
|
|
most objects containing <literal>tags</literal> fields that contain arrays of
|
2015-10-29 23:54:35 +01:00
|
|
|
sub-objects. This query finds entries in which sub-objects containing
|
2017-10-09 03:44:17 +02:00
|
|
|
both <literal>"term":"paris"</literal> and <literal>"term":"food"</literal> appear,
|
|
|
|
while ignoring any such keys outside the <literal>tags</literal> array:
|
2015-10-29 23:54:35 +01:00
|
|
|
<programlisting>
|
|
|
|
SELECT doc->'site_name' FROM websites
|
|
|
|
WHERE doc @> '{"tags":[{"term":"paris"}, {"term":"food"}]}';
|
|
|
|
</programlisting>
|
|
|
|
One could accomplish the same thing with, say,
|
|
|
|
<programlisting>
|
|
|
|
SELECT doc->'site_name' FROM websites
|
|
|
|
WHERE doc->'tags' @> '[{"term":"paris"}, {"term":"food"}]';
|
|
|
|
</programlisting>
|
|
|
|
but that approach is less flexible, and often less efficient as well.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
On the other hand, the JSON existence operator is not nested: it will
|
|
|
|
only look for the specified key or array element at top level of the
|
|
|
|
JSON value.
|
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
The various containment and existence operators, along with all other
|
|
|
|
JSON operators and functions are documented
|
2017-11-23 15:39:47 +01:00
|
|
|
in <xref linkend="functions-json"/>.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<sect2 id="json-indexing">
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><type>jsonb</type> Indexing</title>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<indexterm>
|
|
|
|
<primary>jsonb</primary>
|
|
|
|
<secondary>indexes on</secondary>
|
|
|
|
</indexterm>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2014-05-11 00:56:52 +02:00
|
|
|
GIN indexes can be used to efficiently search for
|
2014-05-09 22:33:25 +02:00
|
|
|
keys or key/value pairs occurring within a large number of
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>jsonb</type> documents (datums).
|
|
|
|
Two GIN <quote>operator classes</quote> are provided, offering different
|
2014-07-17 04:20:15 +02:00
|
|
|
performance and flexibility trade-offs.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The default GIN operator class for <type>jsonb</type> supports queries with
|
|
|
|
top-level key-exists operators <literal>?</literal>, <literal>?&</literal>
|
|
|
|
and <literal>?|</literal> operators and path/value-exists operator
|
|
|
|
<literal>@></literal>.
|
2014-05-09 22:33:25 +02:00
|
|
|
(For details of the semantics that these operators
|
2017-11-23 15:39:47 +01:00
|
|
|
implement, see <xref linkend="functions-jsonb-op-table"/>.)
|
2014-05-09 22:33:25 +02:00
|
|
|
An example of creating an index with this operator class is:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2015-05-15 17:42:29 +02:00
|
|
|
CREATE INDEX idxgin ON api USING GIN (jdoc);
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
The non-default GIN operator class <literal>jsonb_path_ops</literal>
|
|
|
|
supports indexing the <literal>@></literal> operator only.
|
2014-05-09 22:33:25 +02:00
|
|
|
An example of creating an index with this operator class is:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2015-05-15 17:42:29 +02:00
|
|
|
CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops);
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
|
|
|
Consider the example of a table that stores JSON documents
|
|
|
|
retrieved from a third-party web service, with a documented schema
|
2014-05-09 22:33:25 +02:00
|
|
|
definition. A typical document is:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
{
|
|
|
|
"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"
|
|
|
|
]
|
|
|
|
}
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
We store these documents in a table named <structname>api</structname>,
|
|
|
|
in a <type>jsonb</type> column named <structfield>jdoc</structfield>.
|
2014-05-09 22:33:25 +02:00
|
|
|
If a GIN index is created on this column,
|
|
|
|
queries like the following can make use of the index:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Find documents in which the key "company" has value "Magnafone"
|
2014-05-09 22:33:25 +02:00
|
|
|
SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}';
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
However, the index could not be used for queries like the
|
2017-10-09 03:44:17 +02:00
|
|
|
following, because though the operator <literal>?</literal> is indexable,
|
|
|
|
it is not applied directly to the indexed column <structfield>jdoc</structfield>:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Find documents in which the key "tags" contains key or array element "qui"
|
2014-05-09 22:33:25 +02:00
|
|
|
SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui';
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
Still, with appropriate use of expression indexes, the above
|
|
|
|
query can use an index. If querying for particular items within
|
2017-10-09 03:44:17 +02:00
|
|
|
the <literal>"tags"</literal> key is common, defining an index like this
|
2014-05-11 00:56:52 +02:00
|
|
|
may be worthwhile:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2015-05-15 17:42:29 +02:00
|
|
|
CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags'));
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
Now, the <literal>WHERE</literal> clause <literal>jdoc -> 'tags' ? 'qui'</literal>
|
2014-05-09 22:33:25 +02:00
|
|
|
will be recognized as an application of the indexable
|
2017-10-09 03:44:17 +02:00
|
|
|
operator <literal>?</literal> to the indexed
|
|
|
|
expression <literal>jdoc -> 'tags'</literal>.
|
2014-05-09 22:33:25 +02:00
|
|
|
(More information on expression indexes can be found in <xref
|
2017-11-23 15:39:47 +01:00
|
|
|
linkend="indexes-expressional"/>.)
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2014-05-09 22:33:25 +02:00
|
|
|
Another approach to querying is to exploit containment, for example:
|
2014-07-08 17:39:07 +02:00
|
|
|
<programlisting>
|
2014-05-11 00:56:52 +02:00
|
|
|
-- Find documents in which the key "tags" contains array element "qui"
|
2014-05-09 22:33:25 +02:00
|
|
|
SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}';
|
2014-07-08 17:39:07 +02:00
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
A simple GIN index on the <structfield>jdoc</structfield> column can support this
|
2014-05-11 00:56:52 +02:00
|
|
|
query. But note that such an index will store copies of every key and
|
2017-10-09 03:44:17 +02:00
|
|
|
value in the <structfield>jdoc</structfield> column, whereas the expression index
|
2014-05-11 00:56:52 +02:00
|
|
|
of the previous example stores only data found under
|
2017-10-09 03:44:17 +02:00
|
|
|
the <literal>tags</literal> key. While the simple-index approach is far more
|
2014-05-11 00:56:52 +02:00
|
|
|
flexible (since it supports queries about any key), targeted expression
|
|
|
|
indexes are likely to be smaller and faster to search than a simple
|
|
|
|
index.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2014-05-11 18:06:04 +02:00
|
|
|
Although the <literal>jsonb_path_ops</literal> operator class supports
|
2017-10-09 03:44:17 +02:00
|
|
|
only queries with the <literal>@></literal> operator, it has notable
|
2014-05-09 22:33:25 +02:00
|
|
|
performance advantages over the default operator
|
2014-05-11 18:06:04 +02:00
|
|
|
class <literal>jsonb_ops</literal>. A <literal>jsonb_path_ops</literal>
|
2014-05-11 00:56:52 +02:00
|
|
|
index is usually much smaller than a <literal>jsonb_ops</literal>
|
2014-05-09 22:33:25 +02:00
|
|
|
index over the same data, and the specificity of searches is better,
|
2014-05-11 00:56:52 +02:00
|
|
|
particularly when queries contain keys that appear frequently in the
|
|
|
|
data. Therefore search operations typically perform better
|
2014-05-09 22:33:25 +02:00
|
|
|
than with the default operator class.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
2014-05-09 22:33:25 +02:00
|
|
|
|
2014-05-11 18:06:04 +02:00
|
|
|
<para>
|
|
|
|
The technical difference between a <literal>jsonb_ops</literal>
|
|
|
|
and a <literal>jsonb_path_ops</literal> GIN index is that the former
|
|
|
|
creates independent index items for each key and value in the data,
|
|
|
|
while the latter creates index items only for each value in the
|
2014-07-08 17:39:07 +02:00
|
|
|
data.
|
2014-06-21 21:33:23 +02:00
|
|
|
<footnote>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
For this purpose, the term <quote>value</quote> includes array elements,
|
2014-06-21 21:33:23 +02:00
|
|
|
though JSON terminology sometimes considers array elements distinct
|
|
|
|
from values within objects.
|
|
|
|
</para>
|
|
|
|
</footnote>
|
|
|
|
Basically, each <literal>jsonb_path_ops</literal> index item is
|
|
|
|
a hash of the value and the key(s) leading to it; for example to index
|
2014-05-11 18:06:04 +02:00
|
|
|
<literal>{"foo": {"bar": "baz"}}</literal>, a single index item would
|
2017-10-09 03:44:17 +02:00
|
|
|
be created incorporating all three of <literal>foo</literal>, <literal>bar</literal>,
|
|
|
|
and <literal>baz</literal> into the hash value. Thus a containment query
|
2014-05-11 18:06:04 +02:00
|
|
|
looking for this structure would result in an extremely specific index
|
2017-10-09 03:44:17 +02:00
|
|
|
search; but there is no way at all to find out whether <literal>foo</literal>
|
2014-05-11 18:06:04 +02:00
|
|
|
appears as a key. On the other hand, a <literal>jsonb_ops</literal>
|
2017-10-09 03:44:17 +02:00
|
|
|
index would create three index items representing <literal>foo</literal>,
|
|
|
|
<literal>bar</literal>, and <literal>baz</literal> separately; then to do the
|
2014-05-11 18:06:04 +02:00
|
|
|
containment query, it would look for rows containing all three of
|
|
|
|
these items. While GIN indexes can perform such an AND search fairly
|
|
|
|
efficiently, it will still be less specific and slower than the
|
|
|
|
equivalent <literal>jsonb_path_ops</literal> search, especially if
|
|
|
|
there are a very large number of rows containing any single one of the
|
|
|
|
three index items.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A disadvantage of the <literal>jsonb_path_ops</literal> approach is
|
|
|
|
that it produces no index entries for JSON structures not containing
|
|
|
|
any values, such as <literal>{"a": {}}</literal>. If a search for
|
|
|
|
documents containing such a structure is requested, it will require a
|
2017-10-09 03:44:17 +02:00
|
|
|
full-index scan, which is quite slow. <literal>jsonb_path_ops</literal> is
|
2014-05-11 18:06:04 +02:00
|
|
|
therefore ill-suited for applications that often perform such searches.
|
|
|
|
</para>
|
|
|
|
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>jsonb</type> also supports <literal>btree</literal> and <literal>hash</literal>
|
2014-05-09 22:33:25 +02:00
|
|
|
indexes. These are usually useful only if it's important to check
|
|
|
|
equality of complete JSON documents.
|
2017-10-09 03:44:17 +02:00
|
|
|
The <literal>btree</literal> ordering for <type>jsonb</type> datums is seldom
|
2014-05-11 00:56:52 +02:00
|
|
|
of great interest, but for completeness it is:
|
2014-07-08 17:39:07 +02:00
|
|
|
<synopsis>
|
|
|
|
<replaceable>Object</replaceable> > <replaceable>Array</replaceable> > <replaceable>Boolean</replaceable> > <replaceable>Number</replaceable> > <replaceable>String</replaceable> > <replaceable>Null</replaceable>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-07-08 17:39:07 +02:00
|
|
|
<replaceable>Object with n pairs</replaceable> > <replaceable>object with n - 1 pairs</replaceable>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
|
2014-07-08 17:39:07 +02:00
|
|
|
<replaceable>Array with n elements</replaceable> > <replaceable>array with n - 1 elements</replaceable>
|
|
|
|
</synopsis>
|
2014-05-09 22:33:25 +02:00
|
|
|
Objects with equal numbers of pairs are compared in the order:
|
2014-07-08 17:39:07 +02:00
|
|
|
<synopsis>
|
|
|
|
<replaceable>key-1</replaceable>, <replaceable>value-1</replaceable>, <replaceable>key-2</replaceable> ...
|
|
|
|
</synopsis>
|
2014-05-11 00:56:52 +02:00
|
|
|
Note that object keys are compared in their storage order;
|
2014-05-09 22:33:25 +02:00
|
|
|
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>
|
2014-05-11 00:56:52 +02:00
|
|
|
Similarly, arrays with equal numbers of elements are compared in the
|
|
|
|
order:
|
2014-07-08 17:39:07 +02:00
|
|
|
<synopsis>
|
|
|
|
<replaceable>element-1</replaceable>, <replaceable>element-2</replaceable> ...
|
|
|
|
</synopsis>
|
2014-05-09 22:33:25 +02:00
|
|
|
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.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
2018-03-28 14:32:43 +02:00
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Transforms</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Additional extensions are available that implement transforms for the
|
2018-04-03 15:47:18 +02:00
|
|
|
<type>jsonb</type> type for different procedural languages.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The extensions for PL/Perl are called <literal>jsonb_plperl</literal> and
|
|
|
|
<literal>jsonb_plperlu</literal>. If you use them, <type>jsonb</type>
|
|
|
|
values are mapped to Perl arrays, hashes, and scalars, as appropriate.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The extensions for PL/Python are called <literal>jsonb_plpythonu</literal>,
|
2018-03-28 14:32:43 +02:00
|
|
|
<literal>jsonb_plpython2u</literal>, and
|
|
|
|
<literal>jsonb_plpython3u</literal> (see <xref
|
|
|
|
linkend="plpython-python23"/> for the PL/Python naming convention). If you
|
|
|
|
use them, <type>jsonb</type> values are mapped to Python dictionaries,
|
|
|
|
lists, and scalars, as appropriate.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
</sect1>
|