- linkend="json-containment"/>.
- describes how these operators can be used to effectively index
- jsonb data.
-
-
Additional <type>jsonb</type> Operators
-
-
- |
- Operator
- Right Operand Type
- Description
- Example
-
-
-
- |
- @>
- jsonb
- Does the left JSON value contain the right JSON
- path/value entries at the top level?
- '{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb
-
- |
- <@
- jsonb
- Are the left JSON path/value entries contained at the top level within
- the right JSON value?
- '{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb
-
- |
- ?
- text
- Does the string exist as a top-level
- key within the JSON value?
- '{"a":1, "b":2}'::jsonb ? 'b'
-
- |
- ?|
- text[]
- Do any of these array strings
- exist as top-level keys?
- '{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'c']
-
- |
- ?&
- text[]
- Do all of these array strings exist
- as top-level keys?
- '["a", "b"]'::jsonb ?& array['a', 'b']
-
- |
- ||
- jsonb
- Concatenate two jsonb values into a new jsonb value
- '["a", "b"]'::jsonb || '["c", "d"]'::jsonb
-
- |
- -
- text
- Delete key/value pair or string
- element from left operand. Key/value pairs are matched based
- on their key value.
- '{"a": "b"}'::jsonb - 'a'
-
- |
- -
- text[]
- Delete multiple key/value pairs or string
- elements from left operand. Key/value pairs are matched based
- on their key value.
- '{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[]
-
- |
- -
- integer
- Delete the array element with specified index (Negative
- integers count from the end). Throws an error if top level
- container is not an array.
- '["a", "b"]'::jsonb - 1
-
- |
- #-
- text[]
- Delete the field or element with specified path (for
- JSON arrays, negative integers count from the end)
- '["a", {"b":1}]'::jsonb #- '{1,b}'
-
- |
- @?
- jsonpath
- Does JSON path return any item for the specified JSON value?
- '{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'
-
- |
- @@
- jsonpath
- Returns the result of JSON path predicate check for the specified JSON value.
- Only the first item of the result is taken into account. If the
- result is not Boolean, then null is returned.
- '{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'
-
-
-
-
+
+
+
+
The SQL/JSON Path Language
+
+
+
+
+ SQL/JSON path expressions specify the items to be retrieved
+ from the JSON data, similar to XPath expressions used
+ for SQL access to XML. In
PostgreSQL,
+ path expressions are implemented as the jsonpath
+ data type and can use any elements described in
+ .
+
+
+
JSON query functions and operators+ pass the provided path expression to the path engine
+ for evaluation. If the expression matches the queried JSON data,
+ the corresponding SQL/JSON item is returned.
+ Path expressions are written in the SQL/JSON path language
+ and can also include arithmetic expressions and functions.
+ Query functions treat the provided expression as a
+ text string, so it must be enclosed in single quotes.
+
+
+ A path expression consists of a sequence of elements allowed
+ by the jsonpath data type.
+ The path expression is evaluated from left to right, but
+ you can use parentheses to change the order of operations.
+ If the evaluation is successful, a sequence of SQL/JSON items
+ (SQL/JSON sequence) is produced,
+ and the evaluation result is returned to the JSON query function
+ that completes the specified computation.
+
+
+ To refer to the JSON data to be queried (the
+ context item), use the $ sign
+ in the path expression. It can be followed by one or more
+ accessor operators,
+ which go down the JSON structure level by level to retrieve the
+ content of context item. Each operator that follows deals with the
+ result of the previous evaluation step.
+
+
+ For example, suppose you have some JSON data from a GPS tracker that you
+ would like to parse, such as:
+{ "track" :
+ {
+ "segments" : [
+ { "location": [ 47.763, 13.4034 ],
+ "start time": "2018-10-14 10:05:14",
+ "HR": 73
+ },
+ { "location": [ 47.706, 13.2635 ],
+ "start time": "2018-10-14 10:39:21",
+ "HR": 135
+ } ]
+ }
+}
+
+
+
+ To retrieve the available track segments, you need to use the
+ .key accessor
+ operator for all the preceding JSON objects:
+'$.track.segments'
+
+
+
+ If the item to retrieve is an element of an array, you have
+ to unnest this array using the [*] operator. For example,
+ the following path will return location coordinates for all
+ the available track segments:
+'$.track.segments[*].location'
+
+
+
+ To return the coordinates of the first segment only, you can
+ specify the corresponding subscript in the []
+ accessor operator. Note that the SQL/JSON arrays are 0-relative:
+'$.track.segments[0].location'
+
+
+
+ The result of each path evaluation step can be processed
+ by one or more jsonpath operators and methods
+ listed in .
+ Each method name must be preceded by a dot. For example,
+ you can get an array size:
+'$.track.segments.size()'
+
+ For more examples of using jsonpath operators
+ and methods within path expressions, see
+ .
+
+
+ When defining the path, you can also use one or more
+ filter expressions that work similar to the
+ WHERE clause in SQL. A filter expression begins with
+ a question mark and provides a condition in parentheses:
+
+? (condition)
+
+
+
+ Filter expressions must be specified right after the path evaluation step
+ to which they are applied. The result of this step is filtered to include
+ only those items that satisfy the provided condition. SQL/JSON defines
+ three-valued logic, so the condition can be true, false,
+ or unknown. The unknown value
+ plays the same role as SQL NULL and can be tested
+ for with the is unknown predicate. Further path
+ evaluation steps use only those items for which filter expressions
+ return true.
+
+
+ Functions and operators that can be used in filter expressions are listed
+ in . The path
+ evaluation result to be filtered is denoted by the @
+ variable. To refer to a JSON element stored at a lower nesting level,
+ add one or more accessor operators after @.
+
+
+ Suppose you would like to retrieve all heart rate values higher
+ than 130. You can achieve this using the following expression:
+'$.track.segments[*].HR ? (@ > 130)'
+
+
+
+ To get the start time of segments with such values instead, you have to
+ filter out irrelevant segments before returning the start time, so the
+ filter expression is applied to the previous step, and the path used
+ in the condition is different:
+'$.track.segments[*] ? (@.HR > 130)."start time"'
+
+
+
+ You can use several filter expressions on the same nesting level, if
+ required. For example, the following expression selects all segments
+ that contain locations with relevant coordinates and high heart rate values:
+'$.track.segments[*] ? (@.location[1] < 13.4) ? (@.HR > 130)."start time"'
+
+
+
+ Using filter expressions at different nesting levels is also allowed.
+ The following example first filters all segments by location, and then
+ returns high heart rate values for these segments, if available:
+'$.track.segments[*] ? (@.location[1] < 13.4).HR ? (@ > 130)'
+
+
+
+ You can also nest filter expressions within each other:
+'$.track ? (exists(@.segments[*] ? (@.HR > 130))).segments.size()'
+
+ This expression returns the size of the track if it contains any
+ segments with high heart rate values, or an empty sequence otherwise.
+
+
+
PostgreSQL's implementation of SQL/JSON path
+ language has the following deviations from the SQL/JSON standard:
+
+
+
+
+ .datetime() item method is not implemented yet
+ mainly because immutable jsonpath functions and operators
+ cannot reference session timezone, which is used in some datetime
+ operations. Datetime support will be added to jsonpath
+ in future versions of
PostgreSQL.
+
+
+
+
+ A path expression can be a Boolean predicate, although the SQL/JSON
+ standard allows predicates only in filters. This is necessary for
+ implementation of the @@ operator. For example,
+ the following jsonpath expression is valid in
+'$.track.segments[*].HR < 70'
+
+
+
+
+
+ There are minor differences in the interpretation of regular
+ expression patterns used in like_regex filters, as
+ described in .
+
+
+
+
+
+
Strict and Lax Modes
+ When you query JSON data, the path expression may not match the
+ actual JSON data structure. An attempt to access a non-existent
+ member of an object or element of an array results in a
+ structural error. SQL/JSON path expressions have two modes
+ of handling structural errors:
+
+
+
+
+ lax (default) — the path engine implicitly adapts
+ the queried data to the specified path.
+ Any remaining structural errors are suppressed and converted
+ to empty SQL/JSON sequences.
+
+
+
+ strict — if a structural error occurs, an error is raised.
+
+
+
+
+ The lax mode facilitates matching of a JSON document structure and path
+ expression if the JSON data does not conform to the expected schema.
+ If an operand does not match the requirements of a particular operation,
+ it can be automatically wrapped as an SQL/JSON array or unwrapped by
+ converting its elements into an SQL/JSON sequence before performing
+ this operation. Besides, comparison operators automatically unwrap their
+ operands in the lax mode, so you can compare SQL/JSON arrays
+ out-of-the-box. An array of size 1 is considered equal to its sole element.
+ Automatic unwrapping is not performed only when:
+
+
+ The path expression contains type() or
+ size() methods that return the type
+ and the number of elements in the array, respectively.
+
+
+
+ The queried JSON data contain nested arrays. In this case, only
+ the outermost array is unwrapped, while all the inner arrays
+ remain unchanged. Thus, implicit unwrapping can only go one
+ level down within each path evaluation step.
+
+
+
+
+
+ For example, when querying the GPS data listed above, you can
+ abstract from the fact that it stores an array of segments
+ when using the lax mode:
+'lax $.track.segments.location'
+
+
+
+ In the strict mode, the specified path must exactly match the structure of
+ the queried JSON document to return an SQL/JSON item, so using this
+ path expression will cause an error. To get the same result as in
+ the lax mode, you have to explicitly unwrap the
+ segments array:
+'strict $.track.segments[*].location'
+
+
+
+
+
+
+
Regular Expressions
+
+
+ in SQL/JSON
+
+
+ SQL/JSON path expressions allow matching text to a regular expression
+ with the like_regex filter. For example, the
+ following SQL/JSON path query would case-insensitively match all
+ strings in an array that start with an English vowel:
+'$[*] ? (@ like_regex "^[aeiou]" flag "i")'
+
+
+
+ The optional flag string may include one or more of
+ the characters
+ i for case-insensitive match,
+ m to allow ^
+ and $ to match at newlines,
+ s to allow . to match a newline,
+ and q to quote the whole pattern (reducing the
+ behavior to a simple substring match).
+
+
+ The SQL/JSON standard borrows its definition for regular expressions
+ from the LIKE_REGEX operator, which in turn uses the
+ XQuery standard. PostgreSQL does not currently support the
+ LIKE_REGEX operator. Therefore,
+ the like_regex filter is implemented using the
+ POSIX regular expression engine described in
+ . This leads to various minor
+ discrepancies from standard SQL/JSON behavior, which are cataloged in
+ .
+ Note, however, that the flag-letter incompatibilities described there
+ do not apply to SQL/JSON, as it translates the XQuery flag letters to
+ match what the POSIX engine expects.
+
+
+ Keep in mind that the pattern argument of like_regex
+ is a JSON path string literal, written according to the rules given in
+ . This means in particular that any
+ backslashes you want to use in the regular expression must be doubled.
+ For example, to match strings that contain only digits:
+'$ ? (@ like_regex "^\\d+$")'
+
+
+
+
+
+
+
SQL/JSON Path Operators and Methods
+
+ shows the operators and
+ methods available in
jsonpath.
+ linkend="functions-sqljson-filter-ex-table"/> shows the available filter
+ expression elements.
+
+
+
<type>jsonpath</type> Operators and Methods
+
+
+ |
+ Operator/Method
+ Description
+ Example JSON
+ Example Query
+ Result
+
+
+
+ |
+ + (unary)
+ Plus operator that iterates over the SQL/JSON sequence
+ {"x": [2.85, -14.7, -9.4]}
+ + $.x.floor()
+ 2, -15, -10
+
+ |
+ - (unary)
+ Minus operator that iterates over the SQL/JSON sequence
+ {"x": [2.85, -14.7, -9.4]}
+ - $.x.floor()
+ -2, 15, 10
+
+ |
+ + (binary)
+ Addition
+ [2]
+ 2 + $[0]
+ 4
+
+ |
+ - (binary)
+ Subtraction
+ [2]
+ 4 - $[0]
+ 2
+
+ |
+ *
+ Multiplication
+ [4]
+ 2 * $[0]
+ 8
+
+ |
+ /
+ Division
+ [8]
+ $[0] / 2
+ 4
+
+ |
+ %
+ Modulus
+ [32]
+ $[0] % 10
+ 2
+
+ |
+ type()
+ Type of the SQL/JSON item
+ [1, "2", {}]
+ $[*].type()
+ "number", "string", "object"
+
+ |
+ size()
+ Size of the SQL/JSON item
+ {"m": [11, 15]}
+ $.m.size()
+ 2
+
+ |
+ double()
+ Approximate floating-point number converted from an SQL/JSON number or a string
+ {"len": "1.9"}
+ $.len.double() * 2
+ 3.8
+
+ |
+ ceiling()
+ Nearest integer greater than or equal to the SQL/JSON number
+ {"h": 1.3}
+ $.h.ceiling()
+ 2
+
+ |
+ floor()
+ Nearest integer less than or equal to the SQL/JSON number
+ {"h": 1.3}
+ $.h.floor()
+ 1
+
+ |
+ abs()
+ Absolute value of the SQL/JSON number
+ {"z": -0.3}
+ $.z.abs()
+ 0.3
+
+ |
+ keyvalue()
+
+ Sequence of object's key-value pairs represented as array of items
+ containing three fields ("key",
+ "value", and "id").
+ "id" is a unique identifier of the object
+ key-value pair belongs to.
+
+ {"x": "20", "y": 32}
+ $.keyvalue()
+ {"key": "x", "value": "20", "id": 0}, {"key": "y", "value": 32, "id": 0}
+
+
+
+
+
+
<type>jsonpath</type> Filter Expression Elements
+
+
+ |
+ Value/Predicate
+ Description
+ Example JSON
+ Example Query
+ Result
+
+
+
+ |
+ ==
+ Equality operator
+ [1, 2, 1, 3]
+ $[*] ? (@ == 1)
+ 1, 1
+
+ |
+ !=
+ Non-equality operator
+ [1, 2, 1, 3]
+ $[*] ? (@ != 1)
+ 2, 3
+
+ |
+ <>
+ Non-equality operator (same as !=)
+ [1, 2, 1, 3]
+ $[*] ? (@ <> 1)
+ 2, 3
+
+ |
+ <
+ Less-than operator
+ [1, 2, 3]
+ $[*] ? (@ < 2)
+ 1
+
+ |
+ <=
+ Less-than-or-equal-to operator
+ [1, 2, 3]
+ $[*] ? (@ <= 2)
+ 1, 2
+
+ |
+ >
+ Greater-than operator
+ [1, 2, 3]
+ $[*] ? (@ > 2)
+ 3
+
+ |
+ >=
+ Greater-than-or-equal-to operator
+ [1, 2, 3]
+ $[*] ? (@ >= 2)
+ 2, 3
+
+ |
+ true
+ Value used to perform comparison with JSON true literal
+ [{"name": "John", "parent": false},
+ {"name": "Chris", "parent": true}]
+ $[*] ? (@.parent == true)
+ {"name": "Chris", "parent": true}
+
+ |
+ false
+ Value used to perform comparison with JSON false literal
+ [{"name": "John", "parent": false},
+ {"name": "Chris", "parent": true}]
+ $[*] ? (@.parent == false)
+ {"name": "John", "parent": false}
+
+ |
+ null
+ Value used to perform comparison with JSON null value
+ [{"name": "Mary", "job": null},
+ {"name": "Michael", "job": "driver"}]
+ $[*] ? (@.job == null) .name
+ "Mary"
+
+ |
+ &&
+ Boolean AND
+ [1, 3, 7]
+ $[*] ? (@ > 1 && @ < 5)
+ 3
+
+ |
+ ||
+ Boolean OR
+ [1, 3, 7]
+ $[*] ? (@ < 1 || @ > 5)
+ 7
+
+ |
+ !
+ Boolean NOT
+ [1, 3, 7]
+ $[*] ? (!(@ < 5))
+ 7
+
+ |
+ like_regex
+
+ Tests whether the first operand matches the regular expression
+ given by the second operand, optionally with modifications
+ described by a string of flag characters (see
+ )
+
+ ["abc", "abd", "aBdC", "abdacb", "babc"]
+ $[*] ? (@ like_regex "^ab.*c" flag "i")
+ "abc", "aBdC", "abdacb"
+
+ |
+ starts with
+ Tests whether the second operand is an initial substring of the first operand
+ ["John Smith", "Mary Stone", "Bob Johnson"]
+ $[*] ? (@ starts with "John")
+ "John Smith"
+
+ |
+ exists
+ Tests whether a path expression matches at least one SQL/JSON item
+ {"x": [1, 2], "y": [2, 4]}
+ strict $.* ? (exists (@ ? (@[*] > 2)))
+ 2, 4
+
+ |
+ is unknown
+ Tests whether a Boolean condition is unknown
+ [-1, 2, 7, "infinity"]
+ $[*] ? ((@ > 0) is unknown)
+ "infinity"
+
+
+
+
+
+
projects / postgresql.git / commitdiff