OBKV-Table supports weak-consistency reads and near reads. This topic describes the principles, supported versions, routing strategies, and usage of these two features.
The traditional strong-consistency read mode can easily cause performance bottlenecks in high-concurrency or low-latency scenarios. To address this issue, OBKV-Table supports weak-consistency reads (hereinafter referred to as weak reads) and near reads, which allow you to balance data consistency and access efficiency more flexibly.
Principle
Imagine a scenario where your database is deployed across multiple IDCs (for example, Beijing, Shanghai, and Guangzhou), with multiple copies of the data replicated.
In the traditional strong-consistency read mode, the client prioritizes reading from the leader replica. This leads to two issues:
- The leader replica experiences high load and can become a performance bottleneck. Moreover, if the leader fails, the entire IDC becomes unavailable.
- Users in Guangzhou or Shanghai have to go through the Beijing IDC to read data, increasing network latency.
Therefore, weak reads and near reads are introduced to address these issues:
- Weak read: The client reads data from non-leader replicas (such as followers). Reading data in this mode introduces a slight delay but improves read performance and system availability.
- Near read: The client preferentially reads from the replica in the IDC closest to its geographical location or network distance, which reduces network latency and improves access speed and user experience.
Supported versions
To use this feature, the OceanBase AI Database cluster, ODP, and the OBKV-Table Java client must meet the following version requirements:
Component |
Supported version |
|---|---|
| ODP | 4.3.6.2 |
| OBKV-Table | 2.3.0 |
Procedure
Step 1: Configure the IDC for the OceanBase AI Database cluster
Log on to the OceanBase AI Database cluster as root@sys and configure the IDC information as follows. Assume that the cluster contains three zones, each with one OBServer node, and the IP addresses of the zones are 10.0.0.1, 10.0.0.2, and 10.0.0.3 respectively:
Set the region for
z1. TheREGIONparameter specifies the region information of the zone. We recommend that you use the city name (case-sensitive).ALTER SYSTEM MODIFY ZONE "z1" SET REGION = "SHANGHAI";Set the IDC for
z1. TheIDCparameter specifies the IDC information of the zone. We recommend that you use the actual IDC name (in lowercase).ALTER SYSTEM MODIFY ZONE "z1" SET IDC = "zue";
After completion, the cluster deployment is shown in the following table:
OBServer node IP |
Zone |
IDC |
Region |
|---|---|---|---|
| 10.0.0.1 | z1 | zue | SHANGHAI |
| 10.0.0.2 | z2 | xue | SHANGHAI |
| 10.0.0.3 | z3 | yue | HANGZHOU |
Step 2: Configure client weak read parameters
APIs and parameters
API |
Parameter description |
Case-sensitive |
Options |
Feature description |
|---|---|---|---|---|
| public void setReadConsistency(ObReadConsistency readConsistency) | readConsistency: the consistency level | No |
|
The consistency level, which controls whether to enable weak-consistency reads:
|
| public void setCurrentIDC(String idc) | idc: the name of the IDC where the client is located | No | The actual IDC name | The IDC name of the client:
|
| public void setRoutePolicy(ObRoutePolicy policy) | policy: the routing policy | No |
|
The routing policy:
|
Statement-level parameters take precedence over global parameters. The following sections describe the specific configuration methods.
Set global weak read parameters in ObTableClient
The following example shows how to set weak-consistency read parameters in ObTableClient: it sets the consistency level to ObReadConsistency.WEAK, specifies the current IDC as idc1, and selects the ObRoutePolicy.FOLLOWER_FIRST routing policy. After the configuration, query operations are preferentially routed to follower replicas in the idc1 IDC, which improves performance and reduces latency.
ObTableClient client = new ObTableClient();
... // Set other connection parameters.
client.setCurrentIDC("idc1");
client.setReadConsistency(ObReadConsistency.WEAK);
client.setRoutePolicy(ObRoutePolicy.FOLLOWER_FIRST);
client.init();
Set statement-level weak-consistency read parameters in a query
This example sets the current IDC of the client to idc1 and the routing policy to ObRoutePolicy.FOLLOWER_FIRST in ObTableClient. It also sets the consistency level to ObReadConsistency.WEAK for the get operation. In this way, get operations are preferentially routed to follower replicas in the idc1 IDC.
ObTableClient client = new ObTableClient();
... // Set other connection parameters.
client.setCurrentIDC("idc1"); // Set the current IDC.
client.setRoutePolicy(ObRoutePolicy.FOLLOWER_FIRST); // Set the routing policy.
client.init();
String tableName = "test";
String rowkey = "key";
Map<String, Object> result = client.get(tableName).setRowKey(row(colVal("c1", rowkey)))
.setReadConsistency(ObReadConsistency.WEAK) // Set weak-consistency read
.select("c2").execute();
This example sets the current IDC of the client to idc1 and the routing policy to ObRoutePolicy.FOLLOWER_FIRST in ObTableClient. It also sets the consistency level to ObReadConsistency.WEAK in the BatchOperation API. In this way, batch get operations are preferentially routed to follower replicas in the idc1 IDC.
ObTableClient client = new ObTableClient();
... // Set other connection parameters.
client.setCurrentIDC("idc1"); // Set the current IDC.
client.setRoutePolicy(ObRoutePolicy.FOLLOWER_FIRST); // Set the routing policy.
client.init();
String tableName = "test";
String rowkey1 = "key1";
String rowkey2 = "key2";
BatchOperation batch = client.batchOperation(tableName);
batch.setReadConsistency(ObReadConsistency.WEAK); // Set weak-consistency read. Note: All reads in the same batch must be weak-consistency reads; partial weak-consistency reads are not supported.
Get get1 = client.get(tableName).setRowKey(row(colVal("c1", rowkey1)))
.select("c2");
Get get2 = client.get(tableName).setRowKey(row(colVal("c1", rowkey2)))
.select("c2");
batch.addOperation(get1, get2);
BatchOperationResult res = batch.execute();
In this example, the current IDC of the client is set to idc1 and the routing policy is set to ObRoutePolicy.FOLLOWER_FIRST in ObTableClient. The consistency level is set to ObReadConsistency.WEAK for the query operation. Therefore, queries are preferentially routed to follower replicas in the idc1 IDC.
ObTableClient client = new ObTableClient();
... // Set other connection parameters.
client.setCurrentIDC("idc1"); // Set the current IDC.
client.setRoutePolicy(ObRoutePolicy.FOLLOWER_FIRST); // Set the routing policy.
client.init();
String tableName = "test";
String startRowkey = "key1";
String endRowkey = "key5";
QueryResultSet res = client.query(tableName)
.addScanRange(new Object[] { startRowkey }, new Object[] { endRowkey })
.setScanRangeColumns("c1")
.setReadConsistency(ObReadConsistency.WEAK)
.select("c2")
.execute();
while (res.next()) {
Map<String, Object> valueMap = res.getRow();
System.out.println(valueMap.get("c2"));
}
Procedure for using ODP mode
Step 1: Configure the IDC for the OceanBase AI Database cluster
Log in to the OceanBase AI Database cluster as root@sys and configure the IDC and region information of the cluster as follows. Assume that the cluster contains three zones, with one OBServer node in each zone. The following example configures zone z1:
Set the region for
z1. TheREGIONparameter specifies the region where the zone is located. We recommend that you set it to a city name (case-sensitive).ALTER SYSTEM MODIFY ZONE "z1" SET REGION = "SHANGHAI";Set the IDC for zone
z1. TheIDCparameter specifies the IDC where the zone is located. We recommend that you set it to the actual name of the IDC (in lowercase).ALTER SYSTEM MODIFY ZONE "z1" SET IDC = "zue";
After completion, the cluster deployment information is as follows:
OBServer node IP |
Zone |
IDC |
Region |
|---|---|---|---|
| 10.0.0.1 | z1 | zue | SHANGHAI |
| 10.0.0.2 | z2 | xue | SHANGHAI |
| 10.0.0.3 | z3 | yue | HANGZHOU |
Step 2: Configure ODP weak-read parameters
You can set the
proxy_idc_nameparameter to specify the IDC to which ODP belongs in the LDC system. This allows weak-read traffic to be routed to replicas in the corresponding IDC based on your actual deployment. For example, to preferentially route all weak-read requests to the IDC where zonez1is located, use the following configuration:ALTER PROXYCONFIG SET proxy_idc_name = 'zue';You can also set the
proxy_route_policyparameter to specify the replica routing policy. The following example preferentially reads from follower replicas:ALTER PROXYCONFIG SET proxy_route_policy = 'follower_first';
Step 3: Configure client weak-read parameters
For how to set weak-read parameters, see Step 2 in the preceding procedure.