refactor: refactor Read Replica documentation structure

Author: WenyXu

docs/enterprise/read-replica.md

@@ -0,0 +1,181 @@
+---
+keywords: [enterprise, cluster, read replicas, leader region, follower region]
+description: An overview, key concepts, and step-by-step guides for managing read replicas in GreptimeDB Enterprise.
+---
+
+# Manage Read Replicas
+
+This guide explains how to manage **Read Replicas (follower regions)** in GreptimeDB Enterprise, including how to add and remove read replicas at both the table and region levels, inspect the current regions distribution with the `SHOW REGION`, and apply placement constraints and recommended best practices for performance.
+
+## Adding Read Replicas to a Table
+
+Adding a Read Replica is as simple as executing one SQL command:
+
+```sql
+ADMIN ADD_TABLE_FOLLOWER(<table_name>)
+```
+
+Read Replica peers for each region are allocated based on the workload types of the datanodes. **For optimal performance, it is strongly recommended to [configure Datanode groups](/enterprise/deployments-administration/deploy-on-kubernetes/configure-datanode-groups.md) to separate read and write workloads into different datanode groups.**
+
+This is the function in GreptimeDB for adding read replicas to. The parameters are:
+
+- `table_name`: The name of the table to add read replicas to.
+
+Next is an example to illustrate steps to add read replicas to a table.
+
+First start a GreptimeDB Enterprise Cluster with 3 Datanodes. Then create a table:
+
+```sql
+CREATE TABLE foo (
+  ts TIMESTAMP TIME INDEX,
+  i INT PRIMARY KEY,
+  s STRING,
+) PARTITION ON COLUMNS ('i') (
+  i <= 0,
+  i > 0,
+);
+```
+
+
+Using the `SHOW REGION`, we can find the regions distribution information:
+
+```sql
+SHOW REGION FROM foo;
+
++-------+---------------+------+--------+
+| Table | Region        | Peer | Leader |
++-------+---------------+------+--------+
+| foo   | 4398046511104 |    0 | Yes    |
+| foo   | 4398046511105 |    1 | Yes    |
++-------+---------------+------+--------+
+```
+
+This shows two write replicas (leader regions) on Datanodes `1` and `2`.
+
+Then to add read replicas (Follower regions):
+
+```sql
+ADMIN ADD_TABLE_FOLLOWER('foo');
+```
+
+After the read replicas are added, find the regions distribution information:
+
+```sql
+SHOW REGION FROM foo;
+
++-------+---------------+------------+--------+
+| Table | Region        | Peer       | Leader |
++-------+---------------+------------+--------+
+| foo   | 4398046511104 |          0 | Yes    |
+| foo   | 4398046511104 | 4294967296 | No     |
+| foo   | 4398046511105 |          1 | Yes    |
+| foo   | 4398046511105 | 4294967297 | No     |
++-------+---------------+------------+--------+
+```
+
+Now, read replicas can be found on Datanode `4294967296` and `4294967297`.
+
+## Removing Read Replicas from a Table
+
+Removing a Read Replica is as simple as executing one SQL command:
+
+```sql
+ADMIN REMOVE_TABLE_FOLLOWER(<table_name>)
+```
+
+This is the function in GreptimeDB for removing read replicas from a table. The parameters are:
+
+- `table_name`: The name of the table to remove read replicas from.
+
+This command removes **the most recently added read replica' peers from each region**.
+
+For example, before running the command:
+
+```sql
+SHOW REGION FROM foo;
++-------+---------------+------------+--------+
+| Table | Region        | Peer       | Leader |
++-------+---------------+------------+--------+
+| foo   | 4398046511104 |          0 | Yes    |
+| foo   | 4398046511104 | 4294967296 | No     |
+| foo   | 4398046511104 | 4294967297 | No     |
+| foo   | 4398046511105 |          1 | Yes    |
+| foo   | 4398046511105 | 4294967296 | No     |
+| foo   | 4398046511105 | 4294967297 | No     |
++-------+---------------+------------+--------+
+```
+
+Here, region `4398046511104` has two read replicas on peers (`4294967296`, `4294967297`), and region `4398046511105` also has two read replicas on peers (`4294967296`, `4294967297`).
+After executing:
+
+```sql
+ADMIN REMOVE_TABLE_FOLLOWER('foo');
++------------------------------------+
+| ADMIN REMOVE_TABLE_FOLLOWER('foo') |
++------------------------------------+
+|                                  0 |
++------------------------------------+
+```
+
+The most recently added read replicas' peers of each region are removed:
+
+* Region `4398046511104`: removed read replica on peer `4294967297`.
+* Region `4398046511105`: removed read replica on peer `4294967296`.
+
+Result:
+
+```sql
+SHOW REGION FROM foo;
++-------+---------------+------------+--------+
+| Table | Region        | Peer       | Leader |
++-------+---------------+------------+--------+
+| foo   | 4398046511104 |          0 | Yes    |
+| foo   | 4398046511104 | 4294967296 | No     |
+| foo   | 4398046511105 |          1 | Yes    |
+| foo   | 4398046511105 | 4294967297 | No     |
++-------+---------------+------------+--------+
+```
+
+## Adding Read Replica to a Region
+```sql
+ADMIN ADD_REGION_FOLLOWER(<region_id>, <datanode_id>)
+```
+
+This is the function in GreptimeDB for adding read replicas to a region. The parameters are:
+
+- `region_id`: The id of the region to add Read Replica to.
+- `datanode_id`: The id of the datanode to add Read Replica to.
+
+A read replica and a write replica cannot be placed on the same datanode. Additionally, each datanode can host only one read replica per region.
+
+Example:
+
+```sql
+-- Add a read replica for region 4398046511104 on datanode 2
+ADMIN ADD_REGION_FOLLOWER(4398046511104, 2);
+```
+
+If the specified datanode already hosts a read replica for that region, or is the write replica (leader) of that region, the command will be rejected.
+
+## Removing Read Replica from a Region
+```sql
+ADMIN REMOVE_REGION_FOLLOWER(<region_id>, <datanode_id>)
+```
+
+This is the function in GreptimeDB for removing read replicas from a region. The parameters are:
+
+- `region_id`: The id of the region to remove read replica from.
+- `datanode_id`: The id of the datanode to remove read replica from.
+
+
+Example:
+
+```sql
+-- Remove the read replica on datanode 2 for region 4398046511104
+ADMIN REMOVE_REGION_FOLLOWER(4398046511104, 2);
+```
+
+
+## Next steps
+
+* [Query Read Replicas](/enterprise/read-replicas/query-read-replicas.md)