The page describes Spanner directed reads and how to use it.
Directed reads in Spanner provide the flexibility to route read-only transactions and single reads to a specific replica type or region within a multi-region instance configuration or a custom regional configuration with optional read-only region(s).
Benefits
Directed reads offer the following benefits:
- Provide more control over load-balancing workloads across multiple regions to achieve more uniform CPU utilization and avoid over-provisioning of Spanner instances.
- Enable workload isolation. You can direct your analytics workloads and change streams reads to specific Spanner replicas to minimize impact to transactional workloads running on the same Spanner database.
Supported query operations
Query operations | Are directed reads supported? |
---|---|
Stale read | Yes |
Strong read | Yes |
Read-write transaction | No |
Directed reads are not supported for read-write transactions
and partitioned DML types of bulk updates. This
is because read-write transactions must be processed in the leader region. If
directed reads are used in a read-write transaction, the transaction fails with
a BAD_REQUEST
error.
Limitations
Spanner directed reads have the following limitations:
- You can only use directed reads in a Spanner instance that is in a multi-region instance configuration or a custom regional configuration with optional read-only region(s).
- You can't use directed reads with read-write requests because write requests are always served by the leader region.
- You can't use directed reads in the Google Cloud console or Google Cloud CLI. It is available using REST and RPC APIs and the Spanner client libraries.
- You can specify a maximum of 10 replicas in a single directed read.
Before you begin
Consider the following before you use directed reads:
- The application might incur additional latency if you are routing reads to a replica or region other than the one closest to the application.
- You can route traffic based on:
- Region name (For example:
us-central1
). - Replica type (Possible values:
READ_ONLY
andREAD_WRITE
).
- Region name (For example:
- The auto failover option in directed reads is enabled by default. When auto
failover option is enabled and all of the specified replicas are unavailable
or unhealthy, Spanner routes requests to a replica outside the
includeReplicas
list. If you disable the auto failover option and all of the specified replicas are unavailable or unhealthy, the directed reads request fails.
Directed reads parameters
If you're using the REST or RPC API to perform directed reads, you must define
these fields in the directedReadOptions
parameter. You can only include one of
includeReplicas
or excludeReplicas
, not both.
includeReplicas
: Contains a repeated set ofreplicaSelections
. This list indicates the order in which directed reads to specific regions or replica types should be considered. You can specify a maximum of 10includeReplicas
.replicaSelections
: Consists of thelocation
or replicatype
serving the directed reads request. If you useincludeReplicas
, you must provide at least one of the following fields:location
: The location serving the directed reads request. The location must be one of the regions within the multi-region configuration of your database. If the location is not one of the regions within the multi-region configuration of your database, requests won't be routed as expected. Instead, they are served by the nearest region. For example, you can direct reads to the locationus-central1
on a database in the multi-region instance configurationnam6
.You can also specify the
location
parameter with aleader
ornon-leader
string literal. If you input theleader
value, Spanner directs your requests to the database's leader replica. Conversely, if you input thenon-leader
value, Spanner fulfills the request in the nearest non-leader replica.type
: The replica type serving the directed reads request. Possible types includeREAD_WRITE
andREAD_ONLY
.
autoFailoverDisabled
: By default, this is set toFalse
, which means auto failover is enabled. When auto failover option is enabled, and all of the specified replicas are unavailable or unhealthy, Spanner routes requests to a replica outside theincludeReplicas
list. If you disable the auto failover option and all of the specified replicas are unavailable or unhealthy, the directed reads request fails. Possible values includeTRUE
for disabled andFALSE
for enabled.
excludeReplicas
: Contains a repeated set ofreplicaSelections
that is excluded from serving requests. Spanner doesn't route requests to replicas in this list.replicaSelections
: The location or replica type that is excluded from serving the directed reads request. If you useexcludeReplicas
, you must provide at least one of the following fields:location
: The location that is excluded from serving the directed reads request.type
: The replica type that is excluded from serving the directed reads request. Possible types includeREAD_WRITE
andREAD_ONLY
.
To see an example of what a REST request body looks like, click the REST tab in the Use directed reads section.
Use directed reads
You can use the Spanner client libraries and REST and RPC APIs to perform directed reads.
Client libraries
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST
You can use the following REST APIs to perform directed reads:
For example, to perform directed reads in us-central1
using executeSQL
:
For session, enter:
projects/<VAR>PROJECT-ID</VAR>/instances/<VAR>INSTANCE-ID</VAR>/databases/<VAR>DATABASE-ID</VAR>/sessions/<VAR>SESSION-ID</VAR>
Replace the following:
- PROJECT-ID: the project ID.
- INSTANCE-ID: the instance ID.
- DATABASE-ID: the database ID.
- SESSION-ID: the session ID.
You receive the
SESSION-ID
value when you create a session.
For Request body, use the following:
{ "directedReadOptions": { "includeReplicas": { "replicaSelections": [ { "location": "us-central1", } ] } }, "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Click Execute. The response shows the query results.
RPC
You can use the following RPC APIs to perform directed reads:
Monitoring
Spanner provides a latency metric to help you monitor directed reads activities in your instances. The metric is available in Cloud Monitoring.
spanner.googleapis.com/api/read_request_latencies_by_serving_location
You can filter this metric using the /serving_location
or
/is_directed_read
fields. The /serving location
field indicates the location
of the Spanner server where the request is served from. The
/is_directed_read
field indicates whether the directed reads option is
enabled.
For a full list of available metrics, see metrics list for Spanner.
What's next
- Learn how to perform Reads outside of transactions.