Nesta página, descrevemos como trabalhar com o tipo de dados JSONB
ao usar o Spanner.
JSONB
é um tipo de dados do PostgreSQL usado para manter dados semiestruturados no dialeto PostgreSQL do Spanner. JSONB
armazena dados no formato JavaScript Object Notation (JSON), que segue a especificação descrita na RFC 7159 (em inglês).
Especificações
O tipo de dados JSONB
do Spanner armazena uma representação normalizada do documento de entrada. Isso implica o seguinte:
- Aspas e caracteres de espaços em branco não são preservados.
- Não é possível usar comentários. Falha em transações ou consultas com comentários.
- As chaves de objeto são classificadas primeiro pelo comprimento da chave e, em seguida, lexicograficamente pelo comprimento equivalente da chave de objeto. Se houver chaves de objetos duplicadas, apenas a última será preservada.
- Os tipos primitivos (
string
,boolean
,number
enull
) têm o tipo e o valor preservados.- Os valores do tipo
string
são preservados exatamente. - Os zeros à direita são preservados. O formato de saída para valores de tipo
number
não usa a notação científica.
- Os valores do tipo
Os valores
JSONB
null
são tratados como SQL nãoNULL
. Por exemplo:SELECT null::jsonb IS NULL; -- Returns true SELECT 'null'::jsonb IS NULL; -- Returns false SELECT '{"a":null}'::jsonb -> 'a' IS NULL; -- Returns false SELECT '{"a":null}'::jsonb -> 'b' IS NULL; -- Returns true SELECT '{"a":null}'::jsonb -> 'a'; -- Returns a JSONB 'null' SELECT '{"a":null}'::jsonb -> 'b'; -- Returns a SQL NULL
A ordem dos elementos da matriz JSONB é preservada.
Restrições
As restrições a seguir se aplicam ao Spanner JSONB
:
- Os argumentos para a função
to_jsonb
só podem ser dos tipos de dados do PostgreSQL compatíveis com o Spanner. - Os valores de tipo numérico podem ter 4.932 dígitos antes do ponto decimal e 16.383 dígitos após o ponto decimal.
- O tamanho máximo permitido do formato de armazenamento normalizado é de 10 MB.
- Os documentos
JSONB
precisam ser codificados em UTF-8. As transações ou consultas com documentosJSONB
codificados em outros formatos retornam um erro.
Criar uma tabela com colunas JSONB
É possível adicionar uma coluna JSONB
a uma tabela durante a criação dela.
CREATE TABLE Venues (
VenueId BIGINT PRIMARY KEY,
VenueName VARCHAR(1024),
VenueAddress VARCHAR(1024),
VenueFeatures JSONB,
DateOpened TIMESTAMPTZ
);
Veja a seguir um exemplo do objeto JSONB
VenueFeatures
:
{
"rating": 4.5,
"capacity":"1500",
"construction":"brick",
"tags": [
"multi-cuisine",
"open-seating",
"stage",
"public address system"
]
}
Adicionar e remover colunas JSONB de tabelas atuais
É possível adicionar uma coluna JSONB
e soltá-la usando instruções ALTER
da seguinte maneira:
ALTER TABLE Venues ADD COLUMN VenueDetails JSONB;
ALTER TABLE Venues DROP COLUMN VenueDetails;
O exemplo a seguir mostra como adicionar uma coluna JSONB
chamada VenueDetails
à tabela Venues
usando bibliotecas de cliente do Spanner.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Modificar dados JSONB
É possível modificar uma coluna JSONB
como qualquer outra coluna.
Confira um exemplo:
UPDATE Venues SET VenueFeatures = '{"rating": 4.5, "tags":["multi-cuisine", "open-seating"] }'
WHERE VenueId = 1;
O exemplo a seguir mostra como atualizar dados JSONB
usando
bibliotecas de cliente do Spanner.
C++
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
C#
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consultar dados JSONB
É possível consultar colunas JSONB
com base nos valores dos campos subjacentes. O
exemplo a seguir extrai VenueId
e VenueName
de Venues
, em que
VenueFeatures
tem um valor rating
maior que 3.5
.
SELECT VenueId, VenueName FROM Venues WHERE (VenueFeatures->>'rating')::FLOAT8 > 3.5;
O exemplo a seguir mostra como consultar dados JSONB
usando
bibliotecas de cliente do Spanner.
C++
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
C#
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Recursos não compatíveis do PostgreSQL JSONB
Os seguintes recursos JSONB
do PostgreSQL não são compatíveis com o Spanner JSONB
:
- Ordem, comparação e agregação
- PrimaryKey e ForeignKey
- Indexação, incluindo o índice de GIN. Para mais informações, consulte Indexação.
- Mudar uma coluna
JSONB
para ou de qualquer outro tipo de dados. - Uso de consultas parametrizadas com parâmetros JSONB não tipados em ferramentas que usam o protocolo de transferência do PostgreSQL
"Coerção" no mecanismo de consulta. Ao contrário do PostgreSQL padrão, a coerção de
JSONB
para texto não é compatível. Somente stringsJSON
válidas são forçadas para o tipoJSONB
para corresponder às assinaturas da função. Exemplos:SELECT concat('abc'::text, '{"key1":1}'::jsonb); -- Returns error SELECT concat('abc'::text, CAST('{"key1":1}'::jsonb AS TEXT)); -- This works
Indexação
As colunas JSONB
não oferecem suporte à indexação. No entanto, é possível criar um índice em
uma coluna gerada para extrair um valor escalar de uma coluna JSONB
.
CREATE TABLE Venues (
VenueId BIGINT PRIMARY KEY,
VenueName VARCHAR(1024),
VenueAddress VARCHAR(1024),
VenueFeatures JSONB,
TotalCapacity BIGINT GENERATED ALWAYS AS ((VenueFeatures->>'capacity')::BIGINT) STORED,
DateOpened TIMESTAMPTZ
);
CREATE INDEX VenuesByCapacity ON Venues(TotalCapacity);