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 armazenar dados semiestruturados
no dialeto PostgreSQL do Spanner. JSONB
guarda de dados
em formato JavaScript Object Notation (JSON), que segue a especificação
descritos na RFC 7159 (link em inglês).
Especificações
O tipo de dados JSONB
do Spanner armazena uma representação normalizada
o 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. Transações ou consultas com comentários falham.
- As chaves de objeto são classificadas primeiro pelo comprimento da chave e depois lexicograficamente pelo comprimento equivalente da chave de objeto. Se houver chaves de objetos duplicadas, somente a última um deles seja preservado.
- O tipo e o valor de tipos primitivos (
string
,boolean
,number
enull
) são preservados.- Os valores do tipo
string
são preservados exatamente. - Os zeros à direita são preservados. O formato de saída para valores do tipo
number
não usa 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 seguintes restrições são aplicadas com o Spanner JSONB
:
- Os argumentos para a função
to_jsonb
só podem ser do PostgreSQL e tipos de dados compatíveis com o Spanner. - Os valores do tipo numérico podem ter 4.932 dígitos antes do ponto decimal e 16.383 dígitos depois do ponto decimal.
- O tamanho máximo permitido do formato de armazenamento normalizado é de 10 MB.
- Os documentos
JSONB
precisam ser codificados em UTF-8. 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.
CREATE TABLE Venues (
VenueId BIGINT PRIMARY KEY,
VenueName VARCHAR(1024),
VenueAddress VARCHAR(1024),
VenueFeatures JSONB,
DateOpened TIMESTAMPTZ
);
Confira um exemplo de 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 as 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 aprender a 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 aprender a 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 aprender a 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. 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 aprender a 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 aprender a 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 aprender a 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 aprender a 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 do JSONB do PostgreSQL sem suporte
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 GIN. Para mais informações, consulte Indexação.
- Mudar uma coluna
JSONB
para ou de qualquer outro tipo de dados. - Como usar consultas parametrizadas com parâmetros JSONB não tipados em ferramentas que usam o protocolo de rede PostgreSQL
Coerção no mecanismo de consulta. Ao contrário do PostgreSQL padrão, não há suporte para coerção de
JSONB
para texto. Somente stringsJSON
válidas são convertidas em tipoJSONB
para corresponder às assinaturas de 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
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);