Follower Reads

On this page Carat arrow pointing down
CockroachDB v19.2 is no longer supported as of May 12, 2021. For more details, refer to the Release Support Policy.

To reduce latency for read queries, you can use the follower reads feature, which lets the closest replica serve the read request at the expense of only not guaranteeing that data is up to date.


The follower reads feature is an enterprise-only feature. For insight into how to use this feature to get low latency, historical reads in multi-region deployments, see the Follower Reads topology pattern.

What are Follower reads?

Follower reads are a mechanism to let any replica of a range serve a read request, but are only available for read queries that are sufficiently in the past, i.e., using AS OF SYSTEM TIME. Currently, follower reads are available for any read operation at least 48 seconds in the past, though there is active work to reduce that window.

In widely distributed deployments, using follower reads can reduce the latency of read operations (which can also increase throughput) by letting the replica closest to the gateway serve the request, instead of forcing the gateway to communicate with the leaseholder, which could be geographically distant.

To make it easier to know when it's safe for your application to make follower reads, we've also included a convenience function (experimental_follower_read_timestamp()) that runs your queries at a time as close as possible to the present time.


Enable/disable follower reads

Use SET CLUSTER SETTING to set kv.closed_timestamp.follower_reads_enabled to:

  • true to enable follower reads (default)
  • false to disable follower reads
> SET CLUSTER SETTING kv.closed_timestamp.follower_reads_enabled = false;

When to use follower reads

Follower reads return consistent historical reads; currently a minimum of 48 seconds in the past, though we are actively working on reducing that number.

As long as your SELECT operations can tolerate slightly outdated data, Follower reads can reduce read latencies and increase throughput.

When not to use follower reads

You should not use follower reads when you need up-to-date data.

Make follower read-compatible queries

Any SELECT statement with an AS OF SYSTEM TIME value at least 48 seconds in the past can be served by any replica (i.e., can be a Follower Read).

To simplify this calculation, we've added a convenience function that will always set the AS OF SYSTEM TIME value to the minimum required for follower reads, experimental_follower_read_timestamp():

SELECT ... FROM ... AS OF SYSTEM TIME experimental_follower_read_timestamp();

Make follower read-compatible transactions

You can set the AS OF SYSTEM TIME value for all operations in a read-only transaction:


SET TRANSACTION AS OF SYSTEM TIME experimental_follower_read_timestamp();

SAVEPOINT cockroach_restart;



Using the SET TRANSACTION statement as shown in the example above will make it easier to use the follower reads feature from drivers and ORMs.

How follower reads works

In CockroachDB's general architecture, all reads are served by a range's leaseholder, which is a replica elected to coordinate all write operations. Because this node contains information about all of a range's writes, it can also serve reads for the range while still guaranteeing SERIALIZABLE isolation. With this architecture, the client might need to communicate with a machine that is far away, creating greater network latencies.

However, if you were to lower the isolation requirements of an operation, it's possible to serve the read from any replica, not only the leaseholder, given that the data can be sufficiently old.

To accomplish this in CockroachDB, we've created a mechanism to let you express that any node can serve the request (kv.closed_timestamp.follower_reads_enabled) and that a historical read is sufficient (AS OF SYSTEM TIME), given that the argument to AS OF SYSTEM TIME is sufficiently in the past (experimental_follower_read_timestamp().

For a more detailed explanation, you can also read the follower reads RFC.

Reading from followers

Each CockroachDB node tracks a property called its "closed timestamp", which means that no new writes can ever be introduced below that timestamp. The closed timestamp advances forward by some target interval behind the current time. If the replica receives a write at a timestamp less than its closed timestamp, it rejects the write.

With follower reads enabled, any replica on a node can serve a read for a key as long as the time at which the operation is performed (i.e., the AS OF SYSTEM TIME value) is less or equal to the node's closed timestamp.

Determining which node to read from

Every node keeps a record of its latency with all other nodes in the system. When a gateway node in cluster with follower reads enabled receives a request to read a key with a sufficiently old AS OF SYSTEM TIME value, it forwards the request to the closest node that contains a replica of the data––whether it be a follower or the leaseholder.

Interactions with long-running writes

Long-running write transactions will create write intents with a timestamp near when the transaction began. When a follower read encounters a write intent, it will often end up in a Wait Queue, waiting for the operation to complete; however, this runs counter to the benefit follower reads provides.

To counteract this, you can issue all follower reads in explicit transactions set with HIGH priority:

BEGIN PRIORITY HIGH AS OF SYSTEM TIME experimental_follower_read_timestamp();

SAVEPOINT cockroach_restart;



See Also

Yes No
On this page

Yes No