The DirectedReadOptions 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 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:
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 waits for a replica in the list to become available, requests might fail due to DEADLINE_EXCEEDED errors.
Exclude_replicas indicates that specified replicas should be excluded from serving requests. Spanner doesn't 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.
If true, Spanner doesn't 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 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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-05-30 UTC."],[],[],null,["# DirectedReadOptions\n\n- [JSON representation](#SCHEMA_REPRESENTATION)\n- [IncludeReplicas](#IncludeReplicas)\n - [JSON representation](#IncludeReplicas.SCHEMA_REPRESENTATION)\n- [ReplicaSelection](#ReplicaSelection)\n - [JSON representation](#ReplicaSelection.SCHEMA_REPRESENTATION)\n- [Type](#Type)\n- [ExcludeReplicas](#ExcludeReplicas)\n - [JSON representation](#ExcludeReplicas.SCHEMA_REPRESENTATION)\n\nThe `DirectedReadOptions` can be used to indicate which replicas or regions should be used for non-transactional reads or queries.\n\n`DirectedReadOptions` can only be specified for a read-only transaction, otherwise the API returns an `INVALID_ARGUMENT` error.\n\nIncludeReplicas\n---------------\n\nAn `IncludeReplicas` contains a repeated set of `ReplicaSelection` which indicates the order in which replicas should be considered.\n\nReplicaSelection\n----------------\n\nThe directed read replica selector. Callers must provide one or more of the following fields for replica selection:\n\n- `location` - The location must be one of the regions within the multi-region configuration of your database.\n- `type` - The type of the replica.\n\nSome examples of using replica_selectors are:\n\n- `location:us-east1` --\\\u003e The \"us-east1\" replica(s) of any available type is used to process the request.\n- `type:READ_ONLY` --\\\u003e The \"READ_ONLY\" type replica(s) in the nearest available location are used to process the request.\n- `location:us-east1 type:READ_ONLY` --\\\u003e The \"READ_ONLY\" type replica(s) in location \"us-east1\" is used to process the request.\n\nType\n----\n\nIndicates the type of replica.\n\nExcludeReplicas\n---------------\n\nAn ExcludeReplicas contains a repeated set of ReplicaSelection that should be excluded from serving requests."]]