Cloud Spanner 使用入门 (Java)

目标

本教程将介绍如何使用适用于 Java 的 Cloud Spanner 客户端库完成以下步骤：

• 创建 Cloud Spanner 实例和数据库。
• 写入、读取数据库中的数据和对数据执行 SQL 查询。
• 更新数据库架构。
• 使用读写事务更新数据。
• 向数据库添加二级索引。
• 使用索引来读取数据和对数据执行 SQL 查询。
• 使用只读事务检索数据。

费用

本教程使用 Cloud Spanner，它是 Google Cloud 的收费组件。如需了解使用 Cloud Spanner 的费用，请参阅价格。

准备工作

完成设置中介绍的步骤，包括创建和设置默认 Google Cloud 项目、启用结算功能、启用 Cloud Spanner API 以及设置 OAuth 2.0 来获取身份验证凭据以使用 Cloud Spanner API。

尤其要确保运行 gcloud auth application-default login，以便使用身份验证凭据设置本地开发环境。

注意：如果您不打算保留在本教程中创建的资源，请考虑创建新的 Google Cloud 项目，而不是选择现有项目。完成本教程后，您可以删除项目，并移除与该项目关联的所有资源。

准备本地 Java 环境

1. 在开发机器上安装以下内容（如果尚未安装）：

   • Java 7 或 Java 8 JDK（下载）。
   • Maven 3（下载）。

2. 将示例应用代码库克隆到本地机器：

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

3. 切换到包含 Cloud Spanner 示例代码的目录：

   cd java-spanner/samples/snippets
   

创建实例

在首次使用 Cloud Spanner 时，必须创建一个实例，实例是 Cloud Spanner 数据库使用的资源分配单位。创建实例时，请选择一个实例配置（决定数据的存储位置），同时选择要使用的节点数（决定实例中服务资源和存储资源的数量）。

执行以下命令，在区域 us-central1 中创建具有 1 个节点的 Cloud Spanner 实例：

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

请注意，此命令将创建一个具有以下特征的实例：

• 实例 ID 为 test-instance
• 显示名为 Test Instance
• 实例配置为 regional-us-central1（单区域配置将数据存储在单个区域中，而多区域配置则将数据分布在多个区域中。如需了解详情，请参阅实例。）
• 节点数为 1（node_count 对应于实例中数据库可用的服务资源和存储资源的数量。如需了解详情，请参阅节点数。）

应显示如下消息：

Creating instance...done.

浏览示例文件

示例代码库包含一个示例，其展示了如何在 Java 中使用 Cloud Spanner。

pom.xml 将 Java 版 Cloud Spanner 客户端库添加到项目的依赖项中，并配置程序集插件以使用本教程中定义的 Java 类构建可执行 JAR 文件。

从 samples/snippets 目录构建示例：

mvn package

创建数据库

通过在命令行运行以下命令，在名为 test-instance 的实例中创建名为 example-db 的数据库。

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

您应该会看到：

Created database [example-db]

您刚刚创建了一个 Cloud Spanner 数据库。以下是创建数据库的代码。

在 GitHub 上查看 反馈

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

该代码还为一个基本的音乐应用定义了两个表：Singers 和 Albums。本页面会一直用到这两个表。请查看示例架构（如果您还没有查看）。

下一步是将数据写入数据库。

创建数据库客户端

您必须先创建一个 DatabaseClient，然后才能执行读写操作。您可以将 DatabaseClient 视为数据库连接：您与 Cloud Spanner 的所有交互都必须通过 DatabaseClient 进行。通常，您可以在应用启动时创建 DatabaseClient，然后重复使用该 DatabaseClient 来读取、写入和执行事务。

在 GitHub 上查看 反馈

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...
} finally {
  spanner.close();
}

每个客户端均使用 Cloud Spanner 中的资源，因此最好通过调用 close() 来关闭不需要的客户端。

如需了解详情，请参阅 DatabaseClient Javadoc 参考。

使用 DML 写入数据

您可以在读写事务中使用数据操纵语言 (DML) 插入数据。

使用 executeUpdate() 方法来执行 DML 语句。

在 GitHub 上查看 反馈

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

使用 writeusingdml 参数运行示例。

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

您应该会看到：

4 records inserted.

注意：提交大小有限制。如需了解详情，请参阅 CRUD 限制。

使用变更写入数据

您还可以使用变更插入数据。

您使用 Mutation 对象写入数据。Mutation 对象是用于变更操作的容器。Mutation 代表插入、更新、删除等一系列操作，这些操作可以原子方式应用于 Cloud Spanner 数据库中的不同行和表。

Mutation 类中的 newInsertBuilder() 方法可构造一项 INSERT 变更，该变更会在表中插入一个新行。如果该行已经存在，则写入失败。或者，您可以使用 newInsertOrUpdateBuilder 方法构造一项 INSERT_OR_UPDATE 变更，该变更会在该行已经存在时更新列值。

DatabaseClient 类中的 write() 方法可写入变更。单个批处理中的所有变更均以原子方式应用。

此代码演示了如何使用变更写入数据：

在 GitHub 上查看 反馈

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

使用 write 参数运行示例。

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

您应该会看到命令成功运行。

注意：提交大小有限制。如需了解详情，请参阅 CRUD 限制。

使用 SQL 查询数据

Cloud Spanner 支持使用原生 SQL 接口读取数据，您可以使用 gcloud 命令行工具在命令行中使用该接口，也可以通过 Java 版 Cloud Spanner 客户端库以编程方式使用该接口。

在命令行中

执行以下 SQL 语句，读取 Albums 表中所有列的值：

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

注意：如需查看 Cloud Spanner SQL 参考文档，请参阅 SQL 语法。

结果应为：

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

使用适用于 Java 的 Cloud Spanner 客户端库

除了在命令行中执行 SQL 语句外，还可以使用 Java 版 Cloud Spanner 客户端库以编程方式发出相同的 SQL 语句。

使用以下方法和类运行 SQL 查询：

• DatabaseClient 类中的 singleUse() 方法：使用此方法读取 Cloud Spanner 表中一行或多行的一列或多列的值。singleUse() 会返回一个 ReadContext 对象，可用于运行读取或 SQL 语句。
• ReadContext 类的 executeQuery() 方法：使用此方法对数据库执行查询。
• Statement 类：使用此类构造 SQL 字符串。
• ResultSet 类：使用此类访问由 SQL 语句或读取调用返回的数据。

下面演示了如何发出查询并访问数据：

在 GitHub 上查看 反馈

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

使用 query 参数运行示例。

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

您应该会看到以下结果：

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

使用 SQL 参数进行查询

您可以使用支持的 SQL 类型在 SQL 语句中添加自定义值。

以下示例演示了如何在 WHERE 子句中使用 @lastName 作为参数来查询包含特定 LastName 值的记录。

在 GitHub 上查看 反馈

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"));
    }
  }
}

使用 queryWithParameter 参数运行示例。

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

您应该会看到以下结果：

12 Melissa Garcia

使用读取 API 读取数据

除 Cloud Spanner 的 SQL 接口外，Cloud Spanner 还支持读取接口。

使用 ReadContext 类的 read() 方法可从数据库中读取行。使用 KeySet 对象定义要读取的键和键范围的集合。

下面演示了如何读取数据：

在 GitHub 上查看 反馈

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

使用 read 参数运行示例。

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

您看到的输出结果应该类似于以下内容：

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

更新数据库架构

假设您需要将名为 MarketingBudget 的新列添加到 Albums 表。向现有表添加新列需要更新数据库架构。Cloud Spanner 支持在数据库继续处理流量的同时，对数据库进行架构更新。架构更新不需要使数据库离线，并且不会锁定整个表或列；在架构更新期间，您可以继续将数据写入数据库。如需详细了解支持的架构更新和架构更改性能，请参阅架构更新。

添加列

您可以使用 gcloud 命令行工具在命令行中添加列，也可以使用 Java 版 Cloud Spanner 客户端库以编程方式添加列。

在命令行中

使用以下 ALTER TABLE 命令向表添加新列：

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

您应该会看到：

Schema updating...done.

使用 Java 版 Cloud Spanner 客户端库

使用 DatabaseAdminClient 类的 updateDatabaseDdl() 方法来修改架构：

在 GitHub 上查看 反馈

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

使用 addmarketingbudget 参数运行示例。

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

您应该会看到：

Added MarketingBudget column.

将数据写入新列

以下代码可将数据写入新列。对于键分别为 Albums(1, 1) 和 Albums(2, 2) 的行，该代码会将 MarketingBudget 分别设置为 100000 和 500000。

在 GitHub 上查看 反馈

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

使用 update 参数运行示例。

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

您还可以执行 SQL 查询或读取调用来获取刚才写入的值。

以下是执行查询的代码：

在 GitHub 上查看 反馈

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"));
    }
  }
}

如需执行此查询，请使用 querymarketingbudget 参数运行示例。

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

您应该会看到：

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

更新数据

您可以在读写事务中使用 DML 来更新数据。

使用 executeUpdate() 方法来执行 DML 语句。

在 GitHub 上查看 反馈

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

使用 writewithtransactionusingdml 参数运行示例。

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

注意：您还可以使用变更更新数据。

使用二级索引

假设您想要提取 Albums 表中 AlbumTitle 值在特定范围内的所有行。您可以使用 SQL 语句或读取调用读取 AlbumTitle 列中的所有值，然后舍弃不符合条件的行。不过，执行全表扫描费用高昂，特别是对内含大量行的表来说更是如此。相反，如果对表创建二级索引，按非主键列进行搜索，则可以提高行检索速度。

向现有表添加二级索引需要更新架构。与其他架构更新一样，Cloud Spanner 支持在数据库继续处理流量的同时添加索引。Cloud Spanner 会使用您的现有数据自动回填索引。回填可能需要几分钟时间才能完成，但在此过程中，您无需使数据库离线，也无需避免写入已编入索引的表。如需了解详情，请参阅索引回填。

添加二级索引后，Cloud Spanner 会自动使用该索引进行 SQL 查询，使用该索引后，查询运行速度可能会提高。如果使用读取接口，则必须指定要使用的索引。

添加二级索引

您可以使用 gcloud 命令行工具在命令行中添加索引，也可以使用 Java 版 Cloud Spanner 客户端库以编程方式添加索引。

在命令行中

使用以下 CREATE INDEX 命令向数据库添加索引：

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

您应该会看到：

Schema updating...done.

使用 Java 版 Cloud Spanner 客户端库

使用 DatabaseAdminClient 类的 updateDatabaseDdl() 方法来添加索引：

在 GitHub 上查看 反馈

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

使用 addindex 参数运行示例。

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

添加索引可能需要几分钟时间。添加索引后，您应该会看到：

Added the AlbumsByAlbumTitle index.

使用索引进行读取

对于 SQL 查询，Cloud Spanner 会自动使用适当的索引。在读取接口中，您必须在请求中指定索引。

如需在读取接口中使用索引，请使用 ReadContext 类的 readUsingIndex() 方法。

以下代码会从 AlbumsByAlbumTitle 索引中提取所有 AlbumId 和 AlbumTitle 列。

在 GitHub 上查看 反馈

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

使用 readindex 参数运行示例。

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

您应该会看到：

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

添加带 STORING 子句的索引

您可能已经注意到，上面的读取示例不包括读取 MarketingBudget 列。这是因为，Cloud Spanner 的读取接口不支持将索引与数据表联接起来查找未存储在索引中的值。

请创建 AlbumsByAlbumTitle 的备用定义，用于将 MarketingBudget 的副本存储到索引中。

在命令行中

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

添加索引可能需要几分钟时间。添加索引后，您应该会看到：

Schema updating...done.

使用 Java 版 Cloud Spanner 客户端库

使用 DatabaseAdminClient 类的 updateDatabaseDdl() 方法来添加带 STORING 子句的索引：

在 GitHub 上查看 反馈

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

使用 addstoringindex 参数运行示例。

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

添加索引可能需要几分钟时间。添加索引后，应显示如下信息：

Added AlbumsByAlbumTitle2 index

现在，当您执行读取操作时便可从 AlbumsByAlbumTitle2 索引中提取所有 AlbumId、AlbumTitle 和 MarketingBudget 列：

在 GitHub 上查看 反馈

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"));
    }
  }
}

使用 readstoringindex 参数运行示例。

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

您看到的输出结果应该类似于以下内容：

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

使用只读事务检索数据

假设您要在同一时间戳执行多个读取操作。只读事务会观察事务提交记录的一致前缀，以便应用始终获得一致的数据。 使用 ReadOnlyTransaction 对象执行只读事务。使用 DatabaseClient 类的 readOnlyTransaction()方法来获取 ReadOnlyTransaction 对象。

下面演示了如何运行查询并在同一只读事务中执行读取操作：

在 GitHub 上查看 反馈

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

使用 readonlytransaction 参数运行示例。

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

您看到的输出结果应该类似于以下内容：

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

清理

为避免因本教程中使用的资源导致您的 Google Cloud 帐号产生额外费用，请删除数据库和您创建的实例。

删除数据库

如果您删除一个实例，则该实例中的所有数据库都会自动删除。 本步骤演示了如何在不删除实例的情况下删除数据库（您仍需为该实例付费）。

在命令行中

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

使用 Cloud Console

1. 转到 Google Cloud Console 中的 Cloud Spanner 实例页面。

   转到“实例”页面

2. 点击实例。

3. 点击您想删除的数据库。

4. 在数据库详细信息页面中，点击删除。

5. 确认您要删除数据库并点击删除。

删除实例

删除实例会自动删除在该实例中创建的所有数据库。

在命令行中

gcloud spanner instances delete test-instance

使用 Cloud Console

1. 转到 Google Cloud Console 中的 Cloud Spanner 实例页面。

   转到“实例”页面

2. 点击您的实例。

3. 点击删除。

4. 确认您要删除实例并点击删除。

后续步骤

• 试用 Cloud Spanner 的 Spring Data 模块。
• 在虚拟机实例中访问 Cloud Spanner：创建一个可访问 Cloud Spanner 数据库的虚拟机实例。
• 在身份验证入门中了解授权和身份验证凭据。
• 了解更多 Cloud Spanner 概念。