From 443dd97001c4cdb78ec388fffd5780ddccb3218f Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 8 Jul 2014 11:39:07 -0400 Subject: doc: Fix spacing in verbatim environments --- doc/src/sgml/json.sgml | 64 +++++++++++++++++++++++++------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) (limited to 'doc/src/sgml/json.sgml') diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml index d55a08fb18a..4fadf65558e 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -163,7 +163,7 @@ The following are all valid json (or jsonb) expressions: - + -- Simple scalar/primitive value -- Primitive values can be numbers, quoted strings, true, false, or null SELECT '5'::json; @@ -177,7 +177,7 @@ 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; - + @@ -262,7 +262,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; one jsonb document has contained within it another one. These examples return true except as noted: - + -- Simple scalar/primitive values contain only the identical value: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; @@ -282,7 +282,7 @@ SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; -- Similarly, containment is not reported here: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false - + The general principle is that the contained object must match the @@ -296,13 +296,13 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields f As a special exception to the general principle that the structures must match, an array may contain a primitive value: - + -- This array contains the primitive string value: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; -- This exception is not reciprocal -- non-containment is reported here: SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false - + jsonb also has an existence operator, which is @@ -363,22 +363,22 @@ SELECT '"foo"'::jsonb ? 'foo'; (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_path_ops supports indexing the @> operator only. An example of creating an index with this operator class is: - + CREATE INDEX idxginp ON api USING gin (jdoc jsonb_path_ops); - + Consider the example of a table that stores JSON documents retrieved from a third-party web service, with a documented schema definition. A typical document is: - + { "guid": "9c36adc1-7fb5-4d5b-83b4-90356a46061a", "name": "Angela Barton", @@ -394,32 +394,32 @@ CREATE INDEX idxginp ON api USING gin (jdoc jsonb_path_ops); "qui" ] } - + 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: - + -- Find documents in which the key "company" has value "Magnafone" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; - + However, the index could not be used for queries like the following, because though the operator ? is indexable, it is not applied directly to the indexed column jdoc: - + -- Find documents in which the key "tags" contains key or array element "qui" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; - + Still, with appropriate use of expression indexes, the above query can use an index. If querying for particular items within the "tags" key is common, defining an index like this may be worthwhile: - + -- Note that the "jsonb -> text" operator can only be called on a JSON -- 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 @@ -429,10 +429,10 @@ CREATE INDEX idxgintags ON api USING gin ((jdoc -> 'tags')); Another approach to querying is to exploit containment, for example: - + -- Find documents in which the key "tags" contains array element "qui" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; - + A simple GIN index on the jdoc column can support this query. But note that such an index will store copies of every key and value in the jdoc column, whereas the expression index @@ -460,7 +460,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu and a jsonb_path_ops 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 - data. + data. For this purpose, the term value includes array elements, @@ -501,17 +501,17 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu equality of complete JSON documents. The btree ordering for jsonb datums is seldom of great interest, but for completeness it is: - - Object > Array > Boolean > Number > String > Null + +Object > Array > Boolean > Number > String > Null - Object with n pairs > object with n - 1 pairs +Object with n pairs > object with n - 1 pairs - Array with n elements > array with n - 1 elements - +Array with n elements > array with n - 1 elements + Objects with equal numbers of pairs are compared in the order: - - key-1, value-1, key-2 ... - + +key-1, value-1, key-2 ... + Note that object keys are compared in their storage order; in particular, since shorter keys are stored before longer keys, this can lead to results that might be unintuitive, such as: @@ -520,9 +520,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu Similarly, arrays with equal numbers of elements are compared in the order: - - element-1, element-2 ... - + +element-1, element-2 ... + Primitive JSON values are compared using the same comparison rules as for the underlying PostgreSQL data type. Strings are -- cgit v1.2.3