Introduzione a Spanner in Python

Obiettivi

Questo tutorial illustra i passaggi seguenti utilizzando Spanner libreria client per Python:

  • Creare un'istanza e un database Spanner.
  • Scrivere, leggere ed eseguire query SQL sui dati nel database.
  • Aggiorna lo schema del database.
  • Aggiornare 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, un componente fatturabile di Google Cloud. Per informazioni sul costo di utilizzo di Spanner, consulta Prezzi.

Prima di iniziare

Completa i passaggi descritti in Configurazione, che trattano la creazione e impostare un progetto Google Cloud predefinito, abilitare la fatturazione, abilitare l'API Cloud Spanner e la configurazione di OAuth 2.0 per recuperare le credenziali di autenticazione da utilizzare l'API Cloud Spanner.

In particolare, assicurati di eseguire gcloud auth application-default login per configurare l'ambiente di sviluppo locale con l'autenticazione e credenziali.

Prepara l'ambiente Python locale

  1. Segui le istruzioni in Configurazione di un ambiente di sviluppo Python.

  2. Clona il repository dell'app di esempio nella tua macchina locale:

    git clone https://github.com/googleapis/python-spanner

    In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.

  3. Passa alla directory che contiene il codice campione di Spanner:

    cd python-spanner/samples/samples

  4. Crea un ambiente Python isolato e installa le dipendenze:

    virtualenv 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 delle risorse usate dai database Spanner. Quando Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove sono archiviati i dati e il numero di nodi da utilizzare, che determina e la quantità di risorse di servizio e archiviazione nell'istanza.

Esegui questo comando per creare un'istanza Spanner nella regione us-central1 con 1 nodo:

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="Test Instance" --nodes=1

Tieni presente che viene creata un'istanza con le seguenti caratteristiche:

  • ID istanza test-instance
  • Nome visualizzato Test Instance
  • Configurazione istanza regional-us-central1 (archivio configurazioni regionali i dati in una regione, mentre le configurazioni multiregionali distribuiscono i dati in più regioni. Per ulteriori informazioni, consulta Informazioni sulle istanze.
  • Conteggio dei nodi pari a 1 (node_count corrisponde alla quantità di pubblicazione e archiviazione e le risorse disponibili per i database nell'istanza. Scopri di più in Nodi e unità di elaborazione.

Dovresti vedere:

Creating instance...done.

Esamina i file di esempio

Il repository di esempi contiene un esempio che mostra come utilizzare Spanner con Python.

Dai un'occhiata al file snippets.py, che spiega come utilizzare Spanner. Il codice mostra come creare e utilizzare un nuovo database. I dati utilizza lo schema di esempio mostrato Pagina Schema e modello dei dati.

Crea un database

Crea un database denominato example-db nell'istanza test-instance eseguendo quanto segue nella riga di comando.

python snippets.py test-instance --database-id example-db create_database

Dovresti vedere:

Created database example-db on instance test-instance
Il seguente codice crea un database e due tabelle al suo interno. 
def create_database(instance_id, database_id):
    """Creates a database and tables for sample data."""
    from google.cloud.spanner_admin_database_v1.types import \
        spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.CreateDatabaseRequest(
        parent=database_admin_api.instance_path(spanner_client.project, instance_id),
        create_statement=f"CREATE DATABASE `{database_id}`",
        extra_statements=[
            """CREATE TABLE Singers (
            SingerId     INT64 NOT NULL,
            FirstName    STRING(1024),
            LastName     STRING(1024),
            SingerInfo   BYTES(MAX),
            FullName   STRING(2048) AS (
                ARRAY_TO_STRING([FirstName, LastName], " ")
            ) STORED
        ) PRIMARY KEY (SingerId)""",
            """CREATE TABLE Albums (
            SingerId     INT64 NOT NULL,
            AlbumId      INT64 NOT NULL,
            AlbumTitle   STRING(MAX)
        ) PRIMARY KEY (SingerId, AlbumId),
        INTERLEAVE IN PARENT Singers ON DELETE CASCADE""",
        ],
    )

    operation = database_admin_api.create_database(request=request)

    print("Waiting for operation to complete...")
    database = operation.result(OPERATION_TIMEOUT_SECONDS)

    print(
        "Created database {} on instance {}".format(
            database.name,
            database_admin_api.instance_path(spanner_client.project, instance_id),
        )
    )

Il passaggio successivo è scrivere dati nel database.

Crea un client di database

Prima di poter eseguire operazioni di lettura o scrittura, devi creare un Client Tu può pensare a Client come a una connessione di database: tutte le tue interazioni con Spanner deve passare attraverso un Client. Di solito crei una Client quando viene avviata l'applicazione, quindi riutilizzi Client per leggere, scrivere eseguire transazioni. Il codice seguente mostra come creare un client.

# Imports the Google Cloud Client Library.
from google.cloud import spanner

# Your Cloud Spanner instance ID.
# instance_id = "my-instance-id"
#
# Your Cloud Spanner database ID.
# database_id = "my-database-id"
# Instantiate a client.
spanner_client = spanner.Client()

# Get a Cloud Spanner instance by ID.
instance = spanner_client.instance(instance_id)

# Get a Cloud Spanner database by ID.
database = instance.database(database_id)

# Execute a simple SQL statement.
with database.snapshot() as snapshot:
    results = snapshot.execute_sql("SELECT 1")

    for row in results:
        print(row)

Scopri di più nel Client riferimento.

Scrivere dati con DML

Puoi inserire dati utilizzando DML (Data Manipulation Language) in un ambiente transazione.

Utilizzi il metodo execute_update() per eseguire un'istruzione DML.

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

def insert_singers(transaction):
    row_ct = transaction.execute_update(
        "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
        "(12, 'Melissa', 'Garcia'), "
        "(13, 'Russell', 'Morales'), "
        "(14, 'Jacqueline', 'Long'), "
        "(15, 'Dylan', 'Shaw')"
    )
    print("{} record(s) inserted.".format(row_ct))

database.run_in_transaction(insert_singers)

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.

Scrivere dati con mutazioni

Puoi anche inserire i dati utilizzando le mutazioni.

Scrivi i dati utilizzando un Batch . Un oggetto Batch è un container per le operazioni di mutazione. Una mutazione rappresenta una sequenza di inserimenti, aggiornamenti ed eliminazioni che Spanner si applica a livello atomico a diverse righe e tabelle in un database Spanner.

La insert() nella classe Batch aggiunge una o più mutazioni insert alla batch. Tutte le mutazioni in un singolo batch vengono applicate a livello atomico.

Questo codice mostra come scrivere i dati utilizzando le mutazioni:

def insert_data(instance_id, database_id):
    """Inserts sample data into the given database.

    The database and table must already exist and can be created using
    `create_database`.
    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.batch() as batch:
        batch.insert(
            table="Singers",
            columns=("SingerId", "FirstName", "LastName"),
            values=[
                (1, "Marc", "Richards"),
                (2, "Catalina", "Smith"),
                (3, "Alice", "Trentor"),
                (4, "Lea", "Martin"),
                (5, "David", "Lomond"),
            ],
        )

        batch.insert(
            table="Albums",
            columns=("SingerId", "AlbumId", "AlbumTitle"),
            values=[
                (1, 1, "Total Junk"),
                (1, 2, "Go, Go, Go"),
                (2, 1, "Green"),
                (2, 2, "Forever Hold Your Peace"),
                (2, 3, "Terrified"),
            ],
        )

    print("Inserted data.")

Esegui l'esempio utilizzando l'argomento insert_data.

python snippets.py test-instance --database-id example-db insert_data

Dovresti vedere:

Inserted data.

Eseguire query sui dati utilizzando SQL

Spanner supporta un'interfaccia SQL per la lettura dei dati, che puoi l'accesso dalla riga di comando utilizzando Google Cloud CLI in modo programmatico utilizzando la libreria client di Spanner per Python.

Nella riga di comando

Esegui questa istruzione SQL per leggere i valori di tutte le colonne dalla Tabella Albums:

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Il risultato dovrebbe essere:

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Utilizzare la libreria client Spanner per Python

Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi emettere la stessa istruzione SQL in modo programmatico utilizzando la libreria client Spanner per Python.

Utilizza la execute_sql() di un Snapshot oggetto eseguire la query SQL. Per ottenere un oggetto Snapshot, chiama il metodo snapshot() della classe Database in un'istruzione with.

Ecco come inviare la query e accedere ai dati:

def query_data(instance_id, database_id):
    """Queries sample data from the database using SQL."""
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        results = snapshot.execute_sql(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums"
        )

        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

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, riduce i costi di compilazione. Per ulteriori informazioni, vedi Utilizza parametri di ricerca per velocizzare le query eseguite di frequente.

Ecco un esempio di utilizzo di un parametro nella clausola WHERE per record di query contenenti un valore specifico per LastName.

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

with database.snapshot() as snapshot:
    results = snapshot.execute_sql(
        "SELECT SingerId, FirstName, LastName FROM Singers "
        "WHERE LastName = @lastName",
        params={"lastName": "Garcia"},
        param_types={"lastName": spanner.param_types.STRING},
    )

    for row in results:
        print("SingerId: {}, FirstName: {}, LastName: {}".format(*row))

Esegui l'esempio utilizzando l'argomento query_data_with_parameter.

python snippets.py test-instance --database-id example-db query_data_with_parameter

Dovresti vedere il seguente risultato:

SingerId: 12, FirstName: Melissa, LastName: Garcia

Leggere i dati utilizzando l'API di lettura

Oltre all'interfaccia SQL di Spanner, Spanner supporta anche una 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() di Database in un'istruzione with. Utilizza un KeySet per definire una raccolta di chiavi e intervalli di chiavi da leggere.

Ecco come leggere i dati:

def read_data(instance_id, database_id):
    """Reads sample data from the database."""
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        keyset = spanner.KeySet(all_=True)
        results = snapshot.read(
            table="Albums", columns=("SingerId", "AlbumId", "AlbumTitle"), keyset=keyset
        )

        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

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

Supponi di dover aggiungere una nuova colonna denominata MarketingBudget a Albums tabella. L'aggiunta di una nuova colonna a una tabella esistente richiede un aggiornamento delle lo schema del database. Spanner supporta gli aggiornamenti dello schema di un database, mentre continua a gestire traffico. Gli aggiornamenti dello schema non richiedono il database è offline e non bloccano intere tabelle o colonne; puoi continuare dei dati nel database durante l'aggiornamento dello schema. Scopri di più sui servizi supportati degli aggiornamenti dello schema e delle relative prestazioni in Aggiorna lo schema.

Aggiungi una colonna

Puoi aggiungere una colonna sulla riga di comando utilizzando Google Cloud CLI o programmaticamente utilizzando la libreria client Spanner per Python.

Nella riga di comando

Utilizza il seguente comando ALTER TABLE per aggiungi 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.

Usa la libreria client Spanner per Python

Utilizza la update_ddl() di Database per modificare lo schema:

def add_column(instance_id, database_id):
    """Adds a new column to the Albums table in the example database."""

    from google.cloud.spanner_admin_database_v1.types import \
        spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_admin_api.database_path(
            spanner_client.project, instance_id, database_id
        ),
        statements=[
            "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64",
        ],
    )

    operation = database_admin_api.update_database_ddl(request)

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)
    print("Added the MarketingBudget column.")

Esegui l'esempio utilizzando l'argomento add_column.

python 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 Albums(1, 1) e in 500000 per la riga con chiave di Albums(2, 2).

def update_data(instance_id, database_id):
    """Updates sample data in the database.

    This updates the `MarketingBudget` column which must be created before
    running this sample. You can add the column by running the `add_column`
    sample or by running this DDL statement against your database:

        ALTER TABLE Albums ADD COLUMN MarketingBudget INT64

    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.batch() as batch:
        batch.update(
            table="Albums",
            columns=("SingerId", "AlbumId", "MarketingBudget"),
            values=[(1, 1, 100000), (2, 2, 500000)],
        )

    print("Updated data.")

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 appena scritti.

Ecco il codice per eseguire la query:

def query_data_with_new_column(instance_id, database_id):
    """Queries sample data from the database using SQL.

    This sample uses the `MarketingBudget` column. You can add the column
    by running the `add_column` sample or by running this DDL statement against
    your database:

        ALTER TABLE Albums ADD COLUMN MarketingBudget INT64
    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        results = snapshot.execute_sql(
            "SELECT SingerId, AlbumId, MarketingBudget FROM Albums"
        )

        for row in results:
            print("SingerId: {}, AlbumId: {}, MarketingBudget: {}".format(*row))

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

Aggiornare i dati

Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.

Utilizzi il metodo execute_update() per eseguire un'istruzione DML.

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"

spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

def transfer_budget(transaction):
    # Transfer marketing budget from one album to another. Performed in a
    # single transaction to ensure that the transfer is atomic.
    second_album_result = transaction.execute_sql(
        "SELECT MarketingBudget from Albums " "WHERE SingerId = 2 and AlbumId = 2"
    )
    second_album_row = list(second_album_result)[0]
    second_album_budget = second_album_row[0]

    transfer_amount = 200000

    # Transaction will only be committed if this condition still holds at
    # the time of commit. Otherwise it will be aborted and the callable
    # will be rerun by the client library
    if second_album_budget >= transfer_amount:
        first_album_result = transaction.execute_sql(
            "SELECT MarketingBudget from Albums "
            "WHERE SingerId = 1 and AlbumId = 1"
        )
        first_album_row = list(first_album_result)[0]
        first_album_budget = first_album_row[0]

        second_album_budget -= transfer_amount
        first_album_budget += transfer_amount

        # Update first album
        transaction.execute_update(
            "UPDATE Albums "
            "SET MarketingBudget = @AlbumBudget "
            "WHERE SingerId = 1 and AlbumId = 1",
            params={"AlbumBudget": first_album_budget},
            param_types={"AlbumBudget": spanner.param_types.INT64},
        )

        # Update second album
        transaction.execute_update(
            "UPDATE Albums "
            "SET MarketingBudget = @AlbumBudget "
            "WHERE SingerId = 2 and AlbumId = 2",
            params={"AlbumBudget": second_album_budget},
            param_types={"AlbumBudget": spanner.param_types.INT64},
        )

        print(
            "Transferred {} from Album2's budget to Album1's".format(
                transfer_amount
            )
        )

database.run_in_transaction(transfer_budget)

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

Utilizzare un indice secondario

Supponiamo di voler recuperare tutte le righe di Albums con valori AlbumTitle in un determinato intervallo. Puoi leggere tutti i valori dalla colonna AlbumTitle utilizzando un'istruzione SQL o una chiamata di lettura, quindi ignora le righe che non soddisfano le ma l'esecuzione di questa scansione completa della tabella è costosa, soprattutto per le tabelle con molte righe. Puoi accelerare il recupero delle righe quando Cercare in base a colonne non di chiave primaria creando un indice secondario nella tabella.

L'aggiunta di un indice secondario a una tabella esistente richiede un aggiornamento dello schema. Mi piace altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice, mentre continua a gestire traffico. Spanner esegue automaticamente il backfill l'indicizzazione con i dati esistenti. Il completamento dei backfill potrebbe richiedere alcuni minuti ma non è necessario mettere offline il database o evitare di scrivere nell'elenco durante questo processo. Per ulteriori dettagli, vedi Aggiungi un indice secondario.

Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per le query SQL che potrebbero essere eseguite più velocemente con l'indice. Se utilizzi lo strumento devi specificare l'indice che vuoi utilizzare.

Aggiungi un indice secondario

Puoi aggiungere un indice dalla riga di comando utilizzando gcloud CLI in modo programmatico usando la libreria client 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 metodo update_ddl() della classe Database per aggiungere un indice:

def add_index(instance_id, database_id):
    """Adds a simple index to the example database."""

    from google.cloud.spanner_admin_database_v1.types import \
        spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_admin_api.database_path(
            spanner_client.project, instance_id, database_id
        ),
        statements=["CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"],
    )

    operation = database_admin_api.update_database_ddl(request)

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Added the AlbumsByAlbumTitle index.")

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. Una volta aggiunto l'indice, consulta:

Added the AlbumsByAlbumTitle index.

Leggi utilizzando l'indice

Per le query SQL, Spanner utilizza automaticamente un indice appropriato. Nella 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() del metodo Database in un estratto conto with.

def read_data_with_index(instance_id, database_id):
    """Reads sample data from the database using an index.

    The index must exist before running this sample. You can add the index
    by running the `add_index` sample or by running this DDL statement against
    your database:

        CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)

    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        keyset = spanner.KeySet(all_=True)
        results = snapshot.read(
            table="Albums",
            columns=("AlbumId", "AlbumTitle"),
            keyset=keyset,
            index="AlbumsByAlbumTitle",
        )

        for row in results:
            print("AlbumId: {}, AlbumTitle: {}".format(*row))

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 dell'indice

Potresti aver notato che l'esempio di lettura precedente non include la lettura la 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 valori che non sono archiviati nell'indice.

Crea una definizione alternativa di AlbumsByAlbumTitle che memorizzi 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 la update_ddl() di Database per aggiungere un indice con una clausola STORING:

def add_storing_index(instance_id, database_id):
    """Adds an storing index to the example database."""

    from google.cloud.spanner_admin_database_v1.types import \
        spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_admin_api.database_path(
            spanner_client.project, instance_id, database_id
        ),
        statements=[
            "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle)"
            "STORING (MarketingBudget)"
        ],
    )

    operation = database_admin_api.update_database_ddl(request)

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Added the AlbumsByAlbumTitle2 index.")

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 tutti i valori AlbumId, AlbumTitle e MarketingBudget colonne dall'indice AlbumsByAlbumTitle2:

def read_data_with_storing_index(instance_id, database_id):
    """Reads sample data from the database using an index with a storing
    clause.

    The index must exist before running this sample. You can add the index
    by running the `add_scoring_index` sample or by running this DDL statement
    against your database:

        CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle)
        STORING (MarketingBudget)

    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        keyset = spanner.KeySet(all_=True)
        results = snapshot.read(
            table="Albums",
            columns=("AlbumId", "AlbumTitle", "MarketingBudget"),
            keyset=keyset,
            index="AlbumsByAlbumTitle2",
        )

        for row in results:
            print("AlbumId: {}, AlbumTitle: {}, " "MarketingBudget: {}".format(*row))

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

Recuperare i dati utilizzando le transazioni di sola lettura

Supponiamo di voler eseguire più di una lettura per lo stesso timestamp. Sola lettura transazioni osservano una coerenza della cronologia di commit delle transazioni, in modo che l'applicazione la coerenza dei dati. Utilizza un oggetto Snapshot per eseguire transazioni di sola lettura. Per ottenere un oggetto Snapshot, chiama il metodo snapshot() di Database in un'istruzione with.

Di seguito viene illustrato come eseguire una query ed eseguire una lettura nella stessa sessione transazione:

def read_only_transaction(instance_id, database_id):
    """Reads data inside of a read-only transaction.

    Within the read-only transaction, or "snapshot", the application sees
    consistent view of the database at a particular timestamp.
    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot(multi_use=True) as snapshot:
        # Read using SQL.
        results = snapshot.execute_sql(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums"
        )

        print("Results from first read:")
        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

        # Perform another read using the `read` method. Even if the data
        # is updated in-between the reads, the snapshot ensures that both
        # return the same data.
        keyset = spanner.KeySet(all_=True)
        results = snapshot.read(
            table="Albums", columns=("SingerId", "AlbumId", "AlbumTitle"), keyset=keyset
        )

        print("Results from second read:")
        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

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 usate in questo tutorial, elimina il database ed elimina 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 (dovresti sono comunque addebitati costi per l'istanza).

Nella riga di comando

gcloud spanner databases delete example-db --instance=test-instance

Utilizzo della console Google Cloud

  1. Vai alla pagina Istanze Spanner nella console Google Cloud.

    Vai alla pagina Istanze

  2. Fai clic sull'istanza.

  3. Fai clic sul database che vuoi eliminare.

  4. Nella pagina Dettagli database, fai clic su Elimina.

  5. Conferma di voler eliminare il database e fai clic su Elimina.

Elimina l'istanza

L'eliminazione di un'istanza elimina automaticamente tutti i database creati al suo interno.

Nella riga di comando

gcloud spanner instances delete test-instance

Utilizzo della console Google Cloud

  1. Vai alla pagina Istanze Spanner nella console Google Cloud.

    Vai alla pagina Istanze

  2. Fai clic sull'istanza.

  3. Fai clic su Elimina.

  4. Conferma di voler eliminare l'istanza e fai clic su Elimina.

Passaggi successivi