本页面介绍了 Spanner 定向读取及其使用方法。
Spanner 中的定向读取可让您灵活地将只读事务和单次读取路由到多区域实例配置或包含可选只读区域的自定义区域级配置中的特定副本类型或区域。
常见使用场景
定向读取的一些常见使用场景包括：
- 跨多个区域对工作负载进行负载均衡，以实现更均匀的 CPU 利用率。
- 通过最大限度地减少对事务工作负载的影响，在应用中隔离分析。
- 为变更数据流读取提供部分隔离。如果您使用 Spanner API 流式传输 Spanner 数据更改，则可以使用定向读取来帮助最大程度地降低对事务性工作负载的影响。
支持的查询操作
| 查询操作 | 是否支持定向读取？ |
|---|---|
| 过时读取 | 是 |
| 强读取 | 是 |
| 读写事务 | 否 |
读写事务和分区 DML 类型的批量更新不支持定向读取。这是因为读写事务必须在主要区域中处理。如果在读写事务中使用定向读取，则事务会失败并显示 BAD_REQUEST 错误。
限制
Spanner 定向读取存在以下限制：
- 定向读取只能在采用多区域实例配置或具有可选只读区域的自定义区域配置的 Spanner 实例中使用。
- 您不能将定向读取与读写请求搭配使用，因为写入请求始终由主要区域处理。
- 您无法在 Google Cloud 控制台或 Google Cloud CLI 中使用定向读取。它可以通过 REST 和 RPC API 以及 Spanner 客户端库提供。
- 在一次定向读取中，最多可以指定 10 个副本。
- 如果您在系统数据分析信息中心或 Metrics Explorer 的“每秒操作次数”“数据库的每秒操作次数”和“每秒操作次数（按 API 方法）”图表中使用定向读取请求，系统可能会在您指定的位置以外的位置显示定向读取请求。在这种情况下，图表中的信息可能不正确。您可以使用 CPU 利用率指标确认读取请求是否已路由到所选区域。这些指标显示关于定向读取流量路由至何处的最准确信息。
准备工作
在使用定向读取之前，请考虑以下事项：
- 如果您将读取路由到离应用最近的副本或区域，则应用可能会出现额外的延迟。
- 您可以根据以下条件路由流量：
- 区域名称（例如：
us-central1）。 - 副本类型（可能的值：
READ_ONLY和READ_WRITE）。
- 区域名称（例如：
- 定向读取中的自动故障切换选项默认处于启用状态。启用自动故障切换选项且所有指定副本都不可用或运行状况不佳时，Spanner 会将请求路由到
includeReplicas列表之外的副本。如果您停用自动故障切换选项，并且所有指定的副本都不可用或健康状况不佳，则定向读取请求将失败。
定向读取参数
如果您使用 REST 或 RPC API 执行定向读取，则必须在 directedReadOptions 参数中定义这些字段。您只能添加 includeReplicas 或 excludeReplicas 中的一个，不能同时添加这两者。
includeReplicas：包含一组重复的replicaSelections。此列表指示应该按什么顺序考虑针对特定区域或副本类型的定向读取。您最多可以指定 10 个includeReplicas。replicaSelections：由处理定向读取请求的location或副本type组成。如果您使用includeReplicas，则必须至少提供以下字段中的一个：location：处理定向读取请求的位置。此位置必须是您的数据库的多区域配置中的一个区域。如果该位置不是数据库的多区域配置内的区域之一，则请求将无法按预期路由。而是由最近的区域传送。例如，在多区域实例配置nam6中，您可以将读取直接定向到数据库上的us-central1位置。type：处理定向读取请求的副本类型。可能的类型包括READ_WRITE和READ_ONLY。
autoFailoverDisabled：默认情况下，此值设置为False，表示启用自动故障切换功能。启用自动故障切换选项后，如果所有指定副本都不可用或运行状况不佳，则 Spanner 会将请求路由到includeReplicas列表以外的副本。如果您停用自动故障切换选项，并且所有指定的副本都不可用或健康状况不佳，则定向读取请求将失败。可能的值包括TRUE（表示已停用）和FALSE（表示已启用）。
excludeReplicas：包含从服务请求中排除的一组重复的replicaSelections。Spanner 不会将请求路由到此列表中的副本。replicaSelections：从处理定向读取请求中排除的位置或副本类型。如果使用excludeReplicas，则必须至少提供以下字段中的一个：location：从处理定向读取请求中排除的位置。type：从处理定向读取请求中排除的副本类型。可能的类型包括READ_WRITE和READ_ONLY。
如需查看 REST 请求正文的示例，请点击使用定向读取部分中的 REST 标签页。
使用定向读取
您可以使用 Spanner 客户端库以及 REST 和 RPC API 执行定向读取。
客户端库
C++
void DirectedRead(std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
namespace spanner = ::google::cloud::spanner;
// Create a client with a DirectedReadOption.
auto client = spanner::Client(
spanner::MakeConnection(
spanner::Database(project_id, instance_id, database_id)),
google::cloud::Options{}.set<spanner::DirectedReadOption>(
spanner::ExcludeReplicas({spanner::ReplicaSelection("us-east4")})));
spanner::SqlStatement select(
"SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;
// A DirectedReadOption on the operation will override the option set
// at the client level.
auto rows = client.ExecuteQuery(
std::move(select),
google::cloud::Options{}.set<spanner::DirectedReadOption>(
spanner::IncludeReplicas(
{spanner::ReplicaSelection(spanner::ReplicaType::kReadWrite)},
/*auto_failover_disabled=*/true)));
for (auto& row : spanner::StreamOf<RowType>(rows)) {
if (!row) throw std::move(row).status();
std::cout << "SingerId: " << std::get<0>(*row)
<< " AlbumId: " << std::get<1>(*row)
<< " AlbumTitle: " << std::get<2>(*row) << "\n";
}
std::cout << "Read completed for [spanner_directed_read]\n";
}C#
using Google.Cloud.Spanner.Data;
using Google.Cloud.Spanner.V1;
using System.Collections.Generic;
using System.Threading.Tasks;
public class DirectedReadsAsyncSample
{
public class Album
{
public int SingerId { get; set; }
public int AlbumId { get; set; }
public string AlbumTitle { get; set; }
}
public async Task<List<Album>> DirectedReadsAsync(string projectId, string instanceId, string databaseId)
{
string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
using var connection = new SpannerConnection(connectionString);
using var cmd = connection.CreateSelectCommand("SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
// Set directed read options on a query or read command.
cmd.DirectedReadOptions = new DirectedReadOptions
{
IncludeReplicas = new DirectedReadOptions.Types.IncludeReplicas
{
AutoFailoverDisabled = true,
ReplicaSelections =
{
new DirectedReadOptions.Types.ReplicaSelection
{
Location = "us-central1",
Type = DirectedReadOptions.Types.ReplicaSelection.Types.Type.ReadOnly
}
}
}
};
var albums = new List<Album>();
using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
albums.Add(new Album
{
AlbumId = reader.GetFieldValue<int>("AlbumId"),
SingerId = reader.GetFieldValue<int>("SingerId"),
AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
});
}
return albums;
}
}Go
import (
"context"
"fmt"
"io"
"cloud.google.com/go/spanner"
sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
"google.golang.org/api/iterator"
)
// Shows how to run a query with directed read options.
// Only one of ExcludeReplicas or IncludeReplicas can be set
// Each accepts a list of ReplicaSelections which contains Location and Type
// * `location` - The location must be one of the regions within the
// multi-region configuration of your database.
// * `type` - The type of the replica
// Some examples of using replica_selectors are:
// * `location:us-east1` --> The "us-east1" replica(s) of any available type
// will be used to process the request.
// * `type:READ_ONLY` --> The "READ_ONLY" type replica(s) in nearest
// available location will be used to process the
// request.
// * `location:us-east1 type:READ_ONLY` --> The "READ_ONLY" type replica(s)
// in location "us-east1" will be used to process the request.
// IncludeReplicas also contains an option for AutoFailoverDisabled which when set
// Spanner will not route requests to a replica outside the
// IncludeReplicas list when all the specified replicas are unavailable
// or unhealthy. The default value is `false`
func directedReadOptions(w io.Writer, db string) error {
// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
ctx := context.Background()
directedReadOptionsForClient := &sppb.DirectedReadOptions{
Replicas: &sppb.DirectedReadOptions_ExcludeReplicas_{
ExcludeReplicas: &sppb.DirectedReadOptions_ExcludeReplicas{
ReplicaSelections: []*sppb.DirectedReadOptions_ReplicaSelection{
{
Location: "us-east4",
},
},
},
},
}
// DirectedReadOptions can be set at client level and will be used in all read-only transaction requests
client, err := spanner.NewClientWithConfig(ctx, db, spanner.ClientConfig{DirectedReadOptions: directedReadOptionsForClient})
if err != nil {
return err
}
defer client.Close()
// DirectedReadOptions set at Request level will override the options set at Client level.
directedReadOptionsForRequest := &sppb.DirectedReadOptions{
Replicas: &sppb.DirectedReadOptions_IncludeReplicas_{
IncludeReplicas: &sppb.DirectedReadOptions_IncludeReplicas{
ReplicaSelections: []*sppb.DirectedReadOptions_ReplicaSelection{
{
Type: sppb.DirectedReadOptions_ReplicaSelection_READ_ONLY,
},
},
AutoFailoverDisabled: true,
},
},
}
statement := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
// // Read rows while passing directedReadOptions directly to the query.
iter := client.Single().QueryWithOptions(ctx, statement, spanner.QueryOptions{DirectedReadOptions: directedReadOptionsForRequest})
defer iter.Stop()
for {
row, err := iter.Next()
if err == iterator.Done {
return nil
}
if err != nil {
return err
}
var singerID, albumID int64
var albumTitle string
if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
return err
}
fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
}
}
Java
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Options;
import com.google.cloud.spanner.ResultSet;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.Statement;
import com.google.spanner.v1.DirectedReadOptions;
import com.google.spanner.v1.DirectedReadOptions.ExcludeReplicas;
import com.google.spanner.v1.DirectedReadOptions.IncludeReplicas;
import com.google.spanner.v1.DirectedReadOptions.ReplicaSelection;
public class DirectedReadSample {
static void directedRead() {
// TODO(developer): Replace these variables before running the sample.
final String projectId = "my-project";
final String instanceId = "my-instance";
final String databaseId = "my-database";
directedRead(projectId, instanceId, databaseId);
}
static void directedRead(String projectId, String instanceId, String databaseId) {
// Only one of excludeReplicas or includeReplicas can be set
// Each accepts a list of replicaSelections which contains location and type
// * `location` - The location must be one of the regions within the
// multi-region configuration of your database.
// * `type` - The type of the replica
// Some examples of using replicaSelectors are:
// * `location:us-east1` --> The "us-east1" replica(s) of any available type
// will be used to process the request.
// * `type:READ_ONLY` --> The "READ_ONLY" type replica(s) in nearest
// . available location will be used to process the
// request.
// * `location:us-east1 type:READ_ONLY` --> The "READ_ONLY" type replica(s)
// in location "us-east1" will be used to process
// the request.
// includeReplicas also contains an option called autoFailoverDisabled, which when set to true
// will instruct Spanner to not route requests to a replica outside the
// includeReplicas list when all the specified replicas are unavailable
// or unhealthy. Default value is `false`.
final DirectedReadOptions directedReadOptionsForClient =
DirectedReadOptions.newBuilder()
.setExcludeReplicas(
ExcludeReplicas.newBuilder()
.addReplicaSelections(
ReplicaSelection.newBuilder().setLocation("us-east4").build())
.build())
.build();
// You can set default `DirectedReadOptions` for a Spanner client. These options will be applied
// to all read-only transactions that are executed by this client, unless specific
// DirectedReadOptions are set for a query.
// Directed read can only be used for read-only transactions. The default options will be
// ignored for any read/write transaction that the client executes.
try (Spanner spanner =
SpannerOptions.newBuilder()
.setProjectId(projectId)
.setDirectedReadOptions(directedReadOptionsForClient)
.build()
.getService()) {
final DatabaseClient dbClient =
spanner.getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
// DirectedReadOptions at request level will override the options set at
// client level (through SpannerOptions).
final DirectedReadOptions directedReadOptionsForRequest =
DirectedReadOptions.newBuilder()
.setIncludeReplicas(
IncludeReplicas.newBuilder()
.addReplicaSelections(
ReplicaSelection.newBuilder()
.setType(ReplicaSelection.Type.READ_WRITE)
.build())
.setAutoFailoverDisabled(true)
.build())
.build();
// Read rows while passing DirectedReadOptions directly to the query.
try (ResultSet rs =
dbClient
.singleUse()
.executeQuery(
Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"),
Options.directedRead(directedReadOptionsForRequest))) {
while (rs.next()) {
System.out.printf(
"SingerId: %d, AlbumId: %d, AlbumTitle: %s\n",
rs.getLong(0), rs.getLong(1), rs.getString(2));
}
System.out.println("Successfully executed read-only transaction with directedReadOptions");
}
}
}
}Node.js
// Imports the Google Cloud Spanner client library
const {Spanner, protos} = require('@google-cloud/spanner');
// Only one of excludeReplicas or includeReplicas can be set
// Each accepts a list of replicaSelections which contains location and type
// * `location` - The location must be one of the regions within the
// multi-region configuration of your database.
// * `type` - The type of the replica
// Some examples of using replicaSelectors are:
// * `location:us-east1` --> The "us-east1" replica(s) of any available type
// will be used to process the request.
// * `type:READ_ONLY` --> The "READ_ONLY" type replica(s) in nearest
//. available location will be used to process the
// request.
// * `location:us-east1 type:READ_ONLY` --> The "READ_ONLY" type replica(s)
// in location "us-east1" will be used to process
// the request.
// includeReplicas also contains an option for autoFailover which when set
// Spanner will not route requests to a replica outside the
// includeReplicas list when all the specified replicas are unavailable
// or unhealthy. The default value is `false`
const directedReadOptionsForClient = {
excludeReplicas: {
replicaSelections: [
{
location: 'us-east4',
},
],
},
};
// Instantiates a client with directedReadOptions
const spanner = new Spanner({
projectId: projectId,
directedReadOptions: directedReadOptionsForClient,
});
async function spannerDirectedReads() {
// Gets a reference to a Cloud Spanner instance and backup
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);
const directedReadOptionsForRequest = {
includeReplicas: {
replicaSelections: [
{
type: protos.google.spanner.v1.DirectedReadOptions.ReplicaSelection
.Type.READ_ONLY,
},
],
autoFailoverDisabled: true,
},
};
await database.getSnapshot(async (err, transaction) => {
if (err) {
console.error(err);
return;
}
try {
// Read rows while passing directedReadOptions directly to the query.
// These will override the options passed at Client level.
const [rows] = await transaction.run({
sql: 'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
directedReadOptions: directedReadOptionsForRequest,
});
rows.forEach(row => {
const json = row.toJSON();
console.log(
`SingerId: ${json.SingerId}, AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`
);
});
console.log(
'Successfully executed read-only transaction with directedReadOptions'
);
} catch (err) {
console.error('ERROR:', err);
} finally {
transaction.end();
// Close the database when finished.
await database.close();
}
});
}
spannerDirectedReads();PHP
use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type as ReplicaType;
/**
* Queries sample data from the database with directed read options.
* Example:
* ```
* directed_read($instanceId, $databaseId);
* ```
*
* @param string $instanceId The Spanner instance ID.
* @param string $databaseId The Spanner database ID.
*/
function directed_read(string $instanceId, string $databaseId): void
{
$directedReadOptionsForClient = [
'directedReadOptions' => [
'excludeReplicas' => [
'replicaSelections' => [
[
'location' => 'us-east4'
]
]
]
]
];
$directedReadOptionsForRequest = [
'directedReadOptions' => [
'includeReplicas' => [
'replicaSelections' => [
[
'type' => ReplicaType::READ_WRITE
]
],
'autoFailoverDisabled' => true
]
]
];
$spanner = new SpannerClient($directedReadOptionsForClient);
$instance = $spanner->instance($instanceId);
$database = $instance->database($databaseId);
$snapshot = $database->snapshot();
// directedReadOptions at Request level will override the options set at
// Client level
$results = $snapshot->execute(
'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
$directedReadOptionsForRequest
);
foreach ($results as $row) {
printf('SingerId: %s, AlbumId: %s, AlbumTitle: %s' . PHP_EOL,
$row['SingerId'], $row['AlbumId'], $row['AlbumTitle']);
}
}Python
# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
directed_read_options_for_client = {
"exclude_replicas": {
"replica_selections": [
{
"location": "us-east4",
},
],
},
}
# directed_read_options can be set at client level and will be used in all
# read-only transaction requests
spanner_client = spanner.Client(
directed_read_options=directed_read_options_for_client
)
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)
directed_read_options_for_request = {
"include_replicas": {
"replica_selections": [
{
"type_": DirectedReadOptions.ReplicaSelection.Type.READ_ONLY,
},
],
"auto_failover_disabled": True,
},
}
with database.snapshot() as snapshot:
# Read rows while passing directed_read_options directly to the query.
# These will override the options passed at Client level.
results = snapshot.execute_sql(
"SELECT SingerId, AlbumId, AlbumTitle FROM Albums",
directed_read_options=directed_read_options_for_request,
)
for row in results:
print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))Ruby
require "google/cloud/spanner"
##
# This is a snippet for showcasing how to pass in directed read options.
#
# @param project_id [String] The ID of the Google Cloud project.
# @param instance_id [String] The ID of the spanner instance.
# @param database_id [String] The ID of the database.
#
def spanner_directed_read project_id:, instance_id:, database_id:
# Only one of exclude_replicas or include_replicas can be set.
# Each accepts a list of replica_selections which contains location and type
# * `location` - The location must be one of the regions within the
# multi-region configuration of your database.
# * `type` - The type of the replica
# Some examples of using replicaSelectors are:
# * `location:us-east1` --> The "us-east1" replica(s) of any available type
# will be used to process the request.
# * `type:READ_ONLY` --> The "READ_ONLY" type replica(s) in the nearest
# . available location will be used to process the
# request.
# * `location:us-east1 type:READ_ONLY` --> The "READ_ONLY" type replica(s)
# in location "us-east1" will be used to process
# the request.
# include_replicas also contains an option for auto_failover_disabled. If set
# Spanner will not route requests to a replica outside the
# include_replicas list even if all the specified replicas are
# unavailable or unhealthy. The default value is `false`.
directed_read_options_for_client = {
include_replicas: {
replica_selections: [{ location: "us-east4" }]
}
}
# Instantiates a client with directedReadOptions
spanner = Google::Cloud::Spanner.new project: project_id
client = spanner.client instance_id, database_id, directed_read_options: directed_read_options_for_client
directed_read_options = {
include_replicas: {
replica_selections: [{ type: "READ_WRITE" }],
auto_failover_disabled: true
}
}
result = client.execute_sql "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", directed_read_options: directed_read_options
result.rows.each do |row|
puts "SingerId: #{row[:SingerId]}"
puts "AlbumId: #{row[:AlbumId]}"
puts "AlbumTitle: #{row[:AlbumTitle]}"
end
puts "Successfully executed read-only transaction with directed_read_options"
endREST
您可以使用以下 REST API 执行定向读取：
例如，如需使用 executeSQL 在 us-central1 中执行定向读取，请编写以下代码：
对于 session，输入：
projects/<VAR>PROJECT-ID</VAR>/instances/<VAR>INSTANCE-ID</VAR>/databases/<VAR>DATABASE-ID</VAR>/sessions/<VAR>SESSION-ID</VAR>替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-ID：实例 ID。
- DATABASE-ID：数据库 ID。
- SESSION-ID：会话 ID。
您在创建会话时收到
SESSION-ID值。
对于 Request body，使用以下内容：
{ "directedReadOptions": { "includeReplicas": { "replicaSelections": [ { "location": "us-central1", } ] } }, "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }点击 Execute。该响应会显示查询结果。
远程过程调用 (RPC)
您可以使用以下 RPC API 执行定向读取：
后续步骤
- 了解如何在事务之外执行读取。