Premiers pas avec Spanner en Python

Objectifs

Ce tutoriel vous montre comment effectuer les opérations suivantes à l'aide de la bibliothèque cliente Spanner pour Python:

Créer une instance et une base de données Spanner
Écrire ou lire des données dans la base de données, et exécuter des requêtes SQL sur ces données
Mettre à jour le schéma de base de données
Mettre à jour les données à l'aide d'une transaction en lecture/écriture
Ajouter un index secondaire à la base de données
Utiliser l'index pour lire et exécuter des requêtes SQL sur des données
Récupérer des données à l'aide d'une transaction en lecture seule

Coûts

Ce tutoriel utilise Spanner, un composant facturable de Google Cloud. Pour en savoir plus sur le coût d'utilisation de Spanner, consultez la page Tarifs.

Avant de commencer

Pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner, suivez les étapes décrites dans la section dédiée à la configuration qui traite des sujets suivants : création et définition d'un projet Google Cloud par défaut, activation de la facturation ainsi que de l'API Cloud Spanner, et configuration d'OAuth 2.0.

Veillez en particulier à exécuter gcloud auth application-default login pour configurer votre environnement de développement local avec des identifiants d'authentification.

Préparer votre environnement Python local

Suivez les instructions de la page Configurer un environnement de développement Python.
Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
```
git clone https://github.com/googleapis/python-spanner
```
Vous pouvez également télécharger l'exemple en tant que fichier zip et l'extraire.
Accédez au répertoire qui contient l'exemple de code Spanner:
```
cd python-spanner/samples/samples
```

Créez un environnement Python isolé et installez des dépendances :

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

Créer une instance

Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, qui alloue les ressources utilisées par les bases de données Spanner. Lorsque vous créez une instance, vous choisissez une configuration d'instance, qui détermine l'emplacement de stockage de vos données et le nombre de nœuds à utiliser. Ce dernier paramètre définit la quantité de ressources disponibles dans votre instance pour le stockage et la diffusion.

Exécutez la commande suivante pour créer une instance Spanner dans la région us-central1 avec un nœud:

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

Cette commande crée une instance présentant les caractéristiques suivantes :

ID d'instance : test-instance
Nom à afficher : Test Instance
Configuration d'instance : regional-us-central1 (Les configurations régionales stockent les données dans une région, tandis que les configurations multirégionales les distribuent dans plusieurs régions. Pour en savoir plus, consultez À propos des instances.)
Nombre de nœuds : 1 (node_count correspond à la quantité de ressources de stockage et de diffusion disponibles pour les bases de données de l'instance. Pour en savoir plus, consultez la section Nœuds et unités de traitement.)

Vous devriez obtenir le résultat suivant :

Creating instance...done.

Consulter des exemples de fichiers

Le dépôt d'exemples contient un exemple qui montre comment utiliser Spanner avec Python.

Examinez le fichier snippets.py, qui montre comment utiliser Spanner. Le code indique comment créer et utiliser une base de données. Les données utilisent l'exemple de schéma présenté sur la page Schéma et modèle de données.

Créer une base de données

Créez une base de données nommée example-db dans l'instance test-instance en exécutant la commande suivante dans la ligne de commande.

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

Vous devriez obtenir le résultat suivant :

Created database example-db on instance test-instance

Le code suivant crée une base de données et deux tables dans la base de données.

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

L'étape suivante consiste à écrire des données dans la base de données.

Créer un client de base de données

Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer un objet Client. Vous pouvez considérer un objet Client comme une connexion à une base de données. Toutes vos interactions avec Spanner doivent s'effectuer par le biais de cet objet Client. En général, vous devez créer un objet Client lorsque votre application démarre. Vous réutiliserez ensuite cet objet Client pour lire, écrire et exécuter des transactions. Le code ci-dessous montre comment créer 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)

Pour en savoir plus, consultez la documentation de référence sur Client.

Écrire des données avec le langage LMD

Vous pouvez insérer des données à l'aide du langage de manipulation de données (LMD) dans une transaction en lecture/écriture.

L'exécution d'une instruction LMD s'effectue via la méthode execute_update().

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

Exécutez l'exemple en utilisant l'argument insert_with_dml.

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

Vous devriez obtenir le résultat suivant :

4 record(s) inserted.

Écrire des données avec des mutations

Vous pouvez également insérer des données à l'aide de mutations.

Vous pouvez écrire des données à l'aide d'un objet Batch. Un objet Batch est un conteneur pour les opérations de mutation. Une mutation représente une séquence d'insertions, de mises à jour et de suppressions que Spanner applique de manière atomique à différentes lignes et tables d'une base de données Spanner.

La méthode insert() de la classe Batch ajoute une ou plusieurs mutations au lot. Toutes les mutations d'un même lot sont appliquées de manière atomique.

Le code ci-dessous montre comment écrire les données à l'aide de mutations :

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

Exécutez l'exemple en utilisant l'argument insert_data.

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

Vous devriez obtenir le résultat suivant :

Inserted data.

Interroger des données à l'aide de SQL

Spanner accepte une interface SQL pour la lecture des données. Vous pouvez accéder à cette interface via la ligne de commande à l'aide de Google Cloud CLI ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Python.

Sur la ligne de commande

Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums :

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

Vous devez obtenir le résultat suivant :

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

Utiliser la bibliothèque cliente Spanner pour Python

Vous pouvez non seulement exécuter une instruction SQL via la ligne de commande, mais également appliquer la même instruction SQL de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Python.

Pour exécuter la requête SQL, utilisez la méthode execute_sql() d'un objet Snapshot. Pour obtenir un objet Snapshot, appelez la méthode snapshot() de la classe Database dans une instruction with.

Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.

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

Exécutez l'exemple en utilisant l'argument query_data.

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

Vous devriez obtenir le résultat suivant :

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

Requête utilisant un paramètre SQL

Si votre application exécute une requête fréquemment, vous pouvez améliorer ses performances en la paramétrant. La requête paramétrique résultante peut être mise en cache et réutilisée, ce qui réduit les coûts de compilation. Pour en savoir plus, consultez la section Utiliser des paramètres de requête pour accélérer les requêtes fréquemment exécutées.

Voici un exemple d'utilisation d'un paramètre de la clause WHERE pour interroger des enregistrements contenant une valeur spécifique pour 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))

Exécutez l'exemple en utilisant l'argument query_data_with_parameter :

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

Vous devriez obtenir le résultat suivant :

SingerId: 12, FirstName: Melissa, LastName: Garcia

Lire des données à l'aide de l'API de lecture

En plus de son interface SQL, Spanner accepte également une interface de lecture.

Pour lire les lignes de la base de données, utilisez la méthode read() d'un objet Snapshot. Pour obtenir un objet Snapshot, appelez la méthode snapshot() de la classe Database dans une instruction with. Utilisez un objet KeySet pour définir une collection de clés et de plages de clés à lire.

Le code ci-dessous permet de lire les données.

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

Exécutez l'exemple en utilisant l'argument read_data.

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

Un résultat semblable à celui-ci s'affiche :

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

Mettre à jour le schéma de base de données

Supposons que vous deviez ajouter la colonne MarketingBudget à la table Albums. L'ajout d'une colonne à une table existante nécessite une mise à jour du schéma de base de données. Spanner permet de mettre à jour le schéma d'une base de données pendant que celle-ci continue de diffuser le trafic. Les mises à jour de schéma ne nécessitent pas de mettre la base de données hors connexion et ne verrouillent pas des tables ou des colonnes entières. Vous pouvez continuer à écrire des données dans la base de données pendant la mise à jour du schéma. Pour en savoir plus sur les mises à jour de schéma acceptées et les performances liées aux modifications de schéma, consultez la page Effectuer des mises à jour de schéma.

Ajouter une colonne

Vous pouvez ajouter une colonne via la ligne de commande à l'aide de Google Cloud CLI, ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Python.

Sur la ligne de commande

Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE suivante :

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'

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Python

Utilisez la méthode update_ddl() de la classe Database pour modifier le schéma:

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

Exécutez l'exemple en utilisant l'argument add_column.

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

Vous devriez voir les éléments suivants :

Added the MarketingBudget column.

Écrire des données dans la nouvelle colonne

Le code ci-dessous permet d'écrire des données dans la nouvelle colonne. Il définit MarketingBudget sur 100000 pour la ligne correspondant à la clé Albums(1, 1) et sur 500000 pour la ligne correspondant à la clé 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.")

Exécutez l'exemple en utilisant l'argument update_data.

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

Vous pouvez également exécuter une requête SQL ou un appel de lecture pour récupérer les valeurs que vous venez d'écrire.

Le code permettant d'exécuter la requête est présenté ci-dessous.

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

Pour mettre en œuvre cette requête, exécutez l'exemple en utilisant l'argument query_data_with_new_column.

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

Vous devriez obtenir le résultat suivant :

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

Mettre à jour des données

Vous pouvez mettre à jour des données à l'aide du langage LMD dans une transaction en lecture/écriture.

L'exécution d'une instruction LMD s'effectue via la méthode execute_update().

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

Exécutez l'exemple en utilisant l'argument write_with_dml_transaction.

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

Vous devriez voir les éléments suivants :

Transferred 200000 from Album2's budget to Album1's

Utiliser un index secondaire

Supposons que vous vouliez récupérer toutes les lignes de la table Albums dont les valeurs AlbumTitle sont comprises dans une certaine plage. Vous pouvez lire toutes les valeurs de la colonne AlbumTitle à l'aide d'une instruction SQL ou d'un appel de lecture, puis supprimer les lignes qui ne correspondent pas aux critères. Toutefois, cette analyse complète de la table est coûteuse, en particulier si celle-ci comporte beaucoup de lignes. Vous pouvez accélérer la récupération des lignes lors des recherches effectuées en fonction des colonnes de clé non primaire en créant un index secondaire pour la table.

L'ajout d'un index secondaire à une table existante nécessite une mise à jour du schéma. Comme les autres mises à jour de schéma, Spanner permet l'ajout d'un index pendant que la base de données continue de diffuser du trafic. Spanner remplit automatiquement l'index avec vos données existantes. Les remplissages peuvent prendre quelques minutes. Toutefois, ce processus ne requiert pas la mise hors connexion de la base de données et ne vous empêche pas d'écrire dans la table indexée. Pour en savoir plus, consultez Ajouter un index secondaire.

Une fois que vous avez ajouté un index secondaire, Spanner l'utilise automatiquement pour les requêtes SQL susceptibles de s'exécuter plus rapidement avec l'index. Si vous utilisez l'interface de lecture, vous devez spécifier l'index que vous souhaitez utiliser.

Ajouter un index secondaire

Vous pouvez ajouter un index via la ligne de commande à l'aide de la gcloud CLI ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Python.

Sur la ligne de commande

Exécutez la commande CREATE INDEX suivante pour ajouter un index à la base de données :

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

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Python

Utilisez la méthode update_ddl() de la classe Database pour ajouter un index:

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

Exécutez l'exemple en utilisant l'argument add_index.

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

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Added the AlbumsByAlbumTitle index.

Lire des données avec l'index

Pour les requêtes SQL, Spanner utilise automatiquement un index approprié. Dans l'interface de lecture, vous devez spécifier l'index dans votre requête.

Pour utiliser l'index dans l'interface de lecture, indiquez un argument Index à la méthode read() d'un objet Snapshot. Pour obtenir un objet Snapshot, appelez la méthode snapshot() de la classe Database dans une instruction 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))

Exécutez l'exemple en utilisant l'argument read_data_with_index.

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

Vous devriez obtenir le résultat suivant :

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

Ajouter un index pour les lectures sur index uniquement

Vous avez peut-être remarqué que l'exemple de lecture précédent n'inclut pas la lecture de la colonne MarketingBudget. En effet, l'interface de lecture de Spanner ne permet pas de joindre un index à une table de données pour rechercher des valeurs qui ne sont pas stockées dans l'index.

Créez une autre définition de l'index AlbumsByAlbumTitle qui stocke dans l'index une copie de MarketingBudget.

Sur la ligne de commande

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'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Python

Utilisez la méthode update_ddl() de la classe Database pour ajouter un index avec une clause 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.")

Exécutez l'exemple en utilisant l'argument add_storing_index.

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

Vous devriez voir les éléments suivants :

Added the AlbumsByAlbumTitle2 index.

Vous pouvez maintenant exécuter une opération de lecture permettant de récupérer toutes les colonnes AlbumId, AlbumTitle et MarketingBudget à partir de l'index 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))

Exécutez l'exemple en utilisant l'argument read_data_with_storing_index.

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

Un résultat semblable à celui-ci s'affiche :

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

Récupérer des données à l'aide de transactions en lecture seule

Supposons que vous souhaitiez exécuter plusieurs opérations de lecture avec le même horodatage. Les transactions en lecture seule tiennent compte d'un préfixe cohérent de l'historique de commit des transactions, de sorte que votre application obtienne toujours des données cohérentes. Pour exécuter des transactions en lecture seule, utilisez un objet Snapshot. Pour obtenir un objet Snapshot, appelez la méthode snapshot() de la classe Database dans une instruction with.

L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.

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

Exécutez l'exemple en utilisant l'argument read_only_transaction.

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

Un résultat semblable à celui-ci s'affiche :

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

Nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Cloud Billing pour les ressources utilisées dans ce tutoriel, supprimez la base de données et l'instance que vous avez créées.

Supprimer la base de données

Si vous supprimez une instance, toutes les bases de données qu'elle contient sont automatiquement supprimées. Cette étape montre comment supprimer une base de données sans supprimer l'instance. Des frais continueront à vous être facturés pour cette dernière.

Sur la ligne de commande

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

Utiliser la console Google Cloud

Accédez à la page Instances de Spanner dans la console Google Cloud.

Accéder à la page Instances
Cliquez sur l'instance.
Cliquez sur la base de données que vous souhaitez supprimer.
Sur la page Détails de la base de données, cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer la base de données, puis cliquez sur Supprimer.

Supprimer l'instance

La suppression d'une instance supprime automatiquement toutes les bases de données créées dans cette instance.

Sur la ligne de commande

gcloud spanner instances delete test-instance

Utiliser la console Google Cloud

Accédez à la page Instances de Spanner dans la console Google Cloud.

Accéder à la page Instances
Cliquez sur votre instance.
Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.

Étapes suivantes

Découvrez comment accéder à Spanner à l'aide d'une instance de machine virtuelle.
Pour en savoir plus sur les identifiants d'autorisation et d'authentification, consultez la section S'authentifier auprès des services cloud à l'aide de bibliothèques clientes.
En savoir plus sur les bonnes pratiques de conception de schémas Spanner.