Obiettivi
Questo tutorial ti guida attraverso i seguenti passaggi utilizzando la libreria client Spanner per Python:
- Crea un'istanza e un database Spanner.
- Scrivere, leggere ed eseguire query SQL sui dati nel database.
- Aggiorna lo schema del database.
- Aggiorna i dati utilizzando una transazione di lettura/scrittura.
- Aggiungi un indice secondario al database.
- Utilizza l'indice per leggere ed eseguire query SQL sui dati.
- Recupera i dati utilizzando una transazione di sola lettura.
Costi
Questo tutorial utilizza Spanner, che è un componente fatturabile di Google Cloud. Per informazioni sul costo dell'utilizzo di Spanner, consulta Prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurazione, che riguardano la creazione e l'impostazione di un progetto Google Cloud predefinito, l'abilitazione della fatturazione, l'abilitazione dell'API Cloud Spanner e la configurazione di OAuth 2.0 per ottenere le credenziali di autenticazione per utilizzare l'API Cloud Spanner.
In particolare, assicurati di eseguire gcloud auth
application-default login per configurare l'ambiente di sviluppo locale con le credenziali di autenticazione.
Prepara l'ambiente Python locale
Segui le istruzioni riportate in Configurazione di un ambiente di sviluppo Python.
Clona il repository dell'app di esempio sulla tua macchina locale:
git clone https://github.com/googleapis/google-cloud-python.gitIn alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice campione di Spanner:
cd google-cloud-python/packages/google-cloud-spanner/samples/samplesCrea un ambiente Python isolato e installa le dipendenze:
python3 -m venv env source env/bin/activate pip install -r requirements.txt
Crea un'istanza
Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero un'allocazione di risorse utilizzate dai database Spanner. Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove vengono archiviati i dati, nonché il numero di nodi da utilizzare, che determina la quantità di risorse di gestione e archiviazione nell'istanza.
Consulta Crea un'istanza per scoprire come creare un'istanza Spanner utilizzando uno dei seguenti metodi. Puoi assegnare all'istanza il nome test-instance per utilizzarla con altri argomenti di questo documento che fanno riferimento a un'istanza denominata test-instance.
- Google Cloud CLI
- La console Google Cloud
- Una libreria client (C++, C#, Go, Java, Node.js, PHP, Python, Ruby o Rust)
Esamina i file di esempio
Il repository degli esempi contiene un esempio che mostra come utilizzare Spanner con Python.
Esamina il filesnippets.py, che mostra come utilizzare Spanner. Il codice mostra come creare e utilizzare un nuovo database. I dati utilizzano lo schema di esempio mostrato nella pagina Schema e modello dei dati.
Crea un database
GoogleSQL
python snippets.py test-instance --database-id example-db create_database
PostgreSQL
python pg_snippets.py test-instance --database-id example-db create_database
Dovresti vedere:
Created database example-db on instance test-instance
GoogleSQL
PostgreSQL
Il passaggio successivo consiste nello scrivere i dati nel database.
Crea un client di database
Prima di poter eseguire operazioni di lettura o scrittura, devi creare unClient. Puoi pensare a un Client come a una connessione al database: tutte le tue interazioni con Spanner devono passare attraverso un Client. In genere, crei un Client all'avvio
dell'applicazione, quindi lo riutilizzi Client per leggere, scrivere ed
eseguire transazioni. Il codice seguente mostra come creare un client.
Scopri di più nella documentazione di riferimento di Client.
Scrivi dati con DML
Puoi inserire dati utilizzando il Data Manipulation Language (DML) in una transazione di lettura/scrittura.
Utilizza il metodo execute_update() per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento insert_with_dml.
python snippets.py test-instance --database-id example-db insert_with_dml
Dovresti vedere:
4 record(s) inserted.
Scrivi dati con mutazioni
Puoi anche inserire dati utilizzando le mutazioni.
I dati vengono scritti utilizzando un oggetto Batch. Un oggetto Batch è un container per le operazioni di mutazione. Una mutazione rappresenta una sequenza di inserimenti, aggiornamenti ed eliminazioni che Spanner applica in modo atomico a righe e tabelle diverse in un database Spanner.
Il metodo insert() nella classe Batch aggiunge una o più mutazioni di inserimento al batch. Tutte le mutazioni in un singolo batch vengono applicate in modo atomico.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui l'esempio utilizzando l'argomento insert_data.
python snippets.py test-instance --database-id example-db insert_data
Dovresti vedere:
Inserted data.
Esegui query sui dati utilizzando SQL
Spanner supporta un'interfaccia SQL per la lettura dei dati, a cui puoi accedere dalla riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando la libreria client di Spanner per Python.
Nella riga di comando
Esegui la seguente istruzione SQL per leggere i valori di tutte le colonne della tabella Albums:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Sintassi pipe di GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'
Il risultato mostra:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Utilizza la libreria client di Spanner per Python
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi eseguire la stessa istruzione SQL in modo programmatico utilizzando la libreria client di Spanner per Python.
Utilizza il metodo execute_sql() di un oggetto Snapshot per eseguire la query SQL. Per ottenere un oggetto Snapshot, chiama il metodo
snapshot()
della classe Database
in un'istruzione with.
Ecco come eseguire la query e accedere ai dati:
Esegui l'esempio utilizzando l'argomento query_data.
python snippets.py test-instance --database-id example-db query_data
Dovresti vedere il seguente risultato:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Esegui una query utilizzando un parametro SQL
Se la tua applicazione ha una query eseguita di frequente, puoi migliorarne le prestazioni parametrizzandola. La query parametrica risultante può essere memorizzata nella cache e riutilizzata, riducendo i costi di compilazione. Per saperne di più, consulta Utilizza parametri di ricerca per velocizzare le query eseguite di frequente.
Ecco un esempio di utilizzo di un parametro nella clausola WHERE per eseguire query sui record contenenti un valore specifico per LastName.
GoogleSQL
PostgreSQL
Esegui l'esempio utilizzando l'argomento query_data_with_parameter.
GoogleSQL
python snippets.py test-instance --database-id example-db query_data_with_parameter
PostgreSQL
python pg_snippets.py test-instance --database-id example-db query_data_with_parameter
Dovresti vedere il seguente risultato:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Leggi i dati utilizzando l'API di lettura
Oltre all'interfaccia SQL di Spanner, Spanner supporta anche un'interfaccia di lettura.
Utilizza il metodo read() di un oggetto Snapshot per leggere le righe dal database. Per ottenere un oggetto Snapshot, chiama il metodo
snapshot()
della classe Database
in un'istruzione with. Utilizza un oggetto KeySet per definire una raccolta di chiavi e intervalli di chiavi da leggere.
Ecco come leggere i dati:
Esegui l'esempio utilizzando l'argomento read_data.
python snippets.py test-instance --database-id example-db read_data
Dovresti visualizzare un output simile al seguente:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Aggiorna lo schema del database
Supponiamo che tu debba aggiungere una nuova colonna denominata MarketingBudget alla tabella Albums. L'aggiunta di una nuova colonna a una tabella esistente richiede un aggiornamento dello schema del database. Spanner supporta gli aggiornamenti dello schema di un database mentre il database continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono la disconnessione del database e non bloccano intere tabelle o colonne. Puoi continuare a scrivere dati nel database durante l'aggiornamento dello schema. Scopri di più sugli aggiornamenti dello schema supportati e sulle prestazioni delle modifiche allo schema in Esegui aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna dalla riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando la libreria client di Spanner per Python.
Nella riga di comando
Utilizza il seguente comando ALTER TABLE per aggiungere la nuova colonna alla tabella:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
Dovresti vedere:
Schema updating...done.
Utilizza la libreria client di Spanner per Python
Utilizza il metodoupdate_ddl() della classe Database per modificare lo schema:
GoogleSQL
PostgreSQL
Esegui l'esempio utilizzando l'argomento add_column.
GoogleSQL
python snippets.py test-instance --database-id example-db add_column
PostgreSQL
python pg_snippets.py test-instance --database-id example-db add_column
Dovresti vedere:
Added the MarketingBudget column.
Scrivi i dati nella nuova colonna
Il codice seguente scrive i dati nella nuova colonna. Imposta MarketingBudget su 100000 per la riga con chiave di riga Albums(1, 1) e su 500000 per la riga con chiave di riga Albums(2, 2).
Esegui l'esempio utilizzando l'argomento update_data.
python snippets.py test-instance --database-id example-db update_data
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori che hai appena scritto.
Ecco il codice per eseguire la query:
Per eseguire questa query, esegui l'esempio utilizzando l'argomento query_data_with_new_column.
python snippets.py test-instance --database-id example-db query_data_with_new_column
Dovresti vedere:
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 1, AlbumId: 2, MarketingBudget: None
SingerId: 2, AlbumId: 1, MarketingBudget: None
SingerId: 2, AlbumId: 3, MarketingBudget: None
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
Aggiorna i dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Utilizza il metodo execute_update() per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento write_with_dml_transaction.
python snippets.py test-instance --database-id example-db write_with_dml_transaction
Dovresti vedere:
Transferred 200000 from Album2's budget to Album1's
Utilizza un indice secondario
Supponiamo che tu voglia recuperare tutte le righe di Albums che hanno valori AlbumTitle in un determinato intervallo. Puoi leggere tutti i valori della colonna AlbumTitle utilizzando un'istruzione SQL o una chiamata di lettura, quindi eliminare le righe che non soddisfano i criteri, ma questa scansione completa della tabella è costosa, soprattutto per le tabelle con molte righe. Puoi invece velocizzare il recupero delle righe durante la ricerca in base a colonne di chiavi non primarie creando un indice secondario nella tabella.
L'aggiunta di un indice secondario a una tabella esistente richiede un aggiornamento dello schema. Come altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice mentre il database continua a gestire il traffico. Spanner esegue automaticamente il backfill dell'indice con i dati esistenti. I backfill potrebbero richiedere alcuni minuti, ma non è necessario portare il database offline o evitare di scrivere nella tabella indicizzata durante questo processo. Per maggiori dettagli, consulta Aggiungi un indice secondario.
Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per le query SQL che probabilmente verranno eseguite più velocemente con l'indice. Se utilizzi l'interfaccia di lettura, devi specificare l'indice che vuoi utilizzare.
Aggiungi un indice secondario
Puoi aggiungere un indice dalla riga di comando utilizzando gcloud CLI o in modo programmatico utilizzando la libreria client di Spanner per Python.
Nella riga di comando
Utilizza il seguente comando CREATE INDEX per aggiungere un indice al database:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per Python
Utilizza il metodoupdate_ddl() della classe Database per aggiungere un indice:
Esegui l'esempio utilizzando l'argomento add_index.
python snippets.py test-instance --database-id example-db add_index
L'aggiunta di un indice può richiedere alcuni minuti. Dopo aver aggiunto l'indice, dovresti vedere:
Added the AlbumsByAlbumTitle index.
Lettura con l'indice
Per le query SQL, Spanner utilizza automaticamente un indice appropriato. Nell'interfaccia di lettura, devi specificare l'indice nella richiesta.
Per utilizzare l'indice nell'interfaccia di lettura, fornisci un argomento Index al metodo read() di un oggetto Snapshot. Per ottenere un oggetto Snapshot, chiama il metodo snapshot() della classe Database in un'istruzione with.
Esegui l'esempio utilizzando l'argomento read_data_with_index.
python snippets.py test-instance --database-id example-db read_data_with_index
Dovresti vedere:
AlbumId: 2, AlbumTitle: Forever Hold Your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: Total Junk
Aggiungi un indice per le letture solo indice
Potresti aver notato che l'esempio di lettura precedente non include la lettura della colonna MarketingBudget. Questo perché l'interfaccia di lettura di Spanner non supporta la possibilità di unire un indice a una tabella di dati per cercare al volo valori non archiviati nell'indice.
Crea una definizione alternativa di AlbumsByAlbumTitle che memorizza una copia di MarketingBudget nell'indice.
Nella riga di comando
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
L'aggiunta di un indice può richiedere alcuni minuti. Dopo aver aggiunto l'indice, dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per Python
Utilizza il metodoupdate_ddl() della classe Database per aggiungere un indice con una clausola STORING:
Esegui l'esempio utilizzando l'argomento add_storing_index.
python snippets.py test-instance --database-id example-db add_storing_index
Dovresti vedere:
Added the AlbumsByAlbumTitle2 index.
Ora puoi eseguire una lettura che recupera tutte le colonne AlbumId, AlbumTitle e MarketingBudget dall'indice AlbumsByAlbumTitle2:
Esegui l'esempio utilizzando l'argomento read_data_with_storing_index.
python snippets.py test-instance --database-id example-db read_data_with_storing_index
Dovresti visualizzare un output simile al seguente:
AlbumId: 2, AlbumTitle: Forever Hold Your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: None
AlbumId: 1, AlbumTitle: Green, MarketingBudget: None
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: None
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 300000
Recupera i dati utilizzando transazioni di sola lettura
Supponiamo che tu voglia eseguire più di una lettura con lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia dei commit delle transazioni, in modo che l'applicazione riceva sempre dati coerenti.
Utilizza un oggetto Snapshot per eseguire transazioni di sola lettura. Per ottenere un oggetto Snapshot, chiama il metodo
snapshot()
della classe Database
in un'istruzione with.
Di seguito viene mostrato come eseguire una query ed eseguire una lettura nella stessa transazione di sola lettura:
Esegui l'esempio utilizzando l'argomento read_only_transaction.
python snippets.py test-instance --database-id example-db read_only_transaction
Dovresti visualizzare un output simile al seguente:
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Esegui la pulizia
Per evitare che al tuo account di fatturazione Cloud vengano addebitati costi aggiuntivi per le risorse utilizzate in questo tutorial, elimina il database e l'istanza che hai creato.
Elimina il database
Se elimini un'istanza, tutti i database al suo interno vengono eliminati automaticamente. Questo passaggio mostra come eliminare un database senza eliminare un'istanza (ti verranno comunque addebitati i costi per l'istanza).
Nella riga di comando
gcloud spanner databases delete example-db --instance=test-instance
Utilizzo della console Google Cloud
Vai alla pagina Istanze Spanner nella console Google Cloud .
Fai clic sull'istanza.
Fai clic sul database che vuoi eliminare.
Nella pagina Dettagli database, fai clic su Elimina.
Conferma di voler eliminare il database e fai clic su Elimina.
Elimina l'istanza
L'eliminazione di un'istanza comporta l'eliminazione automatica di tutti i database creati in quell'istanza.
Nella riga di comando
gcloud spanner instances delete test-instance
Utilizzo della console Google Cloud
Vai alla pagina Istanze Spanner nella console Google Cloud .
Fai clic sull'istanza.
Fai clic su Elimina.
Conferma di voler eliminare l'istanza e fai clic su Elimina.
Passaggi successivi
Scopri come accedere a Spanner con un'istanza di macchina virtuale.
Scopri di più sulle credenziali di autorizzazione e autenticazione in Autenticati ai servizi Cloud utilizzando le librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.