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).
Common use cases
Some common use cases for directed reads include:
- Load-balancing workloads across multiple regions to achieve more uniform CPU utilization.
- Isolating analytics in your application by minimizing impact on transactional workloads.
- Providing partial isolation for change streams reads. If you use the Spanner API to stream Spanner data changes, you can help to minimize impact on transactional workloads by using directed reads.
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.
- If you use the system insights dashboard or Metrics Explorer, in the Operations per second, Operations per second by database, and Operations per second by API method charts, you might see your directed reads request in a location other than the one you designated. In this case, the information from the charts might be incorrect. You can confirm that your read requests are routed to your chosen region(s) by using the CPU utilization metrics. These metrics show the most accurate information on where directed reads traffic is routed.
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
.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:
What's next
- Learn how to perform Reads outside of transactions.