diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5126f14eb6..8a10eb30cb 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10081,7 +10081,7 @@ table2-mapping
JSON
- Functions and operators
+ functions and operators
@@ -10105,43 +10105,43 @@ table2-mapping
->
- int
+ intGet JSON array element'[{"a":"foo"},{"a":"bar"},{"a":"baz"}]'::json->2{"a":"baz"}->
- text
+ textGet JSON object field'{"a": {"b":"foo"}}'::json->'a'{"b":"foo"}->>
- int
- Get JSON array element as text
+ int
+ Get JSON array element as text>'[1,2,3]'::json->>23->>
- text
- Get JSON object field as text
+ text
+ Get JSON object field as text>'{"a":1,"b":2}'::json->>'b'2#>
- text[]
+ text[]Get JSON object at specified path'{"a": {"b":{"c": "foo"}}}'::json#>'{a,b}'{"c": "foo"}#>>
- text[]
- Get JSON object at specified path as text
+ text[]
+ Get JSON object at specified path as text>'{"a":[1,2,3],"b":[4,5,6]}'::json#>>'{a,2}'3
@@ -10152,14 +10152,17 @@ table2-mapping
There are parallel variants of these operators for both the
- json and jsonb types. In addition to
- those operators common to both types, a further set of operators
- exists for jsonb (which comprise the default
- GIN operator class).
+ json and jsonb types. The operators
+ return the same type as their left-hand input (either json
+ or jsonb), except for those specified as
+ returning text>, which coerce the value to text.
- The following are jsonb>-only operators, used by
+ In addition to those operators common to both types, some additional
+ operators exist only for jsonb, as shown
+ in .
+ Many of these operators can be indexed by
jsonb> operator classes. For a full description of
jsonb> containment semantics and nesting, see .
@@ -10167,7 +10170,7 @@ table2-mapping
jsonb>.
- Additonal JSONB Operators
+ Additional jsonb> Operators
@@ -10180,37 +10183,38 @@ table2-mapping
=
- jsonb
- Is the jsonb equal to this jsonb?
+ jsonb
+ Are the two JSON values equal?'[1,2,3]'::jsonb = '[1,2,3]'::jsonb@>
- jsonb
- Does the jsonb contain within it this jsonb?
+ jsonb
+ Does the left JSON value contain within it the right value?'{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb<@
- jsonb
- Does the jsonb have contained within it this jsonb?
+ jsonb
+ Is the left JSON value contained within the right value?'{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb?
- text
- Does this key/element string exist?
+ text
+ Does the key/element string exist within
+ the JSON value?'{"a":1, "b":2}'::jsonb ? 'b'?|
- text[]
+ text[]Do any of these key/element strings exist?'{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'c']?&
- text[]
+ text[]Do all of these key/element strings exist?'["a", "b"]'::jsonb ?& array['a', 'b']
@@ -10218,15 +10222,11 @@ table2-mapping
-
-
+ shows the functions that are
available for creating json values.
- (see )
+ (Currently, there are no equivalent functions for jsonb>, but you
+ can cast the result of one of these functions to jsonb>.)
@@ -10250,11 +10250,10 @@ table2-mapping
JSON Creation Functions
-
+ Function
- Return TypeDescriptionExampleExample Result
@@ -10265,7 +10264,6 @@ table2-mapping
array_to_json(anyarray [, pretty_bool])
- json
Returns the array as JSON. A PostgreSQL multidimensional array
becomes a JSON array of arrays. Line feeds will be added between
@@ -10278,7 +10276,6 @@ table2-mapping
row_to_json(record [, pretty_bool])
- json
Returns the row as JSON. Line feeds will be added between level
1 elements if pretty_bool is true.
@@ -10290,7 +10287,6 @@ table2-mapping
to_json(anyelement)
- json
Returns the value as JSON. If the data type is not built in, and there
is a cast from the type to json, the cast function will be used to
@@ -10305,43 +10301,29 @@ table2-mapping
json_build_array(VARIADIC "any")
- json
- Builds a heterogeneously-typed json array out of a variadic argument list.
-
- SELECT json_build_array(1,2,'3',4,5);
-
-
- json_build_array
--------------------
- [1, 2, "3", 4, 5]
-
+ Builds a possibly-heterogeneously-typed JSON array out of a variadic
+ argument list.
+ json_build_array(1,2,'3',4,5)
+ [1, 2, "3", 4, 5]json_build_object(VARIADIC "any")
- json
- Builds a JSON array out of a variadic argument list. By
- convention, the object is constructed out of alternating
- name/value arguments.
-
- SELECT json_build_object('foo',1,'bar',2);
-
-
- json_build_object
-------------------------
- {"foo" : 1, "bar" : 2}
-
+ Builds a JSON object out of a variadic argument list. By
+ convention, the argument list consists of alternating
+ names and values.
+ json_build_object('foo',1,'bar',2)
+ {"foo" : 1, "bar" : 2}json_object(text[])
- json
Builds a JSON object out of a text array. The array must have either
exactly one dimension with an even number of members, in which case
@@ -10349,42 +10331,28 @@ table2-mapping
such that each inner array has exactly two elements, which
are taken as a name/value pair.
- select * from json_object('{a, 1, b, "def", c, 3.5}') or select json_object('{{a, 1},{b, "def"},{c, 3.5}}')
-
-
- json_object
----------------------------------------
- {"a" : "1", "b" : "def", "c" : "3.5"}
-
-
+ json_object('{a, 1, b, "def", c, 3.5}')>
+ json_object('{{a, 1},{b, "def"},{c, 3.5}}')>
+ {"a" : "1", "b" : "def", "c" : "3.5"}json_object(keys text[], values text[])
- json
- The two-argument form of JSON object takes keys and values pairwise from two separate
+ This form of json_object> takes keys and values pairwise from two separate
arrays. In all other respects it is identical to the one-argument form.
- select json_object('{a, b}', '{1,2}');
-
-
- json_object
-------------------------
- {"a" : "1", "b" : "2"}
-
-
+ json_object('{a, b}', '{1,2}')
+ {"a" : "1", "b" : "2"}
-
shows the functions that
are available for processing json and jsonb values.
- (see )
@@ -10494,8 +10462,8 @@ table2-mapping
json_each(json)jsonb_each(jsonb)
- SETOF key text, value json
- SETOF key text, value jsonb
+ setof key text, value json
+ setof key text, value jsonb
Expands the outermost JSON object into a set of key/value pairs.
@@ -10514,10 +10482,10 @@ table2-mapping
json_each_text(from_json json)jsonb_each_text(from_json jsonb)
- SETOF key text, value text
+ setof key text, value text
Expands the outermost JSON object into a set of key/value pairs. The
- returned value will be of type text.
+ returned value will be of type text>.
select * from json_each_text('{"a":"foo", "b":"bar"}')
@@ -10556,7 +10524,7 @@ table2-mapping
json_object_keys(json)jsonb_object_keys(jsonb)
- SETOF text
+ setof text
Returns set of keys in the JSON object. Only the outer object will be displayed.
@@ -10595,7 +10563,7 @@ table2-mapping
json_populate_recordset(base anyelement, from_json json, [, use_json_as_text bool=false])jsonb_populate_recordset(base anyelement, from_json jsonb, [, use_json_as_text bool=false])
- SETOF anyelement
+ setof anyelement
Expands the outermost set of objects in from_json to a set
whose columns match the record type defined by base.
@@ -10618,13 +10586,13 @@ table2-mapping
json_array_elements(json)jsonb_array_elements(jsonb)
- SETOF json
- SETOF jsonb
+ setof json
+ setof jsonb
Expands a JSON array to a set of JSON values.
- SELECT * FROM json_array_elements('[1,true, [2,false]]')
+ select * from json_array_elements('[1,true, [2,false]]')
value
@@ -10639,11 +10607,11 @@ table2-mapping
json_array_elements_text(json)jsonb_array_elements_text(jsonb)
- SETOF text
+ setof text
- Expands a JSON array to a set of text values.
+ Expands a JSON array to a set of text> values.
- SELECT * FROM json_array_elements_text('["foo", "bar"]')
+ select * from json_array_elements_text('["foo", "bar"]')
value
@@ -10674,9 +10642,9 @@ table2-mapping
record
Returns an arbitrary record from a JSON object. As with all functions
- returning 'record', the caller must explicitly define the structure of the record
+ returning record>, the caller must explicitly define the structure of the record
when making the call. The input JSON must be an object, not a scalar or an array.
- If nested_as_text is true, the function coerces nested complex elements to text.
+ If nested_as_text> is true, the function coerces nested complex elements to text.
Also, see notes below on columns and types.
select * from json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}',true) as x(a int, b text, d text)
@@ -10695,9 +10663,9 @@ table2-mapping
setof record
Returns an arbitrary set of records from a JSON object. As with
- json_to_record, the structure of the record must be explicitly defined when making the
- call. However, with json_to_recordset the input JSON must be an array containing
- objects. nested_as_text works as with json_to_record.
+ json_to_record>, the structure of the record must be explicitly defined when making the
+ call. However, with json_to_recordset> the input JSON must be an array containing
+ objects. nested_as_text> works as with json_to_record>.
select * from json_to_recordset('[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]',true) as x(a int, b text);
@@ -10715,56 +10683,60 @@ table2-mapping
- The json functions and operators can impose stricter validity requirements
- than the type's input functions. In particular, they check much more closely that any use
- of Unicode surrogate pairs to designate characters outside the Unicode Basic Multilingual
- Plane is correct.
+ The json functions and operators can impose stricter
+ validity requirements than the JSON types' input functions do. In
+ particular, they check much more closely that any use of Unicode
+ surrogate pairs to designate characters outside the Unicode Basic
+ Multilingual Plane is correct.
- Many of these functions and operators will convert Unicode escapes
- in the JSON text to the appropriate UTF8 character when the database encoding is UTF8. In
- other encodings the escape sequence must be for an ASCII character, and any other code point
- in a Unicode escape sequence will result in an error.
- In general, it is best to avoid mixing Unicode escapes in JSON with a non-UTF8 database
- encoding, if possible.
+ Many of these functions and operators will convert Unicode escapes in
+ the JSON text to the appropriate UTF8 character when the database
+ encoding is UTF8. In other encodings the escape sequence must be for an
+ ASCII character, and any other code point in a Unicode escape sequence
+ will result in an error. In general, it is best to avoid mixing Unicode
+ escapes in JSON with a non-UTF8 database encoding, if possible.
- In json_to_record and json_to_recordset, type-coercion from the JSON is
- "best effort" and may not result in desired values for some types. JSON
- elements are matched to identical field names in the record definition,
- and elements which do not exist in the JSON will simply be NULL. JSON
- elements which are not defined in the record template will
- be omitted from the output.
+ In json_to_record> and json_to_recordset>,
+ type coercion from the JSON is best effort> and may not result
+ in desired values for some types. JSON elements are matched to
+ identical field names in the record definition, and elements which do
+ not exist in the JSON will simply be NULL. JSON elements which are not
+ defined in the record template will be omitted from the output.
- The extension has a cast from hstore to
- json, so that converted hstore values are represented as JSON objects,
+ The extension has a cast
+ from hstore to json, so that
+ converted hstore values are represented as JSON objects,
not as string values.
- The json_typeof> function's null> return value should not be confused
- with a SQL NULL. While calling json_typeof('null'::json)> will return null>,
- calling json_typeof(NULL::json)> will return a SQL NULL.
+ The json_typeof> function's null> return value
+ should not be confused with a SQL NULL. While
+ calling json_typeof('null'::json)> will
+ return null>, calling json_typeof(NULL::json)>
+ will return a SQL NULL.
- See also about the aggregate
+ See also for the aggregate
function json_agg which aggregates record
- values as JSON efficiently, and the aggregate function
- json_object_agg, which aggregates pairs of values
+ values as JSON, and the aggregate function
+ json_object_agg which aggregates pairs of values
into a JSON object.
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 576ad3005a..41f7b91395 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -416,7 +416,7 @@
Of the two operator classes for type jsonb>, jsonb_ops>
is the default. jsonb_hash_ops> supports fewer operators but
- will work with larger indexed values than jsonb_ops> can support.
+ offers better performance for those operators.
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index 5fd2439742..592a5ce2b2 100644
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -15,118 +15,148 @@
JSON data types are for storing JSON (JavaScript Object Notation)
data, as specified in RFC
7159. Such data can also be stored as text, but
- both JSON data types have the advantage of enforcing that each
- stored value is a valid JSON value. There are also related support
- functions available; see .
+ the JSON data types have the advantage of enforcing that each
+ stored value is valid according to the JSON rules. There are also
+ assorted JSON-specific functions available for data stored in these
+ data types; see .
There are two JSON data types: json> and jsonb>.
- Both accept almost identical sets of values as
+ They accept almost> identical sets of values as
input. The major practical difference is one of efficiency. The
json> data type stores an exact copy of the input text,
- which processing functions must continually reparse, while
+ which processing functions must reparse on each execution; while
jsonb> data is stored in a decomposed binary format that
- makes it slightly less efficient to input due to added serialization
+ makes it slightly slower to input due to added conversion
overhead, but significantly faster to process, since it never needs
- reparsing. jsonb> also supports advanced
- GIN indexing, which is a further significant
- advantage.
+ reparsing. jsonb> also supports indexing, which can be a
+ significant advantage.
- The other difference between the types is that the json>
- type is guaranteed to contain an exact copy of the input, including
- preservation of semantically insignificant white space, and the
- order of keys within JSON objects (although jsonb> will
- preserve trailing zeros within a JSON number). Also, because the
- exact text is kept, if a JSON object within the value contains the
- same key more than once, and has been stored using the json>
- type, all the key/value pairs are kept. In that case, the
- processing functions consider the last value as the operative one.
- By contrast, jsonb> does not preserve white space, does not
- preserve the order of object keys, and does not keep duplicate
- object keys. Only the last value for a key specified in the input
- is kept.
+ Because the json> type stores an exact copy of the input text, it
+ will preserve semantically-insignificant white space between tokens, as
+ well as the order of keys within JSON objects. Also, if a JSON object
+ within the value contains the same key more than once, all the key/value
+ pairs are kept. (The processing functions consider the last value as the
+ operative one.) By contrast, jsonb> does not preserve white
+ space, does not preserve the order of object keys, and does not keep
+ duplicate object keys. Only the last value for a key specified in the
+ input is kept. jsonb> will preserve trailing zeros within a JSON
+ number, even though those are semantically insignificant for purposes such
+ as equality checks.
- In general, most applications will prefer to store JSON data as
- jsonb>, unless there are quite specialized needs.
+ In general, most applications should prefer to store JSON data as
+ jsonb>, unless there are quite specialized needs, such as
+ legacy assumptions about ordering of object keys.
- PostgreSQL allows only one server
+ PostgreSQL allows only one character set
encoding per database. It is therefore not possible for the JSON
- types to conform rigidly to the specification unless the server
+ types to conform rigidly to the JSON specification unless the database
encoding is UTF-8. Attempts to directly include characters which
- cannot be represented in the server encoding will fail; conversely,
- characters which can be represented in the server encoding but not
+ cannot be represented in the database encoding will fail; conversely,
+ characters which can be represented in the database encoding but not
in UTF-8 will be allowed. \uXXXX escapes are
- allowed regardless of the server encoding, and are checked only for
+ allowed regardless of the database encoding, and are checked only for
syntactic correctness.
Mapping of RFC-7159/JSON Primitive Types to PostgreSQL Types
- Mapping of type correspondence, notes
+ JSON scalar types and corresponding PostgreSQL types
- PostgreSQL typeRFC-7159/JSON primitive type
+ PostgreSQL typeNotes
- text>string>
- See general introductory notes on encoding and JSON
+ text>
+ See introductory notes on JSON and encoding
- numeric>number>
+ numeric>NaN and infinity values are disallowedboolean>boolean>
- Only lowercase true and false values are accepted
+ Only lowercase true and false spellings are accepted
- unknown>null>
- SQL NULL is orthogonal. NULL semantics do not apply.
+ (none)
+ SQL NULL is a different concept
- Primitive types described by RFC> 7159 are effectively
- internally mapped onto native
- PostgreSQL types. Therefore, there are
+ When converting textual JSON input into jsonb>,
+ the primitive types described by RFC> 7159 are effectively
+ mapped onto native
+ PostgreSQL types, as shown in
+ . Therefore, there are
some very minor additional constraints on what constitutes valid
jsonb that do not apply to the json
- type, or to JSON in the abstract, that pertain to limits on what
- can be represented by the underlying type system. These
+ type, nor to JSON in the abstract, corresponding to limits on what
+ can be represented by the underlying data type. Specifically,
+ jsonb> will reject numbers that are outside the range of
+ the PostgreSQLnumeric> data type,
+ while json> will not. Such
implementation-defined restrictions are permitted by
- RFC> 7159. However, in practice problems are far more
- likely to occur in other implementations which internally
+ RFC> 7159. However, in practice such problems are far more
+ likely to occur in other implementations, as it is common to
represent the number> JSON primitive type as IEEE 754
- double precision floating point values, which RFC> 7159
- explicitly anticipates and allows for. When using JSON as an
+ double precision floating point (which RFC> 7159
+ explicitly anticipates and allows for). When using JSON as an
interchange format with such systems, the danger of losing numeric
- precision in respect of data originally stored by
+ precision compared to data originally stored by
PostgreSQL should be considered.
-
- Conversely, as noted above there are some minor restrictions on
- the input format of JSON primitive types that do not apply to
- corresponding PostgreSQL types.
-
+
+ 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 PostgreSQL types.
+
+
+
+
+ jsonb> Input and Output Syntax
+
+ The input/output syntax for the JSON data types is as specified in
+ RFC> 7159.
+
+
+ The following are all valid json> (or jsonb>) expressions:
+
+-- Simple scalar/primitive value (explicitly required by RFC-7159)
+SELECT '5'::json;
+
+-- Array of heterogeneous, primitive-typed elements
+SELECT '[1, 2, "foo", null]'::json;
+
+-- Object of heterogeneous key/value pairs of primitive types
+-- Note that key values are always strings
+SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::json;
+
+
+
+ Note the distinction between scalar/primitive values as array elements,
+ keys and values.
+
@@ -144,46 +174,19 @@
summarize a set of documents> (datums) in a table.
- jsonb> data is subject to the same concurrency control
+ json> data is subject to the same concurrency control
considerations as any other datatype when stored in a table.
Although storing large documents is practicable, in order to ensure
correct behavior row-level locks are, quite naturally, acquired as
- rows are updated. Consider keeping jsonb> documents at a
+ rows are updated. Consider keeping json> documents at a
manageable size in order to decrease lock contention among updating
- transactions. Ideally, jsonb> documents should each
+ transactions. Ideally, json> documents should each
represent an atomic datum that business rules dictate cannot
reasonably be further subdivided into smaller atomic datums that
can be independently modified.
-
- jsonb> Input and Output Syntax
-
- In effect, jsonb> has an internal type system whose
- implementation is defined in terms of several particular ordinary
- PostgreSQL types. The SQL parser does
- not have direct knowledge of the internal types that constitute a
- jsonb>.
-
-
- The following are all valid jsonb> expressions:
-
--- Simple scalar/primitive value (explicitly required by RFC-7159)
-SELECT '5'::jsonb;
--- Array of heterogeneous, primitive-typed elements
-SELECT '[1, 2, "foo", null]'::jsonb;
-
--- Object of heterogeneous key/value pairs of primitive types
--- Note that key values are always strings
-SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::jsonb;
-
-
-
- Note the distinction between scalar/primitive values as elements,
- keys and values.
-
- jsonb> containment
@@ -199,7 +202,7 @@ SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::jsonb;
technically, top-down, unordered subtree isomorphism>
may be tested. Containment is conventionally tested using the
@>> operator, which is made indexable by various
- operator classes discussed later in this section.
+ operator classes discussed below.
-- Simple scalar/primitive values may contain only each other:
@@ -249,45 +252,47 @@ SELECT '{"p":1, "a":{"b":3, "q":11}, "i":77}'::jsonb @> '{"a":{"b":3}}'::jsonb;
The various containment operators, along with all other JSON
- operators and support functions are documented fully within , .
+ operators and support functions are documented in .
+
- jsonb> GIN Indexing
+ jsonb> Indexingjsonbindexes on
-
- jsonb> GIN indexes can be used to efficiently search among
- more than one possible key/value pair within a single
- jsonb> datum/document, among a large number of such
- documents within a column in a table (i.e. among many rows).
-
-
- jsonb> has GIN index support for the @>>,
- ?>, ?&> and ?|> operators.
- The default GIN operator class makes all these operators
- indexable:
-
-
--- GIN index (default opclass)
-CREATE INDEX idxgin ON api USING GIN (jdoc);
--- GIN jsonb_hash_ops index
-CREATE INDEX idxginh ON api USING GIN (jdoc jsonb_hash_ops);
-
+ jsonb> GIN indexes can be used to efficiently search for
+ keys or key/value pairs occurring within a large number of
+ jsonb> documents (datums).
+ Two GIN operator classes> are provided, offering different
+ performance and flexibility tradeoffs.
+
+
+ The default GIN operator class supports queries with the
+ @>>, ?>, ?&> and ?|>
+ operators.
+ (For details of the semantics that these operators
+ implement, see .)
+ An example of creating an index with this operator class is:
+
+CREATE INDEX idxgin ON api USING gin (jdoc);
+
The non-default GIN operator class jsonb_hash_ops>
supports indexing the @>> operator only.
+ An example of creating an index with this operator class is:
+
+CREATE INDEX idxginh ON api USING gin (jdoc jsonb_hash_ops);
+
+
Consider the example of a table that stores JSON documents
retrieved from a third-party web service, with a documented schema
- definition. An example of a document retrieved from this web
- service is as follows:
+ definition. A typical document is:
{
"guid": "9c36adc1-7fb5-4d5b-83b4-90356a46061a",
@@ -305,85 +310,67 @@ CREATE INDEX idxginh ON api USING GIN (jdoc jsonb_hash_ops);
]
}
- If a GIN index is created on the table that stores these
- documents, api, on its jdoc>
- jsonb> column, we can expect that queries like the
- following may make use of the index:
+ We store these documents in a table named api>,
+ in a jsonb> column named jdoc>.
+ If a GIN index is created on this column,
+ queries like the following can make use of the index:
-- Note that both key and value have been specified
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}';
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}';
However, the index could not be used for queries like the
- following, due to the aforementioned nesting restriction:
+ following, because though the operator ?> is indexable,
+ it is not applied directly to the indexed column jdoc>:
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui';
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui';
- Still, with judicious use of expressional indexing, the above
+ Still, with judicious use of expression indexes, the above
query can use an index scan. If there is a requirement to find
those records with a particular tag quickly, and the tags have a
high cardinality across all documents, defining an index as
follows is an effective approach to indexing:
--- Note that the "jsonb -> text" operator can only be called on an
--- object, so as a consequence of creating this index the root "jdoc"
--- datum must be an object. This is enforced during insertion.
-CREATE INDEX idxgin ON api USING GIN ((jdoc -> 'tags'));
+-- Note that the "jsonb -> text" operator can only be called on an
+-- object, so as a consequence of creating this index the root of each
+-- "jdoc" value must be an object. This is enforced during insertion.
+CREATE INDEX idxgintags ON api USING gin ((jdoc -> 'tags'));
+ Now, the WHERE> clause jdoc -> 'tags' ? 'qui'>
+ will be recognized as an application of the indexable
+ operator ?> to the indexed
+ expression jdoc -> 'tags'>.
+ (More information on expression indexes can be found in .)
- Expressional indexes are discussed in .
-
-
- For the most flexible approach in terms of what may be indexed,
- sophisticated querying on nested structures is possible by
- exploiting containment. At the cost of having to create an index
- on the entire structure for each row, and not just a nested
- subset, we may exploit containment semantics to get an equivalent
- result with a non-expressional index on the entire jdoc>
- column, without> ever having to create additional
- expressional indexes against the document (provided only
- containment will be tested). While the index will be considerably
- larger than our expression index, it will also be much more
- flexible, allowing arbitrary structured searching. Such an index
- can generally be expected to help with a query like the following:
-
+ Another approach to querying is to exploit containment, for example:
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}';
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}';
-
- For full details of the semantics that these indexable operators
- implement, see , .
+ This approach uses a single GIN index covering everything in the
+ jdoc> column, whereas our expression index stored only
+ data found under the tags> key. While the single-index
+ approach is certainly more flexible, targeted expression indexes
+ are likely to be smaller and faster to search than a single index.
-
-
- jsonb> non-default GIN operator class
-
- jsonb
- indexes on
-
+
- Although only the @>> operator is made indexable, a
- jsonb_hash_ops operator class GIN index has
- some notable advantages over an equivalent GIN index of the
- default GIN operator class for jsonb. Search
- operations typically perform considerably better, and the on-disk
- size of a jsonb_hash_ops operator class GIN
- index can be much smaller.
+ Although the jsonb_hash_ops operator class supports
+ only queries with the @>> operator, it has notable
+ performance advantages over the default operator
+ class jsonb_ops. A jsonb_hash_ops
+ GIN index is usually much smaller than a jsonb_ops
+ index over the same data, and the specificity of searches is better,
+ particularly when queries contain tags that appear frequently in the
+ data. Therefore search operations typically perform considerably better
+ than with the default operator class.
-
-
- jsonb> B-Tree and hash indexing
+
- jsonb comparisons and related operations are
- type-wise>, in that the underlying
- PostgreSQL datatype comparators are
- invoked recursively, much like a traditional composite type.
-
-
- jsonb> also supports btree> and hash>
- indexes. Ordering between jsonb> datums is:
+ jsonb> also supports btree> and hash>
+ indexes. These are usually useful only if it's important to check
+ equality of complete JSON documents.
+ The btree> ordering for jsonb> datums is:
Object > Array > Boolean > Number > String > Null
@@ -391,23 +378,24 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}';
Array with n elements > array with n - 1 elements
- Subsequently, individual primitive type comparators are invoked.
- All comparisons of JSON primitive types occurs using the same
- comparison rules as the underlying
- PostgreSQL types. Strings are
- compared lexically, using the default database collation.
- Objects with equal numbers of pairs are compared:
+ Objects with equal numbers of pairs are compared in the order:
key-1, value-1, key-2 ...
- Note however that object keys are compared in their storage order, and in particular,
- since shorter keys are stored before longer keys, this can lead to results that might be
- unintuitive, such as:
- { "aa": 1, "c": 1} > {"b": 1, "d": 1}
+ Note however that object keys are compared in their storage order, and
+ in particular, since shorter keys are stored before longer keys, this
+ can lead to results that might be unintuitive, such as:
+
+{ "aa": 1, "c": 1} > {"b": 1, "d": 1}
+
Similarly, arrays with equal numbers of elements are compared:
element-1, element-2 ...
+ Primitive JSON values are compared using the same
+ comparison rules as for the underlying
+ PostgreSQL data type. Strings are
+ compared using the default database collation.
diff --git a/doc/src/sgml/release-9.3.sgml b/doc/src/sgml/release-9.3.sgml
index b4053c62bc..64b1801f3c 100644
--- a/doc/src/sgml/release-9.3.sgml
+++ b/doc/src/sgml/release-9.3.sgml
@@ -3618,14 +3618,14 @@ ALTER EXTENSION hstore UPDATE;
Allow JSON> values to be converted into records
+ linkend="functions-json">converted into records
(Andrew Dunstan)
- Add functions to convert
+ Add functions to convert
scalars, records, and hstore> values to JSON> (Andrew
Dunstan)