Esta página se ha traducido con Cloud Translation API.

Introducción a Spanner en Python
Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Objetivos

Este tutorial lo guiará a través de los siguientes pasos utilizando la biblioteca cliente Spanner para Python:

Cree una instancia y una base de datos de Spanner.
Escribir, leer y ejecutar consultas SQL sobre datos de la base de datos.
Actualizar el esquema de la base de datos.
Actualizar datos mediante una transacción de lectura y escritura.
Agregar un índice secundario a la base de datos.
Utilice el índice para leer y ejecutar consultas SQL sobre los datos.
Recupere datos mediante una transacción de solo lectura.

Costos

Este tutorial utiliza Spanner, que es un componente facturable deGoogle CloudPara obtener información sobre el costo de usar Spanner, consulte Precios .

Antes de empezar

Complete los pasos descritos en Configuración , que cubren la creación y configuración de un valor predeterminado. Google Cloud proyecto, habilitar la facturación, habilitar la API de Cloud Spanner y configurar OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.

En particular, asegúrese de ejecutar gcloud auth application-default login para configurar su entorno de desarrollo local con credenciales de autenticación.

Nota: Si no planea conservar los recursos que cree en este tutorial, considere crear uno nuevo. Google Cloud proyecto en lugar de seleccionar uno existente. Tras finalizar el tutorial, puede eliminar el proyecto y así eliminar todos los recursos asociados.

Prepare su entorno local de Python

Siga las instrucciones en Configuración de un entorno de desarrollo de Python .
Clone el repositorio de aplicaciones de muestra en su máquina local:
```
git clone https://github.com/googleapis/python-spanner
```
Alternativamente, puede descargar la muestra como un archivo zip y extraerlo.
Cambie al directorio que contiene el código de muestra de Spanner:
```
cd python-spanner/samples/samples
```

Cree un entorno de Python aislado e instale las dependencias:

virtualenv env
source env/bin/activate
pip install -r requirements.txt

Crear una instancia

Al usar Spanner por primera vez, debe crear una instancia, que consiste en una asignación de recursos que utilizan las bases de datos de Spanner. Al crear una instancia, se elige una configuración que determina dónde se almacenan los datos y el número de nodos a usar, lo que determina la cantidad de recursos de servicio y almacenamiento en la instancia.

Ejecute el siguiente comando para crear una instancia de Spanner en la región us-central1 con 1 nodo:

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

Tenga en cuenta que esto crea una instancia con las siguientes características:

ID de instancia test-instance
Nombre para mostrar Test Instance
Configuración de instancia regional-us-central1 (las configuraciones regionales almacenan datos en una región, mientras que las configuraciones multirregionales distribuyen datos entre varias regiones. Para obtener más información, consulte Acerca de las instancias ).
Cantidad de nodos de 1 ( node_count corresponde a la cantidad de recursos de servicio y almacenamiento disponibles para las bases de datos en la instancia. Obtenga más información en Nodos y unidades de procesamiento ).

Deberías ver:

Creating instance...done.

Mirar archivos de muestra

El repositorio de muestras contiene un ejemplo que muestra cómo utilizar Spanner con Python.

Revise el archivo snippets.py , que muestra cómo usar Spanner. El código muestra cómo crear y usar una nueva base de datos. Los datos utilizan el esquema de ejemplo que se muestra en la página Esquema y modelo de datos .

Crear una base de datos

Google SQL

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

PostgreSQL

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

Deberías ver:

Created database example-db on instance test-instance

El siguiente código crea una base de datos y dos tablas en la base de datos.

Google SQL

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),
        )
    )

PostgreSQL

def create_database(instance_id, database_id):
    """Creates a PostgreSql 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}"',
        database_dialect=DatabaseDialect.POSTGRESQL,
    )

    operation = database_admin_api.create_database(request=request)

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

    create_table_using_ddl(database.name)
    print("Created database {} on instance {}".format(database_id, instance_id))


def create_table_using_ddl(database_name):
    from google.cloud.spanner_admin_database_v1.types import \
        spanner_database_admin

    spanner_client = spanner.Client()
    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_name,
        statements=[
            """CREATE TABLE Singers (
  SingerId   bigint NOT NULL,
  FirstName  character varying(1024),
  LastName   character varying(1024),
  SingerInfo bytea,
  FullName   character varying(2048)
    GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED,
  PRIMARY KEY (SingerId)
  )""",
            """CREATE TABLE Albums (
  SingerId     bigint NOT NULL,
  AlbumId      bigint NOT NULL,
  AlbumTitle   character varying(1024),
  PRIMARY KEY (SingerId, AlbumId)
  ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE""",
        ],
    )
    operation = spanner_client.database_admin_api.update_database_ddl(request)
    operation.result(OPERATION_TIMEOUT_SECONDS)

El siguiente paso es escribir datos en su base de datos.

Crear un cliente de base de datos

Antes de poder realizar operaciones de lectura o escritura, debe crear un Client . Un Client es como una conexión a una base de datos: todas sus interacciones con Spanner deben pasar por Client . Normalmente, se crea un Client al iniciar la aplicación y luego se Client para leer, escribir y ejecutar transacciones. El siguiente código muestra cómo crear un cliente.

# 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)

Lea más en la referencia Client .

Escribir datos con DML

Puede insertar datos utilizando el lenguaje de manipulación de datos (DML) en una transacción de lectura y escritura.

Utilice el método execute_update() para ejecutar una declaración 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)

Ejecute la muestra utilizando el argumento insert_with_dml .

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

Deberías ver:

4 record(s) inserted.

Escribir datos con mutaciones

También puedes insertar datos usando mutaciones .

Los datos se escriben mediante un objeto Batch . Un objeto Batch es un contenedor para operaciones de mutación. Una mutación representa una secuencia de inserciones, actualizaciones y eliminaciones que Spanner aplica automáticamente a diferentes filas y tablas de una base de datos Spanner.

El método insert() de la clase Batch añade una o más mutaciones de inserción al lote. Todas las mutaciones de un lote se aplican automáticamente.

Este código muestra cómo escribir los datos usando mutaciones:

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.")

Ejecute la muestra utilizando el argumento insert_data .

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

Deberías ver:

Inserted data.

Consultar datos mediante SQL

Spanner admite una interfaz SQL para leer datos, a la que puedes acceder en la línea de comandos mediante la CLI de Google Cloud o mediante programación mediante la biblioteca cliente Spanner para Python.

En la línea de comandos

Ejecute la siguiente declaración SQL para leer los valores de todas las columnas de la tabla Albums :

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

El resultado debería ser:

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

Utilice la biblioteca cliente Spanner para Python

Además de ejecutar una declaración SQL en la línea de comandos, puede emitir la misma declaración SQL mediante programación utilizando la biblioteca cliente Spanner para Python.

Utilice el método execute_sql() de un objeto Snapshot para ejecutar la consulta SQL. Para obtener un objeto Snapshot , llame al método snapshot() de la clase Database en una instrucción with .

A continuación se explica cómo emitir la consulta y acceder a los datos:

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))

Ejecute la muestra utilizando el argumento query_data .

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

Deberías ver el siguiente resultado:

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

Consulta utilizando un parámetro SQL

Si su aplicación tiene una consulta que se ejecuta con frecuencia, puede mejorar su rendimiento parametrizándola. La consulta paramétrica resultante puede almacenarse en caché y reutilizarse, lo que reduce los costos de compilación. Para obtener más información, consulte Usar parámetros de consulta para acelerar las consultas que se ejecutan con frecuencia .

A continuación se muestra un ejemplo del uso de un parámetro en la cláusula WHERE para consultar registros que contienen un valor específico para 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))

Ejecute la muestra utilizando el argumento query_data_with_parameter.

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

Deberías ver el siguiente resultado:

SingerId: 12, FirstName: Melissa, LastName: Garcia

Leer datos usando la API de lectura

Además de la interfaz SQL de Spanner, Spanner también admite una interfaz de lectura.

Utilice el método read() de un objeto Snapshot para leer filas de la base de datos. Para obtener un objeto Snapshot , llame al método snapshot() de la clase Database en una instrucción ` with . Utilice un objeto KeySet para definir una colección de claves y rangos de claves para leer.

Aquí se explica cómo leer los datos:

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))

Ejecute la muestra utilizando el argumento read_data .

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

Debería ver un resultado similar a este:

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

Actualizar el esquema de la base de datos

Supongamos que necesita agregar una nueva columna llamada MarketingBudget a la tabla Albums . Agregar una nueva columna a una tabla existente requiere actualizar el esquema de su base de datos. Spanner admite actualizaciones de esquema en una base de datos mientras esta continúa gestionando el tráfico. Las actualizaciones de esquema no requieren desconectar la base de datos ni bloquean tablas o columnas completas; puede seguir escribiendo datos en la base de datos durante la actualización del esquema. Obtenga más información sobre las actualizaciones de esquema admitidas y el rendimiento de los cambios de esquema en Realizar actualizaciones de esquema .

Agregar una columna

Puede agregar una columna en la línea de comando mediante la CLI de Google Cloud o mediante programación utilizando la biblioteca cliente Spanner para Python.

En la línea de comandos

Utilice el siguiente comando ALTER TABLE para agregar la nueva columna a la tabla:

Google SQL

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'

Deberías ver:

Schema updating...done.

Utilice la biblioteca cliente Spanner para Python

Utilice el método update_ddl() de la clase Database para modificar el esquema:

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.")

Ejecute la muestra utilizando el argumento add_column .

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

Deberías ver:

Added the MarketingBudget column.

Escribir datos en la nueva columna

El siguiente código escribe datos en la nueva columna. Establece MarketingBudget en 100000 para la fila especificada por Albums(1, 1) y en 500000 para la fila especificada por 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.")

Ejecute la muestra utilizando el argumento update_data .

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

También puede ejecutar una consulta SQL o una llamada de lectura para obtener los valores que acaba de escribir.

Aquí está el código para ejecutar la consulta:

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))

Para ejecutar esta consulta, ejecute el ejemplo utilizando el argumento query_data_with_new_column .

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

Deberías ver:

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

Actualizar datos

Puede actualizar datos utilizando DML en una transacción de lectura y escritura.

Utilice el método execute_update() para ejecutar una declaración 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)

Ejecute la muestra utilizando el argumento write_with_dml_transaction .

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

Deberías ver:

Transferred 200000 from Album2's budget to Album1's

Utilice un índice secundario

Supongamos que desea obtener todas las filas de Albums con valores AlbumTitle dentro de un rango determinado. Podría leer todos los valores de la columna AlbumTitle mediante una sentencia SQL o una llamada de lectura y luego descartar las filas que no cumplan los criterios. Sin embargo, realizar este análisis completo de la tabla es costoso, especialmente en tablas con muchas filas. En su lugar, puede acelerar la recuperación de filas al buscar por columnas que no sean de clave principal creando un índice secundario en la tabla.

Añadir un índice secundario a una tabla existente requiere una actualización del esquema. Al igual que otras actualizaciones de esquema, Spanner permite añadir un índice mientras la base de datos sigue gestionando el tráfico. Spanner rellena automáticamente el índice con los datos existentes. El proceso de rellenado puede tardar unos minutos, pero no es necesario desconectar la base de datos ni evitar escribir en la tabla indexada durante el proceso. Para más información, consulte "Añadir un índice secundario" .

Tras agregar un índice secundario, Spanner lo usa automáticamente para las consultas SQL que probablemente se ejecuten más rápido con él. Si usa la interfaz de lectura, debe especificar el índice que desea usar.

Agregar un índice secundario

Puede agregar un índice en la línea de comando usando la CLI de gcloud o programáticamente usando la biblioteca cliente Spanner para Python.

En la línea de comandos

Utilice el siguiente comando CREATE INDEX para agregar un índice a la base de datos:

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'

Deberías ver:

Schema updating...done.

Uso de la biblioteca cliente Spanner para Python

Utilice el método update_ddl() de la clase Database para agregar un índice:

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.")

Ejecute la muestra utilizando el argumento add_index .

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

Añadir un índice puede tardar unos minutos. Una vez añadido, debería ver lo siguiente:

Added the AlbumsByAlbumTitle index.

Leer utilizando el índice

Para las consultas SQL, Spanner utiliza automáticamente un índice apropiado. En la interfaz de lectura, debe especificar el índice en su solicitud.

Para usar el índice en la interfaz de lectura, proporcione un argumento Index al método read() de un objeto Snapshot . Para obtener un objeto Snapshot , llame al método snapshot() de la clase Database en una instrucción " 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))

Ejecute la muestra utilizando el argumento read_data_with_index .

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

Deberías ver:

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

Agregar un índice para lecturas de solo índice

Quizás haya notado que el ejemplo de lectura anterior no incluye la lectura de la columna MarketingBudget . Esto se debe a que la interfaz de lectura de Spanner no permite unir un índice con una tabla de datos para buscar valores que no están almacenados en el índice.

Cree una definición alternativa de AlbumsByAlbumTitle que almacene una copia de MarketingBudget en el índice.

En la línea de comandos

Google SQL

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)

Añadir un índice puede tardar unos minutos. Una vez añadido, debería ver lo siguiente:

Schema updating...done.

Uso de la biblioteca cliente Spanner para Python

Utilice el método update_ddl() de la clase Database para agregar un índice con una cláusula 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.")

Ejecute la muestra utilizando el argumento add_storing_index .

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

Deberías ver:

Added the AlbumsByAlbumTitle2 index.

Ahora puede ejecutar una lectura que obtenga todas las columnas AlbumId , AlbumTitle y MarketingBudget del índice 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))

Ejecute la muestra utilizando el argumento read_data_with_storing_index .

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

Debería ver un resultado similar a este:

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

Recuperar datos mediante transacciones de solo lectura

Supongamos que desea ejecutar más de una lectura en la misma marca de tiempo. Las transacciones de solo lectura siguen un prefijo consistente del historial de confirmación de transacciones, por lo que su aplicación siempre recibe datos consistentes.

Utilice un objeto Snapshot para ejecutar transacciones de solo lectura. Para obtener un objeto Snapshot , llame al método snapshot() de la clase Database en una instrucción with .

A continuación se muestra cómo ejecutar una consulta y realizar una lectura en la misma transacción de solo lectura:

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))

Ejecute la muestra utilizando el argumento read_only_transaction .

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

Debería ver un resultado similar a este:

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

Limpieza

Para evitar incurrir en cargos adicionales en su cuenta de facturación de Cloud por los recursos utilizados en este tutorial, elimine la base de datos y borre la instancia que creó.

Eliminar la base de datos

Si elimina una instancia, todas sus bases de datos se eliminan automáticamente. Este paso muestra cómo eliminar una base de datos sin eliminar una instancia (aunque se le cobrarán cargos por la instancia).

En la línea de comandos

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

Usando el Google Cloud consola

Vaya a la página Instancias de Spanner en el Google Cloud consola.
Ir a la página de Instancias
Haga clic en la instancia.
Haga clic en la base de datos que desea eliminar.
En la página de detalles de la base de datos , haga clic en Eliminar .
Confirme que desea eliminar la base de datos y haga clic en Eliminar .

Eliminar la instancia

Al eliminar una instancia se eliminan automáticamente todas las bases de datos creadas en esa instancia.

En la línea de comandos

gcloud spanner instances delete test-instance

Usando el Google Cloud consola

Vaya a la página Instancias de Spanner en el Google Cloud consola.
Ir a la página de Instancias
Haga clic en su instancia.
Haga clic en Eliminar .
Confirme que desea eliminar la instancia y haga clic en Eliminar .

¿Qué sigue?

Aprenda cómo acceder a Spanner con una instancia de máquina virtual .
Obtenga información sobre las credenciales de autorización y autenticación en Autenticarse en servicios en la nube mediante bibliotecas de cliente .
Obtenga más información sobre las mejores prácticas de diseño de esquemas Spanner.

Introducción a Spanner en Python Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Objetivos

Costos

Antes de empezar

Limpieza

Eliminar la base de datos

En la línea de comandos

Usando el Google Cloud consola

Eliminar la instancia

En la línea de comandos

Usando el Google Cloud consola

¿Qué sigue?

Introducción a Spanner en Python
Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.