DirectedReadOptions

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

DirectedReadOptions may only be specified for a read-only transaction, otherwise the API will return an INVALID_ARGUMENT error.

JSON representation
{

  // Union field replicas can be only one of the following:
  "includeReplicas": {
    object (IncludeReplicas)
  },
  "excludeReplicas": {
    object (ExcludeReplicas)
  }
  // End of list of possible types for union field replicas.
}
Fields
Union field replicas. Required. At most one of either include_replicas or exclude_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. If autoFailoverDisabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.

excludeReplicas

object (ExcludeReplicas)

Exclude_replicas indicates that specified replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.

IncludeReplicas

An IncludeReplicas contains a repeated set of ReplicaSelection 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

If true, Spanner will not route requests to a replica outside the includeReplicas list when all of the specified replicas are unavailable or unhealthy. Default value is false.

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 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.
JSON representation
{
  "location": string,
  "type": enum (Type)
}
Fields
location

string

The location or region of the serving requests, e.g. "us-east1".

type

enum (Type)

The type of replica.

Type

Indicates the type of replica.

Enums
TYPE_UNSPECIFIED Not specified.
READ_WRITE sessions.read-write replicas support both reads and writes.
READ_ONLY sessions.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.