Primeros pasos con Cloud Spanner en Java

Objetivos

En este instructivo, se explican los siguientes pasos para usar la biblioteca cliente de Cloud Spanner en Java:

  • Crear una base de datos y una instancia de Cloud Spanner
  • Escribe, lee y ejecuta consultas de SQL sobre datos en la base de datos.
  • Actualiza el esquema de la base de datos.
  • Actualiza los datos mediante una transacción de lectura y escritura.
  • Agrega un índice secundario a la base de datos.
  • Usa el índice para leer y ejecutar consultas de SQL sobre datos.
  • Recupera datos con una transacción de solo lectura.

Costos

En este instructivo, se usa Cloud Spanner, que es un componente facturable de Google Cloud. Para obtener información sobre el costo de usar Cloud Spanner, consulta Precios.

Antes de comenzar

Completa los pasos descritos en Configuración, que abarcan la creación y configuración de un proyecto de Google Cloud predeterminado, la facturación, la habilitación de la API de Cloud Spanner y la configuración de OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.

En especial, asegúrate de ejecutar gcloud auth application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.

Prepara tu entorno local de Java

  1. Instala los siguientes componentes en tu máquina de desarrollo si aún no se instalaron:

  2. Clona el repositorio de la aplicación de muestra en tu máquina local con el siguiente comando:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples
    

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

  3. Ve al directorio que contiene el código de muestra de Cloud Spanner:

    cd java-docs-samples/spanner/cloud-client
    

Crea una instancia

Cuando usas Cloud Spanner por primera vez, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de Cloud Spanner. Cuando creas una instancia, debes elegir una configuración de instancia, que determina dónde se almacenan tus datos y también la cantidad de nodos que se usarán, lo que, a su vez, determina la cantidad de recursos de entrega y almacenamiento de tu instancia.

Ejecuta el siguiente comando para crear una instancia de Cloud 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

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

  • ID de instancia: test-instance
  • Nombre visible: Test Instance
  • Configuración de la instancia: regional-us-central1 (la configuración regional almacena datos en una región, mientras que la multirregional distribuye datos en varias regiones; obtén más información en Instancias)
  • Recuento de nodos: 1 (node_count corresponde a la cantidad de recursos de procesamiento y almacenamiento disponibles para las bases de datos de la instancia; obtén más información en Recuento de nodos)

Deberías ver lo siguiente:

Creating instance...done.

Examina archivos de muestra

El repositorio de muestras contiene una muestra que indica cómo usar Cloud Spanner con Java.

pom.xml agrega la biblioteca cliente de Cloud Spanner para Java a las dependencias del proyecto y configura el complemento de ensamble a fin de compilar un archivo JAR ejecutable con la clase Java definida en este instructivo.

Compila la muestra del directorio spanner/cloud-client:

mvn package

Crea una base de datos

Para crear una base de datos llamada example-db en la instancia test-instance, ejecuta lo siguiente en la línea de comandos.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    createdatabase test-instance example-db

Deberías ver lo siguiente:

Created database [example-db]

Acabas de crear una base de datos de Cloud Spanner. El siguiente es el código que creó la base de datos:

static void createDatabase(DatabaseAdminClient dbAdminClient, DatabaseId id) {
  OperationFuture<Database, CreateDatabaseMetadata> op =
      dbAdminClient.createDatabase(
          id.getInstanceId().getInstance(),
          id.getDatabase(),
          Arrays.asList(
              "CREATE TABLE Singers ("
                  + "  SingerId   INT64 NOT NULL,"
                  + "  FirstName  STRING(1024),"
                  + "  LastName   STRING(1024),"
                  + "  SingerInfo BYTES(MAX)"
                  + ") 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"));
  try {
    // Initiate the request which returns an OperationFuture.
    Database db = op.get();
    System.out.println("Created database [" + db.getId() + "]");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

El código también define dos tablas, Singers y Albums, para una aplicación básica de música. Ambas tablas se usan en toda la página. Si aún no lo has hecho, consulta el esquema de ejemplo.

El siguiente paso consiste en escribir datos en tu base de datos.

Crea un cliente de base de datos

Para realizar operaciones de lectura o escritura, debes crear un DatabaseClient. Un DatabaseClient es como una conexión de base de datos: todas tus interacciones con Cloud Spanner deben pasar por un DatabaseClient. Normalmente, cuando se inicia la aplicación, se crea un DatabaseClient y se vuelve a usar ese DatabaseClient para leer, escribir y ejecutar transacciones.

SpannerOptions options = SpannerOptions.newBuilder().build();
Spanner spanner = options.getService();
try {
  String command = args[0];
  DatabaseId db = DatabaseId.of(options.getProjectId(), args[1], args[2]);
  DatabaseClient dbClient = spanner.getDatabaseClient(db);
  DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();
  InstanceAdminClient instanceAdminClient = spanner.getInstanceAdminClient();
  // Use client here...

Cada cliente usa recursos en Cloud Spanner, por lo que se recomienda llamar a close() para cerrar los clientes innecesarios.

Obtén más información en la referencia de Javadoc DatabaseClient.

Escribe datos con DML

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

Usarás el método executeUpdate() para ejecutar una Declaración DML.

static void writeUsingDml(DatabaseClient dbClient) {
  // Insert 4 singer records
  dbClient
      .readWriteTransaction()
      .run(
          new TransactionCallable<Void>() {
            @Override
            public Void run(TransactionContext transaction) throws Exception {
              String sql =
                  "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
                      + "(12, 'Melissa', 'Garcia'), "
                      + "(13, 'Russell', 'Morales'), "
                      + "(14, 'Jacqueline', 'Long'), "
                      + "(15, 'Dylan', 'Shaw')";
              long rowCount = transaction.executeUpdate(Statement.of(sql));
              System.out.printf("%d records inserted.\n", rowCount);
              return null;
            }
          });
}

Ejecuta la muestra con el argumento writeusingdml.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    writeusingdml test-instance example-db

Debería ver lo siguiente:

4 records inserted.

Escribe datos con mutaciones

También puedes insertar datos mediante mutaciones.

Escribirás datos con un objeto Mutation. Un objeto Mutation es un contenedor para operaciones de mutación. Una Mutation representa una secuencia de inserciones, actualizaciones y eliminaciones que Cloud Spanner aplica de manera atómica a diferentes filas y tablas en una base de datos de Cloud Spanner.

El método newInsertBuilder() en la clase Mutation genera una mutación INSERT, que inserta una fila nueva en una tabla. Si la fila ya existe, la operación de escritura falla. Como alternativa, puedes usar el método newInsertOrUpdateBuilder para generar una mutación INSERT_OR_UPDATE, que actualiza los valores de la columna si la fila ya existe.

El método write() en la clase DatabaseClient escribe las mutaciones. Todas las mutaciones en un solo lote se aplican de forma atómica.

En este código, se muestra cómo escribir los datos mediante mutaciones:

static final List<Singer> SINGERS =
    Arrays.asList(
        new Singer(1, "Marc", "Richards"),
        new Singer(2, "Catalina", "Smith"),
        new Singer(3, "Alice", "Trentor"),
        new Singer(4, "Lea", "Martin"),
        new Singer(5, "David", "Lomond"));

static final List<Album> ALBUMS =
    Arrays.asList(
        new Album(1, 1, "Total Junk"),
        new Album(1, 2, "Go, Go, Go"),
        new Album(2, 1, "Green"),
        new Album(2, 2, "Forever Hold Your Peace"),
        new Album(2, 3, "Terrified"));
static void writeExampleData(DatabaseClient dbClient) {
  List<Mutation> mutations = new ArrayList<>();
  for (Singer singer : SINGERS) {
    mutations.add(
        Mutation.newInsertBuilder("Singers")
            .set("SingerId")
            .to(singer.singerId)
            .set("FirstName")
            .to(singer.firstName)
            .set("LastName")
            .to(singer.lastName)
            .build());
  }
  for (Album album : ALBUMS) {
    mutations.add(
        Mutation.newInsertBuilder("Albums")
            .set("SingerId")
            .to(album.singerId)
            .set("AlbumId")
            .to(album.albumId)
            .set("AlbumTitle")
            .to(album.albumTitle)
            .build());
  }
  dbClient.write(mutations);
}

Ejecuta la muestra con el argumento write.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    write test-instance example-db

Deberías ver que el comando se ejecuta con éxito.

Consulta datos mediante SQL

Cloud Spanner admite una interfaz nativa de SQL para leer datos, a la que puedes acceder desde la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para Java.

En la línea de comandos

Ejecuta la siguiente instrucción de 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 este:

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

Usa la biblioteca cliente de Cloud Spanner para Java

Además de ejecutar una instrucción de SQL en la línea de comandos, puedes emitir la misma instrucción de SQL de manera programática con la biblioteca cliente de Cloud Spanner para Java.

Los siguientes métodos y clases se usan para ejecutar la consulta de SQL:

  • Método singleUse() en la clase DatabaseClient: usa esto para leer el valor de una o más columnas de una o más filas en una tabla de Cloud Spanner. singleUse() muestra un objeto ReadContext, que se usa para ejecutar una operación de lectura o una instrucción de SQL.
  • Método executeQuery() de la clase ReadContext: usa este método para ejecutar una consulta en una base de datos.
  • Clase Statement: úsala para crear una string de SQL.
  • Clase ResultSet: úsala para acceder a los datos que muestra una instrucción de SQL o una llamada de lectura.

A continuación, se muestra cómo enviar la consulta y acceder a los datos:

static void query(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse() // Execute a single read or query against Cloud Spanner.
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

Ejecuta la muestra con el argumento query.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    query test-instance example-db

Deberías ver el siguiente resultado:

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

Realiza consultas con un parámetro de SQL

Puedes incluir valores personalizados en las instrucciones de SQL mediante parámetros. Este es un ejemplo del uso de @lastName como parámetro en la cláusula WHERE a fin de consultar registros que contienen un valor específico para LastName.

static void queryWithParameter(DatabaseClient dbClient) {
  Statement statement =
      Statement.newBuilder(
              "SELECT SingerId, FirstName, LastName "
                  + "FROM Singers "
                  + "WHERE LastName = @lastName")
          .bind("lastName")
          .to("Garcia")
          .build();
  try (ResultSet resultSet = dbClient.singleUse().executeQuery(statement)) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %s %s\n",
          resultSet.getLong("SingerId"),
          resultSet.getString("FirstName"),
          resultSet.getString("LastName"));
    }
  }
}

Ejecuta la muestra con el argumento queryWithParameter.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    querywithparameter test-instance example-db

Deberías ver el siguiente resultado:

12 Melissa Garcia

Lee datos con la API de lectura

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

Usa el método read() de la clase ReadContext para leer las filas de la base de datos. Usa un objeto KeySet para definir un conjunto de claves y rangos de claves que se leerán.

A continuación, te indicamos cómo leer los datos:

static void read(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .read(
              "Albums",
              KeySet.all(), // Read all rows in a table.
              Arrays.asList("SingerId", "AlbumId", "AlbumTitle"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

Ejecuta la muestra con el argumento read.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    read test-instance example-db

Deberías ver un resultado similar a este:

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

Actualiza el esquema de la base de datos

Supongamos que necesitas agregar una columna nueva llamada MarketingBudget a la tabla Albums. Para agregar una columna nueva a una tabla existente, es necesario actualizar el esquema de la base de datos. Cloud Spanner admite actualizaciones del esquema de una base de datos mientras esta sigue entregando tráfico. Las actualizaciones de esquema no requieren que la base de datos esté sin conexión y no bloquean tablas ni columnas completas. Puedes continuar escribiendo datos en la base de datos durante la actualización del esquema. Obtén más información sobre las actualizaciones admitidas del esquema y el rendimiento de los cambios de esquema en la página sobre actualizaciones de esquema.

Agrega una columna

Puedes agregar una columna en la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para Java.

En la línea de comandos

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

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

Deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para Java

Usa el método updateDatabaseDdl() de la clase DatabaseAdminClient para modificar el esquema:

static void addMarketingBudget(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient.updateDatabaseDdl(
          dbId.getInstanceId().getInstance(),
          dbId.getDatabase(),
          Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"),
          null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added MarketingBudget column");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

Ejecuta la muestra con el argumento addmarketingbudget.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    addmarketingbudget test-instance example-db

Deberías ver lo siguiente:

Added MarketingBudget column.

Escribe datos en la columna nueva

Con el siguiente código, se escriben datos en la columna nueva. Configura MarketingBudget en 100000 para la fila marcada por Albums(1, 1) y en 500000 para la fila marcada por Albums(2, 2).

static void update(DatabaseClient dbClient) {
  // Mutation can be used to update/insert/delete a single row in a table. Here we use
  // newUpdateBuilder to create update mutations.
  List<Mutation> mutations =
      Arrays.asList(
          Mutation.newUpdateBuilder("Albums")
              .set("SingerId")
              .to(1)
              .set("AlbumId")
              .to(1)
              .set("MarketingBudget")
              .to(100000)
              .build(),
          Mutation.newUpdateBuilder("Albums")
              .set("SingerId")
              .to(2)
              .set("AlbumId")
              .to(2)
              .set("MarketingBudget")
              .to(500000)
              .build());
  // This writes all the mutations to Cloud Spanner atomically.
  dbClient.write(mutations);
}

Ejecuta la muestra con el argumento update.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    update test-instance example-db

También puedes ejecutar una consulta de SQL o una llamada de lectura para recuperar los valores que acabas de escribir.

Este es el código para ejecutar la consulta:

static void queryMarketingBudget(DatabaseClient dbClient) {
  // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
  // null. A try-with-resource block is used to automatically release resources held by
  // ResultSet.
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n",
          resultSet.getLong("SingerId"),
          resultSet.getLong("AlbumId"),
          // We check that the value is non null. ResultSet getters can only be used to retrieve
          // non null values.
          resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"));
    }
  }
}

Para ejecutar esta consulta, ejecuta la muestra con el argumento querymarketingbudget.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    querymarketingbudget test-instance example-db

Deberías ver lo siguiente:

1 1 100000
1 2 NULL
2 1 NULL
2 2 500000
2 3 NULL

Actualiza datos

Puedes actualizar los datos mediante DML en una transacción de lectura y escritura.

Usarás el método executeUpdate() para ejecutar una Declaración DML.

static void writeWithTransactionUsingDml(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(
          new TransactionCallable<Void>() {
            @Override
            public Void run(TransactionContext transaction) throws Exception {
              // Transfer marketing budget from one album to another. We do it in a transaction to
              // ensure that the transfer is atomic.
              String sql1 =
                  "SELECT MarketingBudget from Albums WHERE SingerId = 2 and AlbumId = 2";
              ResultSet resultSet = transaction.executeQuery(Statement.of(sql1));
              long album2Budget = 0;
              while (resultSet.next()) {
                album2Budget = resultSet.getLong("MarketingBudget");
              }
              // 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.
              long transfer = 200000;
              if (album2Budget >= transfer) {
                String sql2 =
                    "SELECT MarketingBudget from Albums WHERE SingerId = 1 and AlbumId = 1";
                ResultSet resultSet2 = transaction.executeQuery(Statement.of(sql2));
                long album1Budget = 0;
                while (resultSet2.next()) {
                  album1Budget = resultSet2.getLong("MarketingBudget");
                }
                album1Budget += transfer;
                album2Budget -= transfer;
                Statement updateStatement =
                    Statement.newBuilder(
                            "UPDATE Albums "
                                + "SET MarketingBudget = @AlbumBudget "
                                + "WHERE SingerId = 1 and AlbumId = 1")
                        .bind("AlbumBudget")
                        .to(album1Budget)
                        .build();
                transaction.executeUpdate(updateStatement);
                Statement updateStatement2 =
                    Statement.newBuilder(
                            "UPDATE Albums "
                                + "SET MarketingBudget = @AlbumBudget "
                                + "WHERE SingerId = 2 and AlbumId = 2")
                        .bind("AlbumBudget")
                        .to(album2Budget)
                        .build();
                transaction.executeUpdate(updateStatement2);
              }
              return null;
            }
          });
}

Ejecuta la muestra con el argumento writewithtransactionusingdml.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    writewithtransactionusingdml test-instance example-db

Usa un índice secundario

Supongamos que deseas recuperar todas las filas de Albums que tienen valores AlbumTitle en un rango determinado. Puedes leer todos los valores de la columna AlbumTitle con una instrucción de SQL o una llamada de lectura y, luego, descartar las filas que no cumplan con los criterios. Sin embargo, analizar tablas enteras es costoso, especialmente si tienen muchas filas. En su lugar, crea un índice secundario en la tabla para acelerar la recuperación de filas cuando realizas búsquedas por columnas sin claves primarias.

Para agregar un índice secundario a una tabla existente, es necesario actualizar el esquema. Al igual que otras actualizaciones de esquema, Cloud Spanner admite que se agregue un índice mientras la base de datos continúa entregando tráfico. Cloud Spanner reabastece de manera automática el índice con tus datos existentes. Los reabastecimientos pueden tardar unos minutos en completarse, pero no es necesario que uses la base de datos sin conexión ni que evites escribir en la tabla indexada durante este proceso. Para obtener más detalles, consulta la sección sobre el reabastecimiento de índices.

Después de agregar un índice secundario, Cloud Spanner lo usa de forma automática en las consultas de SQL que probablemente se ejecuten más rápido con el índice. Si usas la interfaz de lectura, debes especificar el índice que deseas usar.

Agrega un índice secundario

Puedes agregar un índice en la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para Java.

En la línea de comandos

Usa 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 lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para Java

Usa el método updateDatabaseDdl() de la clase DatabaseAdminClient para agregar un índice:

static void addIndex(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient.updateDatabaseDdl(
          dbId.getInstanceId().getInstance(),
          dbId.getDatabase(),
          Arrays.asList("CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"),
          null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added AlbumsByAlbumTitle index");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

Ejecuta la muestra con el argumento addindex.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    addindex test-instance example-db

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Added the AlbumsByAlbumTitle index.

Lee datos con el índice

Para las consultas de SQL, Cloud Spanner usa de manera automática un índice adecuado. En la interfaz de lectura, debes especificar el índice en tu solicitud.

Para usar el índice en la interfaz de lectura, usa el método readUsingIndex() de la clase ReadContext.

El siguiente código recupera todas las columnas AlbumId y AlbumTitle del índice AlbumsByAlbumTitle.

static void readUsingIndex(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .readUsingIndex(
              "Albums",
              "AlbumsByAlbumTitle",
              KeySet.all(),
              Arrays.asList("AlbumId", "AlbumTitle"))) {
    while (resultSet.next()) {
      System.out.printf("%d %s\n", resultSet.getLong(0), resultSet.getString(1));
    }
  }
}

Ejecuta la muestra con el argumento readindex.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    readindex test-instance example-db

Deberías ver lo siguiente:

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

Agrega un índice con una cláusula STORING

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

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

En la línea de comandos

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

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para Java

Usa el método updateDatabaseDdl() de la clase DatabaseAdminClient para agregar un índice con una cláusula STORING:

static void addStoringIndex(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient.updateDatabaseDdl(
          dbId.getInstanceId().getInstance(),
          dbId.getDatabase(),
          Arrays.asList(
              "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
                  + "STORING (MarketingBudget)"),
          null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added AlbumsByAlbumTitle2 index");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

Ejecuta la muestra con el argumento addstoringindex.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    addstoringindex test-instance example-db

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Added AlbumsByAlbumTitle2 index

Ahora puedes ejecutar una operación de lectura que recupere todas las columnas AlbumId, AlbumTitle y MarketingBudget del índice AlbumsByAlbumTitle2:

static void readStoringIndex(DatabaseClient dbClient) {
  // We can read MarketingBudget also from the index since it stores a copy of MarketingBudget.
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .readUsingIndex(
              "Albums",
              "AlbumsByAlbumTitle2",
              KeySet.all(),
              Arrays.asList("AlbumId", "AlbumTitle", "MarketingBudget"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %s %s\n",
          resultSet.getLong(0),
          resultSet.getString(1),
          resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"));
    }
  }
}

Ejecuta la muestra con el argumento readstoringindex.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    readstoringindex test-instance example-db

Deberías ver un resultado similar a este:

2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000

Recupera datos mediante transacciones de solo lectura

Supongamos que quieres ejecutar más de una lectura en la misma marca de tiempo. Las transacciones de solo lectura utilizan un prefijo coherente del historial de confirmaciones de transacciones, por lo que la aplicación siempre obtiene datos coherentes. Usa un objeto ReadOnlyTransaction para ejecutar transacciones de solo lectura. Usa el método readOnlyTransaction() de la clase DatabaseClient para obtener un objeto ReadOnlyTransaction.

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

static void readOnlyTransaction(DatabaseClient dbClient) {
  // ReadOnlyTransaction must be closed by calling close() on it to release resources held by it.
  // We use a try-with-resource block to automatically do so.
  try (ReadOnlyTransaction transaction = dbClient.readOnlyTransaction()) {
    ResultSet queryResultSet =
        transaction.executeQuery(
            Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"));
    while (queryResultSet.next()) {
      System.out.printf(
          "%d %d %s\n",
          queryResultSet.getLong(0), queryResultSet.getLong(1), queryResultSet.getString(2));
    }
    try (ResultSet readResultSet =
        transaction.read(
            "Albums", KeySet.all(), Arrays.asList("SingerId", "AlbumId", "AlbumTitle"))) {
      while (readResultSet.next()) {
        System.out.printf(
            "%d %d %s\n",
            readResultSet.getLong(0), readResultSet.getLong(1), readResultSet.getString(2));
      }
    }
  }
}

Ejecuta la muestra con el argumento readonlytransaction.

java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
    readonlytransaction test-instance example-db

Deberías ver un resultado similar a este:

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

Realiza una limpieza

Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud por los recursos que se usaron en este instructivo, descarta la base de datos y borra la instancia que creaste.

Borra la base de datos

Si borras una instancia, se borrarán de forma automática todas las bases de datos que contiene. En este paso, se muestra cómo borrar una base de datos sin borrar una instancia (ten en cuenta que se seguirán generando cargos por la instancia).

En la línea de comandos

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

Usa Cloud Console.

  1. Ve a la página Instancias de Cloud Spanner en Google Cloud Console.

    Ir a la página Instancias

  2. Haz clic en la instancia.

  3. Haz clic en la base de datos que deseas borrar.

  4. En la página Detalles de la base de datos, haz clic en Borrar.

  5. Confirma que deseas borrar la base de datos y haz clic en Borrar.

Borra la instancia

Si borras una instancia, se descartarán de forma automática todas las bases de datos creadas en ella.

En la línea de comandos

gcloud spanner instances delete test-instance

Usa Cloud Console.

  1. Ve a la página Instancias de Cloud Spanner en Google Cloud Console.

    Ir a la página Instancias

  2. Haz clic en tu instancia.

  3. Haz clic en Borrar.

  4. Confirma que deseas borrar la instancia y haz clic en Borrar.

Próximos pasos