Skip to main content
Version: Nightly

Query Read Replicas

GreptimeDB allows you to read from Region Replicas (follower regions) to reduce load on Write Replicas (Leader regions) and improve query scalability. You can control the read preference through both SQL and HTTP protocols.

Read Preference Options​

The READ_PREFERENCE setting accepts the following values:

  • leader Always read from write replicas.

  • follower Read only from read replicas The query will fail if no read replicas exist.

  • follower_preferred Prefer read replicas but fall back to write replicas if read replicas are unavailable.

SQL Protocol​

You can set the read preference in a SQL session:

SET READ_PREFERENCE = 'follower';

HTTP Protocol​

For HTTP requests, specify the X-Greptime-Read-Preference header.

Example:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Greptime-Read-Preference: follower" \
  -d "sql=select * from monitoring" \
  http://localhost:4000/v1/sql

Example: Reading from Read Replicas​

Before reading from Read Replicas, you need to add Read Replicas to the table. See Replica Management for more details.

Insert some data into a table:

INSERT INTO foo (ts, i, s)
VALUES
  (1, -1, 's1'),
  (2, 0, 's2'),
  (3, 1, 's3');

Set the read preference to read replicas:

SET READ_PREFERENCE = 'follower';

Query the data:

SELECT * FROM foo ORDER BY ts;

+----------------------------+------+------+
| ts                         | i    | s    |
+----------------------------+------+------+
| 1970-01-01 00:00:00.001000 |   -1 | s1   |
| 1970-01-01 00:00:00.002000 |    0 | s2   |
| 1970-01-01 00:00:00.003000 |    1 | s3   |
+----------------------------+------+------+

Verifying Follower Reads​

To confirm that queries are served by read replicas, use EXPLAIN ANALYZE:

EXPLAIN ANALYZE SELECT * FROM foo ORDER BY ts;
  • A non-zero other_ranges value indicates read replicas were involved.
  • With the VERBOSE option, you can see details like this:
extension_ranges: [LeaderMemtableRange{leader: Peer { id: 1, addr: "192.168.50.189:14101" }, num_rows: 2, time_range: (1::Millisecond, 2::Millisecond) ...

If the query runs only on leaders, this extension_ranges section will not appear.