DirectedReadOptions

TheDirectedReadOptions can be used to indicate which replicas or regions should be used for non-transactional reads or queries.

DirectedReadOptions can only be specified for a read-only transaction, otherwise the API returns anINVALID_ARGUMENT error.

JSON representation
{// Union fieldreplicas can be only one of the following:"includeReplicas":{object (IncludeReplicas)},"excludeReplicas":{object (ExcludeReplicas)}// End of list of possible types for union fieldreplicas.}
Fields
Union fieldreplicas. Required. At most one of eitherinclude_replicas orexclude_replicas should be present in the message.replicas can be only one of the following:
includeReplicas

object (IncludeReplicas)

Include_replicas indicates the order of replicas (as they appear in this list) to process the request. IfautoFailoverDisabled is set totrue and all replicas are exhausted without finding a healthy replica, Spanner waits for a replica in the list to become available, requests might fail due toDEADLINE_EXCEEDED errors.

excludeReplicas

object (ExcludeReplicas)

Exclude_replicas indicates that specified replicas should be excluded from serving requests. Spanner doesn't route requests to the replicas in this list.

IncludeReplicas

AnIncludeReplicas contains a repeated set ofReplicaSelection which indicates the order in which replicas should be considered.

JSON representation
{"replicaSelections":[{object (ReplicaSelection)}],"autoFailoverDisabled":boolean}
Fields
replicaSelections[]

object (ReplicaSelection)

The directed read replica selector.

autoFailoverDisabled

boolean

Iftrue, Spanner doesn't route requests to a replica outside the <includeReplicas list when all of the specified replicas are unavailable or unhealthy. Default value isfalse.

ReplicaSelection

The directed read replica selector. Callers must provide one or more of the following fields for replica selection:

  • 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 is used to process the request.
  • type:READ_ONLY --> The "READ_ONLY" type replica(s) in the nearest available location are used to process the request.
  • location:us-east1 type:READ_ONLY --> The "READ_ONLY" type replica(s) in location "us-east1" is used to process the request.
JSON representation
{"location":string,"type":enum (Type)}
Fields
location

string

The location or region of the serving requests, for example, "us-east1".

type

enum (Type)

The type of replica.

Type

Indicates the type of replica.

Enums
TYPE_UNSPECIFIEDNot specified.
READ_WRITEsessions.read-write replicas support both reads and writes.
READ_ONLYsessions.read-only replicas only support reads (not writes).

ExcludeReplicas

An ExcludeReplicas contains a repeated set of ReplicaSelection that should be excluded from serving requests.

JSON representation
{"replicaSelections":[{object (ReplicaSelection)}]}
Fields
replicaSelections[]

object (ReplicaSelection)

The directed read replica selector.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-05-30 UTC.