Questa pagina descrive come utilizzare JSON con Spanner.
Il tipo di dati JSON è un tipo di dati semistrutturato utilizzato per contenere dati JSON (JavaScript Object Notation). Le specifiche per il formato JSON sono descritte nel documento RFC 7159.
JSON è utile per integrare uno schema relazionale per i dati sparsi o con una struttura definita in modo approssimativo o in evoluzione. Tuttavia, l'ottimizzatore di query si basa sul modello relazionale per filtrare, unire, aggregare e ordinare in modo efficiente su larga scala. Le query su JSON avranno meno ottimizzazioni integrate e meno funzionalità per esaminare e ottimizzare le prestazioni.
Specifiche
Il tipo JSON di Spanner memorizza una rappresentazione normalizzata del documento JSON di input.
- JSON può essere nidificato fino a un massimo di 80 livelli.
- Lo spazio vuoto non viene mantenuto.
- I commenti non sono supportati. Le transazioni o le query con commenti non andranno a buon fine.
- I membri di un oggetto JSON sono ordinati lessicograficamente.
- L'ordine degli elementi dell'array JSON viene mantenuto.
- Se un oggetto JSON ha chiavi duplicate, viene mantenuta solo la prima.
- I tipi primitivi (stringa, booleano, numero e null) mantengono il tipo
e il valore.
- I valori di tipo String vengono conservati esattamente.
- I valori di tipo numerico vengono conservati, ma la loro rappresentazione testuale potrebbe essere modificata in seguito al processo di normalizzazione. Ad esempio, un numero di input pari a 10000 può avere una rappresentazione normalizzata pari a 1e+4. La semantica di conservazione dei valori numerici è la seguente:
- Gli interi con segno nell'intervallo [INT64_MIN, INT64_MAX] vengono conservati.
- I numeri interi senza segno nell'intervallo [0, UINT64_MAX] vengono conservati.
- I valori doppi che possono essere convertiti da stringa a doppio e da doppio a stringa senza perdita di precisione vengono conservati. Se un valore doppio non può
essere convertito in questo modo, la transazione o la query non riesce.
- Ad esempio,
SELECT JSON '2.2412421353246235436'
non va a buon fine. - Una soluzione alternativa funzionale è
PARSE_JSON('2.2412421353246235436', wide_number_mode=>'round')
, che restituisceJSON '2.2412421353246237'
.
- Ad esempio,
- Utilizza le funzioni
TO_JSON()
,JSON_OBJECT()
eJSON_ARRAY()
per creare documenti JSON in SQL. Queste funzioni implementano i caratteri di escape e le virgolette necessari.
La dimensione massima consentita del documento normalizzato è di 10 MB.
Supporto di valori Null
I valori JSON null
vengono trattati come SQL non NULL.
Ad esempio:
SELECT (JSON '{"a":null}').a IS NULL; -- Returns FALSE
SELECT (JSON '{"a":null}').b IS NULL; -- Returns TRUE
SELECT JSON_QUERY(JSON '{"a":null}', "$.a"); -- Returns a JSON 'null'
SELECT JSON_QUERY(JSON '{"a":null}', "$.b"); -- Returns a SQL NULL
Codifica
I documenti JSON devono essere codificati in UTF-8. Le transazioni o le query con documenti JSON codificati in altri formati restituiscono un errore.
Crea una tabella con colonne JSON
Una colonna JSON può essere aggiunta a una tabella quando viene creata. I valori del tipo JSON possono essere nullabili.
CREATE TABLE Venues (
VenueId INT64 NOT NULL,
VenueName STRING(1024),
VenueAddress STRING(1024),
VenueFeatures JSON,
DateOpened DATE,
) PRIMARY KEY(VenueId);
Aggiungere e rimuovere colonne JSON dalle tabelle esistenti
Una colonna JSON può anche essere aggiunta e rimossa dalle tabelle esistenti.
ALTER TABLE Venues ADD COLUMN VenueDetails JSON;
ALTER TABLE Venues DROP COLUMN VenueDetails;
Il seguente esempio mostra come aggiungere una colonna JSON
denominata VenueDetails
alla tabella Venues
utilizzando le librerie client Spanner.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Modificare i dati JSON
Il seguente esempio mostra come aggiornare i dati JSON
utilizzando le librerie client Spanner.
C++
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
C#
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Indicizzare i dati JSON
Puoi accelerare l'esecuzione di query sui dati JSON utilizzando indici secondari e indici di ricerca con i tuoi dati JSON. Spanner non supporta l'utilizzo di colonne di tipo JSON come chiavi negli indici secondari.
Utilizzare l'indice secondario
Gli indici secondari sono utili per filtrare in base a valori scalari all'interno di un documento JSON. Per utilizzare gli indici secondari con JSON, crea una colonna generata che estrae i dati scalari pertinenti e converte i dati in un tipo SQL appropriato. Puoi quindi creare un indice secondario su questa colonna generata. L'indice accelera le query idonee eseguite sulla colonna generata.
Nell'esempio seguente, crei un indice VenuesByCapacity
che il database utilizza per trovare le sedi con capacità superiore a 1000. Anziché controllare ogni riga, Spanner utilizza l'indice per individuare le righe pertinenti, il che migliora il rendimento delle query, soprattutto per le tabelle di grandi dimensioni.
ALTER TABLE Venues
ADD COLUMN VenueCapacity INT64 AS (INT64(VenueDetails.capacity));
CREATE INDEX VenuesByCapacity ON Venue (VenueCapacity);
SELECT VenueName
FROM Venues
WHERE VenueCapacity > 1000;
Utilizzare gli indici di ricerca
Gli indici di ricerca sono utili quando esegui query su documenti JSON dinamici o variabili. A differenza degli indici secondari, puoi creare indici di ricerca su qualsiasi documento JSON archiviato in una colonna JSON. L'indice di ricerca si adatta automaticamente alle variazioni nei documenti JSON, tra le diverse righe e nel tempo.
Nell'esempio seguente, crei un indice di ricerca VenuesByVenueDetails
che
il database utilizza per trovare le sedi con dettagli specifici come dimensioni e
orario di apertura. Anziché controllare ogni riga, Spanner utilizza l'indice per individuare le righe pertinenti, il che migliora le prestazioni delle query, soprattutto per le tabelle di grandi dimensioni.
ALTER TABLE Venues
ADD COLUMN VenueDetails_Tokens TOKENLIST AS (TOKENIZE_JSON(VenueDetails)) HIDDEN;
CREATE SEARCH INDEX VenuesByVenueDetails
ON Venue (VenueDetails_Tokens);
SELECT VenueName
FROM Venues
WHERE JSON_CONTAINS(VenueDetails, JSON '{"labels": ["large"], "open": {"Friday": true}}');
Per saperne di più, consulta Indici di ricerca JSON.
Eseguire query sui dati JSON
Il seguente esempio mostra come eseguire query sui dati JSON
utilizzando le librerie client Spanner.
C++
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
C#
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Spanner, consulta la sezione Librerie client Spanner.
Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Limitazioni
- Non puoi utilizzare le colonne JSON in una clausola
ORDER BY
. - Non puoi utilizzare le colonne di tipo JSON come chiavi primarie o come chiavi negli indici secondari. Per saperne di più, consulta la sezione Indicizzare i dati JSON.
Passaggi successivi
- Tipo di dati JSON
- Funzioni JSON
- Operatori JSON: