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
contém dados
no formato JavaScript Object Notation (JSON), que segue a especificação
descrita na RFC 7159 (link 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:
- As aspas e os caracteres de espaço 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, em seguida, lexicograficamente pelo tamanho equivalente da chave do objeto. Se houver chaves de objeto 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 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 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 é 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 dela.
CREATE TABLE Venues (
VenueId BIGINT PRIMARY KEY,
VenueName VARCHAR(1024),
VenueAddress VARCHAR(1024),
VenueFeatures JSONB,
DateOpened TIMESTAMPTZ
);
Confira abaixo 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
É 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;
A amostra a seguir mostra como atualizar dados JSONB
usando as bibliotecas de cliente do Spanner.
C++
Para saber como instalar e usar a biblioteca de cliente para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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
do Venues
, em que
VenueFeatures
tem um valor rating
maior que 3.5
.
SELECT VenueId, VenueName FROM Venues WHERE (VenueFeatures->>'rating')::FLOAT8 > 3.5;
A amostra a seguir mostra como consultar dados JSONB
usando as bibliotecas de cliente do Spanner.
C++
Para saber como instalar e usar a biblioteca de cliente para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 incompatíveis do PostgreSQL JSONB
Os seguintes recursos JSONB
do PostgreSQL não são compatíveis com o JSONB
do Spanner:
- Ordem, comparação e agregação
- PrimaryKey e ForeignKey
- Indexação, incluindo o índice GIN. Para mais informações, consulte Indexação.
- Alterar uma coluna
JSONB
para ou de qualquer outro tipo de dados - Como usar consultas parametrizadas com parâmetros JSONB não digitados 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. Apenas 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 são compatíveis com 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);