Présentation des types de données JSON de Redis

ElastiCache for Redis prend en charge un certain nombre de commandes Redis pour travailler avec le type de données JSON. Vous trouverez ci-dessous un aperçu du type de données JSON et une liste détaillée des commandes Redis prises en charge.

Terminologie

Terme	Description
Document JSON	Fait référence à la valeur d'une clé JSON Redis.
Valeur JSON	Fait référence à un sous-ensemble d'un document JSON, y compris la racine qui représente le document entier. Une valeur peut être un conteneur ou une entrée dans un conteneur.
Élément JSON	Équivalent de la valeur JSON.

Norme JSON prise en charge

Le format JSON est conforme à la norme d'échange de données JSON RFC 7159 et ECMA-404. L'Unicode UTF-8 dans le texte JSON est pris en charge.

Élément racine

L'élément racine peut être de n'importe quel type de données JSON. Notez que dans la précédente RFC 4627, seuls les objets ou les tableaux étaient autorisés comme valeurs racine. Depuis la mise à jour vers la RFC 7159, la racine d'un document JSON peut être de n'importe quel type de données JSON.

Limite de taille du document

Les documents JSON sont stockés en interne dans un format optimisé pour un accès et une modification rapides. Ce format entraîne généralement une consommation de mémoire un peu plus importante que la représentation sérialisée équivalente du même document.

La consommation de mémoire par un seul document JSON est limitée à 64 Mo, ce qui correspond à la taille de la structure de données en mémoire, et non de la chaîne JSON. Vous pouvez vérifier la quantité de mémoire consommée par un document JSON en utilisant la commande JSON.DEBUG MEMORY.

Listes ACL JSON

• Similaire aux catégories existantes par type de données (@string, @hash, etc.), une nouvelle catégorie @json est ajoutée pour simplifier la gestion de l'accès aux commandes et aux données JSON. Aucune autre commande Redis existante n'est membre de la catégorie @json. Toutes les commandes JSON appliquent les restrictions et autorisations des keyspaces ou des commandes.

• Il existe cinq catégories de listes ACL Redis existantes qui sont mises à jour pour inclure les nouvelles commandes JSON : @read, @write, @fast, @slow et @admin. Le tableau suivant indique le mappage des commandes JSON aux catégories appropriées.

ACL
Commande JSON	@read	@write	@fast	@slow	@admin
JSON.ARRAPPEND		y	y
JSON.ARRINDEX	y		y
JSON.ARRINSERT		y	y
JSON.ARRLEN	y		y
JSON.ARRPOP		y	y
JSON.ARRTRIM		y	y
JSON.CLEAR		y	y
JSON.DEBUG	y			y	y
JSON.DEL		y	y
JSON.FORGET		y	y
JSON.GET	y		y
JSON.MGET	y		y
JSON.NUMINCRBY		y	y
JSON.NUMMULTBY		y	y
JSON.OBJKEYS	y		y
JSON.OBJLEN	y		y
JSON.RESP	y		y
JSON.SET		y		y
JSON.STRAPPEND		y	y
JSON.STRLEN	y		y
JSON.STRLEN	y		y
JSON.TOGGLE		y	y
JSON.TYPE	y		y
JSON.NUMINCRBY		y	y

Limite de profondeur d'imbrication

Lorsqu'un objet ou un tableau JSON possède un élément qui est lui-même un autre objet ou tableau JSON, cet objet ou tableau intérieur est dit « imbriqué » dans l'objet ou le tableau extérieur. La limite maximale de la profondeur d'imbrication est de 128. Toute tentative de création d'un document contenant une profondeur d'imbrication supérieure à 128 sera rejetée avec une erreur.

Syntaxe de commande

La plupart des commandes requièrent un nom de clé Redis comme premier argument. Certaines commandes ont également un argument path. L'argument path correspond par défaut à la racine s'il est optionnel et non fourni.

Notation :

• Les arguments obligatoires sont entourés de chevrons. Par exemple : <key>

• Les arguments facultatifs sont entourés de crochets. Par exemple : [path]

• Les arguments facultatifs supplémentaires sont indiqués par une ellipse (« … »). Par exemple : [json ...]

Syntaxe de chemin

Le JSON de Redis prend en charge deux types de syntaxe de chemin :

• Syntaxe améliorée : suit la syntaxe JSONPath décrite par Goessner, comme indiqué dans la table suivante. Nous avons réorganisé et modifié les descriptions dans le tableau pour plus de clarté.

• Syntaxe restreinte : possède des capacités de requête limitées.

Note

Les résultats de certaines commandes sont sensibles au type de syntaxe de chemin utilisé.

Si un chemin de requête commence par « $ », il utilise la syntaxe améliorée. Sinon, la syntaxe restreinte est utilisée.

Syntaxe améliorée

Symbole/Expression	Description
$	L'élément racine.
. ou []	Opérateur enfant.
..	Descente récursive.
*	Caractère générique. Tous les éléments d'un objet ou d'un tableau.
[]	Opérateur d'indice de tableau. L'index est basé sur 0.
[,]	Opérateur d'union.
[start:end:step]	Opérateur de découpage de tableau.
?()	Applique une expression de filtre (script) au tableau ou à l'objet en cours.
()	Expression de filtre.
@	Utilisé dans les expressions de filtre qui font référence au nœud en cours de traitement.
==	Égal à, utilisé dans les expressions de filtre.
!=	Pas égal à, utilisé dans les expressions de filtre.
>	Supérieur à, utilisé dans les expressions de filtre.
>=	Supérieur ou égal à, utilisé dans les expressions de filtre.
<	Inférieur à, utilisé dans les expressions de filtre.
<=	Inférieur ou égal à, utilisé dans les expressions de filtre.
&&	AND logique, utilisé pour combiner plusieurs expressions de filtre.
||	OR logique, utilisé pour combiner plusieurs expressions de filtre.

Exemples

Les exemples suivants sont basés sur l'exemple de données XML de Goessner, que nous avons modifié en ajoutant des champs supplémentaires.

{ "store": {
    "book": [ 
      { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95,
        "in-stock": true,
        "sold": true
      },
      { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99,
        "in-stock": false,
        "sold": true
      },
      { "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99,
        "in-stock": true,
        "sold": false
      },
      { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99,
        "in-stock": false,
        "sold": false
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95,
      "in-stock": true,
      "sold": false
    }
  }
}

Chemin	Description
$.store.book[*].author	Les auteurs de tous les livres de la boutique.
$..author	Tous les auteurs.
$.store.*	Tous les membres de la boutique.
$["store"].*	Tous les membres de la boutique.
$.store..price	Le prix de tout ce qui se trouve dans la boutique.
$..*	Tous les membres récursifs de la structure JSON.
$..book[*]	Tous les livres.
$..book[0]	Le premier livre.
$..book[-1]	Le dernier livre.
$..book[0:2]	Les deux premiers livres.
$..book[0,1]	Les deux premiers livres.
$..book[0:4]	Les livres d'index 0 à 3 (l'index final n'est pas inclusif).
$..book[0:4:2]	Les livres à l'index 0, 2.
$..book[?(@.isbn)]	Tous les livres ayant un numéro ISBN.
$..book[?(@.price<10)]	Tous les livres dont le prix est inférieur à 10 USD.
'$..book[?(@.price < 10)]'	Tous les livres dont le prix est inférieur à 10 USD. (Le chemin doit être entre guillemets s'il contient des espaces blancs).
'$..book[?(@["price"] < 10)]'	Tous les livres dont le prix est inférieur à 10 USD.
'$..book[?(@.["price"] < 10)]'	Tous les livres dont le prix est inférieur à 10 USD.
$.. book [? (@.prix>=10&&@.prix<=100)]	Tous les livres dans la fourchette de prix comprise entre 10 et 100 USD.
'$..book[?(@.price>=10 && @.price<=100)]'	Tous les livres dans la fourchette de prix comprise entre 10 et 100 USD. (Le chemin doit être entre guillemets s'il contient des espaces blancs).
$..book[?(@.sold==true||@.in-stock==false)]	Tous les livres vendus ou en rupture de stock.
'$..book[?(@.sold == true || @.in-stock == false)]'	Tous les livres vendus ou en rupture de stock. (Le chemin doit être entre guillemets s'il contient des espaces blancs).
'$.store.book[?(@.["category"] == "fiction")]'	Tous les livres dans la catégorie fiction.
'$.store.book[?(@.["category"] != "fiction")]'	Tous les livres dans la catégorie non-fiction.

Exemples d'expressions de filtre supplémentaires :

127.0.0.1:6379> JSON.SET k1 . '{"books": [{"price":5,"sold":true,"in-stock":true,"title":"foo"}, {"price":15,"sold":false,"title":"abc"}]}'
OK
127.0.0.1:6379> JSON.GET k1 $.books[?(@.price>1&&@.price<20&&@.in-stock)]
"[{\"price\":5,\"sold\":true,\"in-stock\":true,\"title\":\"foo\"}]"
127.0.0.1:6379> JSON.GET k1 '$.books[?(@.price>1 && @.price<20 && @.in-stock)]'
"[{\"price\":5,\"sold\":true,\"in-stock\":true,\"title\":\"foo\"}]"
127.0.0.1:6379> JSON.GET k1 '$.books[?((@.price>1 && @.price<20) && (@.sold==false))]'
"[{\"price\":15,\"sold\":false,\"title\":\"abc\"}]"
127.0.0.1:6379> JSON.GET k1 '$.books[?(@.title == "abc")]'
[{"price":15,"sold":false,"title":"abc"}]

127.0.0.1:6379> JSON.SET k2 . '[1,2,3,4,5]'
127.0.0.1:6379> JSON.GET k2 $.*.[?(@>2)]
"[3,4,5]"
127.0.0.1:6379> JSON.GET k2 '$.*.[?(@ > 2)]'
"[3,4,5]"

127.0.0.1:6379> JSON.SET k3 . '[true,false,true,false,null,1,2,3,4]'
OK
127.0.0.1:6379> JSON.GET k3 $.*.[?(@==true)]
"[true,true]"
127.0.0.1:6379> JSON.GET k3 '$.*.[?(@ == true)]'
"[true,true]"
127.0.0.1:6379> JSON.GET k3 $.*.[?(@>1)]
"[2,3,4]"
127.0.0.1:6379> JSON.GET k3 '$.*.[?(@ > 1)]'
"[2,3,4]"

Syntaxe restreinte

Symbole/Expression	Description
. ou []	Opérateur enfant.
[]	Opérateur d'indice de tableau. L'index est basé sur 0.

Exemples

Chemin	Description
.store.book[0].author	L'auteur du premier livre.
.store.book[-1].author	L'auteur du dernier livre.
.address.city	Le nom de la ville.
["store"]["book"][0]["title"]	Le titre du premier livre.
["store"]["book"][-1]["title"]	Le titre du dernier livre.

Note

Tout le contenu de Goessner cité dans cette documentation est soumis à la licence Creative Commons.

Préfixes d'erreur courantes

Chaque message d'erreur possède un préfixe. Voici une liste des préfixes d'erreur courants.

Préfixe	Description
ERR	Une erreur générale.
LIMIT	Une erreur qui se produit lorsque la limite de taille est dépassée. Par exemple, la limite de taille du document ou la limite de profondeur d'imbrication a été dépassée.
NONEXISTENT	Une clé ou un chemin n'existe pas.
OUTOFBOUNDARIES	L'index du tableau est hors limites.
SYNTAXERR	Erreur de syntaxe.
WRONGTYPE	Mauvais type de valeur.

Métriques liées à JSON

Les métriques d'informations JSON suivantes sont fournies :

Infos	Description
json_total_memory_bytes	Mémoire totale allouée aux objets JSON.
json_num_documents	Nombre total de documents dans Redis.

Pour interroger les métriques de base, exécutez la commande Redis suivante :

info json_core_metrics

Comment ElastiCache for Redis interagit avec JSON

La section suivante décrit comment ElastiCache for Redis interagit avec le type de données JSON.

Priorité des opérateurs

Lors de l'évaluation d'expressions conditionnelles pour le filtrage, les && sont prioritaires, puis les || sont évalués, comme c'est le cas dans la plupart des langages. Les opérations à l'intérieur des parenthèses sont exécutées en premier.

Comportement de la limite maximale d'imbrication des chemins

La limite maximale d'imbrication des chemins dans ElastiCache for Redis est de 128. Ainsi, une valeur comme $.a.b.c.d... ne peut atteindre que 128 niveaux.

Traitement des valeurs numériques

JSON n'a pas de types de données séparés pour les nombres entiers et les nombres à virgule flottante. Ils sont tous appelés des nombres.

Représentations numériques :

Lorsqu'un nombre JSON est reçu en entrée, il est converti en l'une des deux représentations binaires internes : un entier signé de 64 bits ou une virgule flottante IEEE à double précision de 64 bits. La chaîne de caractères d'origine et toute sa mise en forme ne sont pas retenues. Ainsi, lorsqu'un nombre est généré en sortie dans le cadre d'une réponse JSON, il est converti de la représentation binaire interne en une chaîne imprimable qui utilise des règles de formatage génériques. Ces règles peuvent entraîner la génération d'une chaîne différente de celle qui a été reçue.

Commandes arithmétiques NUMINCRBY et NUMMULTBY :

• Si les deux nombres sont des entiers et que le résultat est hors de la plage de int64, il devient automatiquement un nombre à virgule flottante IEEE à double précision de 64 bits.

• Si au moins un des nombres est un nombre à virgule flottante, le résultat est un nombre à virgule flottante IEEE à double précision de 64 bits.

• Si le résultat dépasse la plage du double IEEE de 64 bits, la commande renvoie une erreur OVERFLOW.

Pour une liste détaillée des commandes disponibles, consultez Commandes JSON Redis prises en charge.

Filtrage direct de tableau

ElastiCache for Redis filtre directement les objets de type tableau.

Pour des données comme [0,1,2,3,4,5,6] et une requête de chemin telle que $[?(@<4)], ou des données comme {"my_key":[0,1,2,3,4,5,6]} et une requête de chemin telle que $.my_key[?(@<4)], ElastiCache for Redis renverrait [1,2,3] dans les deux cas.

Comportement d'indexation de tableau

ElastiCache for Redis autorise les index positifs et négatifs pour les tableaux. Pour un tableau de longueur cinq, 0 interrogerait le premier élément, 1 le deuxième, et ainsi de suite. Les nombres négatifs commencent à la fin du tableau, donc -1 interrogerait le cinquième élément, -2 le quatrième élément, et ainsi de suite.

Afin d'assurer un comportement prévisible pour les clients, ElastiCache for Redis n'arrondit pas les index de tableau vers une valeur inférieure ou supérieure. Ainsi, si vous avez un tableau d'une longueur de 5, l'appel de l'index 5 ou supérieur, ou -6 ou inférieur, ne produira pas de résultat.

Évaluation stricte de la syntaxe

MemoryDB n'autorise pas les chemins JSON dont la syntaxe est invalide, même si un sous-ensemble du chemin contient un chemin valide. Ceci afin de maintenir un comportement correct pour nos clients.