Operadores de tipos de datos JSON

Obtener información sobre los operadores que se pueden utilizar con los tipos de datos json y jsonb.

Existen variantes paralelas de los operadores para los tipos json y jsonb. Los operadores de extracción de campo/elemento/ruta devuelven el mismo tipo que su entrada izquierda (ya sea ' json o ' jsonb), excepto aquellos operadores especificados como que devuelven ' text, que coaccionan el valor a texto. Los operadores de extracción de campo/elemento/ruta devuelven NULL, en lugar de fallar, si la entrada JSON no tiene la estructura adecuada para coincidir con la solicitud; por ejemplo, si no existe tal elemento. Los operadores de extracción de campo/elemento/vía de acceso que aceptan los subíndices de matriz JSON de enteros admiten todos los subíndices negativos del final de las matrices.

Nota: Los operadores ' #> y ' #>> ' utilizan matrices JSONB como operando derecho.

Operadores disponibles para json y jsonb

->

Tipo de operando derecho: int

Obtener elemento de matriz JSON (indexado desde cero, los enteros negativos cuentan desde el final).

Ejemplos:

SELECT '["football", "volleyball", "soccer"]'::JSONB -> 0;
  ?COLUMN?  
------------
 "football"
(1 row)

SELECT '["football", "volleyball", "soccer"]'::JSONB -> -1;
 ?COLUMN? 
----------
 "soccer"
(1 row)

->

Tipo de operando derecho: text

Obtener el objeto JSON archivado por clave.

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28}'::JSONB -> 'name';
  ?COLUMN?   
-------------
 "Joe Smith"
(1 row)

SELECT '{"name": "Joe Smith", "age": 28}'::JSONB -> 'age';
 ?COLUMN? 
----------
 28
(1 row)

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football", "volleyball", "soccer"]}'::JSONB -> 'sports' -> 0;
  ?COLUMN?  
------------
 "football"
(1 row)

->>

Tipo de operando derecho: int

Obtener elemento de matriz JSON como ' nvarchar.

Ejemplos:

SELECT '["football", "volleyball", "soccer"]'::JSONB ->> 0;
 ?COLUMN? 
----------
 football
(1 row)

SELECT '["football", "volleyball", "soccer"]'::JSONB ->> -1;
 ?COLUMN? 
----------
 soccer
(1 row)

->>

Tipo de operando derecho: text

Obtener campo objeto JSON como ' nvarchar.

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28}'::JSONB ->> 'name';
 ?COLUMN?  
-----------
 Joe Smith
(1 row)

SELECT '{"name": "Joe Smith", "age": 28}'::JSONB ->> 'age';
 ?COLUMN? 
----------
 28
(1 row)

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football", "volleyball", "soccer"]}'::JSONB -> 'sports' ->> 0;
 ?COLUMN? 
----------
 football
(1 row)

#>

Tipo de operando derecho: matrices JSONB

Función: json_extract_path, jsonb_extract_path

Obtener objeto JSON en la vía de acceso especificada.

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football", "volleyball", "soccer"]}'::JSONB #> '["sports", 0]';
  ?COLUMN?  
------------
 "football"
(1 row)

#>>

Tipo de operando derecho: matrices JSONB

Nombre de función: json_extract_path_text, jsonb_extract_path_text

Obtener objeto JSON en la ruta especificada como ' nvarchar.

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football", "volleyball", "soccer"]}'::JSONB #>> '["sports", 0]';
 ?COLUMN? 
----------
 football
(1 row)

Algunos operadores adicionales también existen sólo para jsonb, tal como se describe en la siguiente sección de este documento.

Operadores disponibles para jsonb

Nota: Algunos controladores NPS no admiten operadores con un signo de interrogación. En su lugar, hay que usar la función. Además, los operadores ?| y ?& utilizan matrices JSONB como el tipo de operando derecho.

?

Tipo de operando derecho: text

Nombre de función: jsonb_exists

¿Existe la serie como una clave de nivel superior dentro del valor JSON?

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ? 'age';
 ?COLUMN? 
----------
 t
(1 row)

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ? 'address';
 ?COLUMN? 
----------
 f
(1 row)

SELECT '{"n":null,"a":1,"b":[1,2],"c":{"1":2},"d":{"1":[2,3]},"一":"二"}'::jsonb ? 'e';
 ?COLUMN? 
----------
 f
(1 row)

SELECT jsonb_exists('{"一":"null", "二":"qq"}', '三');
 JSONB_EXISTS 
--------------
 f
(1 row)

Consejo: Los signos de interrogación (?) se utilizan como marcadores de posición de parámetros en los controladores ODBC y OLEDB. Debe utilizar ' jsonb_exists() ' para comprobar la existencia de una clave:

Ejemplos:

SELECT jsonb_exists('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', 'age');
 JSONB_EXISTS 
--------------
 t
(1 row)

SELECT jsonb_exists('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', 'address');
 JSONB_EXISTS 
--------------
 f
(1 row)

?|

Tipo de operando derecho: matrices JSONB

Función: jsonb_exists_any

Véase también Funciones de sobrecarga.

¿Existe alguna de estas series de matriz como claves de nivel superior?

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ?| '["age", "address"]';
 ?COLUMN? 
----------
 t
(1 row)

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ?| '["mobile", "address"]';
 ?COLUMN? 
----------
 f
(1 row)

Consejo: Los signos de interrogación (?) se utilizan como marcadores de posición de parámetros en los controladores ODBC y OLEDB. Debe utilizar ' jsonb_exists_any() ' para comprobar la existencia de una clave:

Ejemplos:

SELECT jsonb_exists_any('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', '["age", "address"]');
 JSONB_EXISTS_ANY 
------------------
 t
(1 row)

SELECT jsonb_exists_any('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', '["mobile", "address"]');
 JSONB_EXISTS_ANY 
------------------
 f
(1 row)

?&

Tipo de operando derecho: matrices JSONB

Función: jsonb_exists_all

Véase también Funciones de sobrecarga.

¿Existen todas estas series de matriz como claves de nivel superior?

Ejemplos:

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ?& '["age", "address"]';
 ?COLUMN? 
----------
 f
(1 row)

SELECT '{"name": "Joe Smith", "age": 28, "sports": ["football"]}'::JSONB ?& '["age", "sports"]';
 ?COLUMN? 
----------
 t
(1 row)

Consejo: Los signos de interrogación (?) se utilizan como marcadores de posición de parámetros en los controladores ODBC y OLEDB. Debe utilizar ' jsonb_exists_all() ' para comprobar la existencia de una clave:

Ejemplos:

SELECT jsonb_exists_all('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', '["age", "address"]');
 JSONB_EXISTS_ALL 
------------------
 f
(1 row)

SELECT jsonb_exists_all('{"name": "Joe Smith", "age": 28, "sports": ["football"]}', '["age", "sports"]');
 JSONB_EXISTS_ALL 
------------------
 t
(1 row)

@?

Tipo de operando derecho: jsonpath

Función: jsonb_path_exists()

Devuelve true si jsonpath devuelve al menos un elemento para el valor jsonb especificado.

Ejemplos:

SELECT '2'                @? '$ > 1'::JSONPATH;
 ?COLUMN? 
----------
 t
(1 row)

select jsonb '{"a": 12}' @? '1';
 ?COLUMN? 
----------
 t
(1 row)

select jsonb '["1",2,0,3]' @? '-$[*]';
 ?COLUMN? 
----------
 t
(1 row)

@@

Tipo de operando derecho: jsonpath

Función: jsonb_path_match

Devuelve el resultado de la comprobación del predicado de ruta JSON para el valor JSON especificado. Sólo se tiene en cuenta el primer elemento del resultado. Si el resultado no es booleano, se devuelve null

Ejemplos:

SELECT '2'::NCHAR(100)    @@ '$ > 1'::JSONPATH;
 ?COLUMN? 
----------
 t
(1 row)

SELECT '2'::JSONB @@ '$ > 1'::JSONPATH;
 ?COLUMN? 
----------
 t
(1 row)

SELECT '2'::JSONB @@ '1'::INT;
ERROR:  Cannot convert 'INT4' to 'JSONB'
SELECT '2'::JSONB @@ '1'::JSONB;
ERROR:  Unable to identify an operator '@@' for types 'JSONB' and 'JSONB'
	You will have to retype this query using an explicit cast
SELECT '2'::JSONB @@ 'true'::BOOL ;
ERROR:  Cannot convert 'BOOL' to 'JSONB'

El @? los operadores y @@ suprimen:

Error de falta de campo de objeto o elemento de matriz.
Tipo de elemento JSON inesperado y errores numéricos.

Esto puede ser útil si estás buscando en colecciones de documentos JSON de estructura variable.

Contención y existencia

Contención

Probar la contención es una función importante del tipo de datos jsonb. El tipo json no tiene un conjunto paralelo de dichos servicios. La contención prueba si un documento jsonb tiene otro documento contenido en él.

El objeto contenido debe coincidir con el objeto que lo contiene en cuanto a estructura y contenido de datos, posiblemente después de descartar algunos elementos de matriz no coincidentes o pares de clave/valor de objeto del objeto contenedor. El orden de los elementos de matriz no es significativo cuando se lleva a cabo una coincidencia de contención y los elementos de matriz duplicados se consideran de forma efectiva sólo una vez.

Ejemplos:

Los valores simples escalares/primitivos sólo contienen el valor idéntico:
```
SELECT '"foo"'::jsonb @> '"foo"'::jsonb;
?COLUMN? 
----------
 t
(1 row)
```

La matriz del lado derecho está contenida en la de la izquierda:

SELECT '[1, 2, 3]'::jsonb @> '[1, 3]'::jsonb;
?COLUMN? 
----------
 t
(1 row)

El orden de los elementos de matriz no es significativo, por lo que lo siguiente también se cumple:
```
SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb;
?COLUMN? 
----------
 t
(1 row)
```

Los elementos de matriz duplicados no importan:

SELECT '[1, 2, 3]'::jsonb @> '[1, 2, 2]'::jsonb;
?COLUMN? 
----------
 t
(1 row)

El objeto con un solo par en el lado derecho está contenido dentro del objeto en el lado izquierdo:

SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @> '{"version": 9.4}'::jsonb;
?COLUMN? 
----------
 t
(1 row)

La matriz del lado derecho no se considera contenida en la matriz de la izquierda, aunque haya una matriz similar anidada en ella:

SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb;
?COLUMN? 
----------
 f
(1 row)

Pero con una capa de anidación, está contenido:

SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb;
?COLUMN? 
----------
 t
(1 row)

Del mismo modo, aquí no se informa de la contención:

SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb;
?COLUMN? 
----------
 f
(1 row)

Una clave de nivel superior y un objeto vacío están contenidos:

SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"foo": {}}'::jsonb;
?COLUMN? 
----------
 t
(1 row)

Una matriz puede contener un valor primitivo, lo cual es una excepción al principio de que las estructuras deben coincidir.

Ejemplo:

SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb;
?COLUMN? 
----------
 t
(1 row)

Esta excepción no es recíproca; aquí se informa de la no contención:

SELECT '"bar"'::jsonb @> '["bar"]'::jsonb;
?COLUMN? 
----------
 f
(1 row)

Existencia

jsonb también tiene un operador de existencia. Prueba si una serie (dada como un valor text) aparece como una clave de objeto o un elemento de matriz en el nivel superior del valor jsonb. Los objetos JSON son más adecuados que las matrices para probar la contención o existencia cuando hay muchas claves o elementos implicados. A diferencia de las matrices, están optimizadas internamente para la búsqueda, y no necesitan ser buscadas linealmente.

Ejemplos:

La serie existe como elemento de matriz:

SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar';
?COLUMN? 
----------
 t
(1 row)

La serie existe como clave de objeto:

SELECT '{"foo": "bar"}'::jsonb ? 'foo';
?COLUMN? 
----------
 t
(1 row)

Los valores de objeto no se tienen en cuenta:

SELECT '{"foo": "bar"}'::jsonb ? 'bar';
?COLUMN? 
----------
 f
(1 row)

Al igual que con la contención, la existencia debe coincidir en el nivel superior:
```
SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar';
?COLUMN? 
----------
 f
(1 row)
```
Se considera que existe una serie si coincide con una serie JSON primitiva:
```
SELECT '"foo"'::jsonb ? 'foo';
?COLUMN? 
----------
 t
(1 row)
```