Sobre o JSON

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O JavaScript Object Notation (JSON) oferece uma maneira eficiente de armazenar e manipular dados estruturados na Memorystore para Valkey. O uso de JSON oferece os seguintes benefícios:

• Ter recursos rápidos de pesquisa e filtragem
• Realizar atualizações in-loco em dados JSON sem precisar substituir documentos inteiros
• Consultar, modificar e gerenciar estruturas de dados complexas de maneira eficiente

Se seus aplicativos exigem armazenamento de dados dinâmico e flexível, o JSON é ideal para você. Além disso, ao usar JSON, é possível codificar conjuntos de dados complexos em instâncias do Memorystore para Valkey sem usar esquemas. Você pode armazenar, acessar e atualizar dados nas instâncias sem precisar gerenciar código personalizado para serializar e desserializar os dados.

Um documento JSON é um formato de texto legível por humanos para armazenar e transportar dados. Esse formato consiste em pares de chave-valor e tipos de dados estruturados. O formato JSON permite recuperar e atualizar partes de um documento JSON sem precisar manipular o objeto inteiro. Isso pode melhorar sua performance e reduzir seus custos. Além disso, o formato JSON está em conformidade com a RFC 7159, o padrão de troca de dados JSON ECMA-404 e o Unicode UTF-8 em texto JSON.

Disponibilidade

Se você criar uma instância do Memorystore para Valkey, versão 8.0 e mais recente, a versão 1.0 do tipo de dados JSON e comandos associados estará disponível automaticamente. Esse tipo de dados é compatível com a API da versão 2 do módulo JSON. Além disso, de acordo com a RFC 7159, o elemento raiz de um documento JSON pode ser de qualquer tipo de dados JSON.

Propriedades JSON

O JSON tem as seguintes propriedades:

• Tamanho máximo do documento: para evitar possíveis problemas de falta de memória devido a inserções maliciosas ou ilimitadas, é possível configurar um limite no tamanho das chaves JSON individuais.

  Por padrão, o valor dessa propriedade é definido como 0, o que significa que não há limite para o tamanho do documento JSON. Para definir esse limite, use o comando CONFIG SET json.max-document-size VALUE, em que VALUE é o tamanho máximo do documento. Por exemplo, se você especificar 4123456, o tamanho máximo do documento será de 4.123.456 bytes (4 MB).

  Para saber quanta memória é usada por um valor JSON armazenado em uma chave especificada, use os comandos JSON.DEBUG MEMORY KEY ou MEMORY USAGE KEY. Para esses comandos, KEY é o nome da chave em que o valor JSON é armazenado.

• Profundidade máxima: o nível máximo de aninhamento para objetos e matrizes JSON. Para mais informações, consulte Limite máximo de profundidade de aninhamento.

Tamanho do documento JSON

Como um documento JSON é armazenado internamente em um formato otimizado para acesso e modificação rápidos, esse tipo de documento pode consumir muita memória. Para verificar quanta memória um documento JSON consome, use o comando JSON.DEBUG MEMORY KEY, em que KEY é o nome da chave que contém o documento.

Categorias JSON

Para gerenciar o acesso a comandos JSON e dados, use a categoria @json. Além dessa categoria, as seguintes usam comandos JSON: @read, @write, @fast, @slow e @admin.

A tabela a seguir indica se é possível mapear comandos JSON para as categorias @read, @write, @fast, @slow, @admin e @json.

Comando JSON	@json	@read	@write	@fast	@slow	@admin
JSON.ARRAPPEND	S	N	S	S	N	N
JSON.ARRINDEX	S	S	N	S	N	N
JSON.ARRINSERT	S	N	S	S	N	N
JSON.ARRLEN	S	S	N	S	N	N
JSON.ARRPOP	S	N	S	S	N	N
JSON.ARRTRIM	S	N	S	S	N	N
JSON.CLEAR	S	N	S	S	N	N
JSON.DEBUG	S	S	N	N	S	Y
JSON.DEL	S	N	S	S	N	N
JSON.FORGET	S	N	S	S	N	N
JSON.GET	S	S	N	S	N	N
JSON.MGET	S	S	N	S	N	N
JSON.MSET	S	N	S	N	S	N
JSON.NUMINCRBY	S	N	S	S	N	N
JSON.NUMMULTBY	S	N	S	S	N	N
JSON.OBJKEYS	S	S	N	S	N	N
JSON.OBJLEN	S	S	N	S	N	N
JSON.RESP	S	S	N	S	N	N
JSON.SET	S	N	S	N	S	N
JSON.STRAPPEND	S	N	S	S	N	N
JSON.STRLEN	S	S	N	S	N	N
JSON.TOGGLE	S	N	S	S	N	N
JSON.TYPE	S	S	N	S	N	N

Comandos JSON

Esta seção lista e descreve os comandos JSON que podem ser usados para realizar operações em documentos JSON.

Comando	Descrição
JSON.ARRAPPEND	Adiciona um ou mais valores JSON à matriz no caminho.
JSON.ARRINDEX	Pesquisa a primeira ocorrência de um valor escalar JSON em uma matriz.
JSON.ARRINSERT	Insere um ou mais valores JSON em uma matriz em um caminho antes do índice especificado.
JSON.ARRLEN	Recupera o comprimento da matriz JSON no caminho.
JSON.ARRPOP	Remove e retorna um elemento de um índice na matriz.
JSON.ARRTRIM	Corte uma matriz no caminho para que ela contenha apenas o intervalo inclusivo de elementos especificados.
JSON.CLEAR	Limpe as matrizes ou um objeto JSON em um caminho especificado.
JSON.DEBUG	Recupera informações sobre um documento JSON. O Memorystore for Valkey é compatível com os seguintes subcomandos: MEMORY: informa o uso da memória de um valor em bytes. DEPTH: informa a profundidade máxima do caminho de um documento JSON. FIELDS: informa o número de campos em um elemento JSON. Esse elemento é armazenado em uma chave especificada por você. HELP: retorna informações úteis sobre o comando JSON.DEBUG.
JSON.DEL JSON.FORGET	Exclua valores JSON em um caminho especificado.
JSON.GET	Retorna um valor em um caminho especificado em formato JSON serializado.
JSON.MGET	Retorna valores em um caminho especificado de várias chaves de documento.
JSON.MSET	Defina vários valores JSON em um caminho para várias chaves.
JSON.NUMINCRBY	Incrementa valores numéricos armazenados em um caminho por um número especificado.
JSON.NUMMULTBY	Multiplica valores numéricos armazenados em um caminho por um número especificado.
JSON.OBJKEYS	Recupera nomes de chaves de objetos JSON em um caminho especificado.
JSON.OBJLEN	Recupera o número de chaves em um objeto JSON em um caminho especificado.
JSON.RESP	Retorna o valor JSON de uma chave no formato do protocolo de serialização do Redis (RESP).
JSON.SET	Defina valores JSON em um caminho especificado.
JSON.STRAPPEND	Anexe uma string a strings JSON em um caminho especificado.
JSON.STRLEN	Recupere o comprimento dos valores de string JSON em um caminho especificado.
JSON.TOGGLE	Alterna um valor booleano entre true e false. Esse valor é armazenado em um caminho especificado por você.
JSON.TYPE	Recupera o tipo de um valor JSON em um caminho especificado.

Observação: para mais informações sobre como usar esses comandos, consulte a página Referência de comandos do Valkey. Você pode verificar o desempenho do uso desses comandos. Para mais informações, consulte Performance.

Como o Memorystore for Valkey interage com JSON

Esta seção descreve como o Memorystore para Valkey interage com o tipo de dados JSON.

Várias expressões condicionais

Se houver várias expressões condicionais para filtragem, a Memorystore para Valkey as avaliará na seguinte ordem:

1. Operações entre parênteses
2. A expressão lógica AND (&&)
3. A expressão lógica OR (||)

Limite máximo de profundidade de aninhamento

Quando um objeto ou matriz JSON tem um elemento que é outro objeto ou matriz JSON, o objeto ou matriz interno é aninhado no objeto ou matriz externo. O limite máximo de profundidade de aninhamento é 128. Assim, um valor como $.a.b.c.d... pode atingir apenas 128 níveis.

Se você tentar criar um documento JSON com uma profundidade de aninhamento maior que 128, o Memorystore for Valkey vai rejeitar o documento e você vai receber um erro. No entanto, é possível ajustar esse limite usando o comando CONFIG SET json.max-path-limit VALUE, em que VALUE é o limite de profundidade desejado.

Números JSON

Em JSON, tanto números de ponto flutuante quanto números inteiros são chamados de números porque têm o mesmo tipo de dados. Quando o Memorystore para Valkey recebe um número JSON, ele o converte em uma das seguintes representações binárias internas:

• Um número de ponto flutuante de dupla precisão IEEE de 64 bits
• Um número inteiro assinado de 64 bits

O JSON não retém a string original e toda a formatação dela. Quando a Memorystore para Valkey gera um número como parte de uma resposta JSON, a Memorystore para Valkey converte o número da representação binária interna para uma string imprimível que usa regras de formatação genéricas.

Quando você usa os comandos JSON.NUMINCRBY e JSON.NUMMULTBY com números JSON, as seguintes condições se aplicam:

• Se os dois números forem inteiros e o resultado estiver fora do intervalo de int64, ele se tornará automaticamente um número de ponto flutuante de dupla precisão IEEE de 64 bits.
• Se pelo menos um dos números for um número de ponto flutuante, o resultado será um número de ponto flutuante de dupla precisão IEEE de 64 bits.
• Se o resultado exceder o intervalo do número de ponto flutuante de dupla precisão IEEE de 64 bits, você vai receber uma mensagem de erro OVERFLOW.

Matrizes diretas

O Memorystore for Valkey filtra objetos de matriz diretamente. Por exemplo, se você tiver dados como
[0,1,2,3] e uma consulta de caminho como $[?(@<3)], a Memorystore for Valkey vai retornar [0,1,2]. Para dados como {"my_valkey_key":[0,1,2,3]} e uma consulta de caminho como
$.my_valkey_key[?(@<3)], o Memorystore for Valkey também retorna [0,1,2].

Índices de matriz

O Memorystore para Valkey permite usar índices positivos e negativos para matrizes. As seguintes condições se aplicam a esses tipos de índices:

• Índice positivo: os números começam no início da matriz. Por exemplo, se uma matriz tiver um índice positivo de três, 0 vai consultar o primeiro elemento, 1 vai consultar o segundo e 2 vai consultar o terceiro.
• Índice negativo: os números começam no final da matriz. Se uma matriz tiver um índice negativo de três, -1 vai consultar o terceiro elemento, -2 vai consultar o segundo elemento e -3 vai consultar o primeiro elemento.

O Memorystore para Valkey não arredonda os índices para cima ou para baixo. Se você tiver uma matriz com um comprimento de 3 e chamar um índice positivo maior que 3 ou um índice negativo menor que -3, o Memorystore para Valkey não retornará um resultado.

Sintaxe para caminhos JSON

Não é possível usar sintaxe inválida nos seus caminhos JSON. Essa condição se aplica mesmo que um subconjunto de um caminho JSON com uma sintaxe inválida contenha um caminho válido.