OBKV-HBase supports weak-consistency reads and near reads. This topic describes the principles, supported versions, routing strategies, and usage of weak-consistency reads and near reads.
The traditional strong-consistency read mode can easily cause performance bottlenecks in high-concurrency or low-latency scenarios. To address this issue, OBKV-HBase supports weak-consistency reads (hereinafter referred to as weak reads) and near reads, enabling users 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) and data is replicated in multiple copies.
In the traditional strong-consistency read mode, the client preferentially reads from the leader replica. This causes two problems:
- The leader replica is under high pressure and can easily become a performance bottleneck. In addition, if the leader replica fails, the entire IDC becomes unavailable.
- Users in Guangzhou or Shanghai must read data through the Beijing IDC, which increases network latency.
Therefore, we introduce weak reads and near reads to address this issue:
- Weak read: Allows the client to read data from non-leader replicas (such as followers or replicas). 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 closest to its geographical location or network distance, reducing network latency and improving access speed and user experience.
Supported versions
To use this feature, you must meet the version requirements for the OceanBase AI Database cluster, ODP, and OBKV-HBase client:
Component |
Supported versions |
|---|---|
| ODP | 4.3.6.2 |
| OBKV-HBase | 2.5.0 |
Procedure for direct connection mode
Step 1: Configure the IDC of the OceanBase AI Database cluster
Log on to the OceanBase AI Database cluster as root@sys and follow these steps to configure the IDC and region information of the cluster. 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 of
z1. TheREGIONparameter specifies the region where the zone is located. We recommend that you use a city name (case-sensitive).ALTER SYSTEM MODIFY ZONE "z1" SET REGION = "SHANGHAI";Set the IDC of
z1. TheIDCparameter specifies the IDC where the zone is located. We recommend that you use the actual IDC name (lowercase).ALTER SYSTEM MODIFY ZONE "z1" SET IDC = "zue";
After the configuration is completed, 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 client weak read parameters
Parameter description
The key parameters for weak reads are described as follows:
Parameter |
Type |
Case-sensitive |
Options |
Default value |
Description |
|---|---|---|---|---|---|
| hbase.htable.read.consistency | String | No | "strong" or "weak" | "strong" |
|
| hbase.htable.client.idc | String | No | Actual IDC name | "" |
|
| hbase.htable.client.route.policy | String | No | "follower_first" or "follower_only" | "follower_first" |
|
Priority of parameters: OBKV-HBase supports global parameters and statement-level parameters. The priority is as follows: statement-level parameters > global parameters. The following sections describe the configuration methods.
Set global weak-read parameters in the configuration file
This method is suitable for smooth migration from native HBase to OBKV-HBase without modifying existing business code. You only need to set the global weak-read parameters in the hbase-site.xml or core-site.xml configuration file to enable weak reads.
In the following example, hbase.htable.read.consistency is set to weak, hbase.htable.client.idc to idc1, and hbase.htable.client.route.policy to follower_first in the hbase-site.xml file. As a result, query operations are preferentially routed to the follower replica in the idc1 IDC.
<configuration>
<property>
<name>hbase.htable.read.consistency</name>
<value>weak</value>
</property>
<property>
<name>hbase.htable.client.idc</name>
<value>idc1</value>
</property>
<property>
<name>hbase.htable.client.route.policy</name>
<value>follower_first</value>
</property>
</configuration>
Set global weak-read parameters in the code
This method is suitable for businesses that require code modification. You only need to set the global weak-read parameters in the code to enable weak reads. In the following example, hbase.htable.client.idc is set to idc1, hbase.htable.client.route.policy to follower_first, and hbase.htable.read.consistency to weak in the configuration. As a result, query operations are preferentially routed to the follower replica in the idc1 IDC.
import static com.alipay.oceanbase.hbase.constants.OHConstants.*;
Configuration config = HBaseConfiguration.create();
config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // Set client IDC information.
config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // Set routing policy.
config.set(HBASE_HTABLE_READ_CONSISTENCY, "weak"); // Set consistency level.
Set statement-level weak-read parameters in the code
This method is suitable for businesses that require code modification. You only need to set the statement-level weak-read parameters in the code to enable weak reads.
The following examples show usage in different scenarios:
In the following example, hbase.htable.client.idc is set to idc1 and hbase.htable.client.route.policy to follower_first in the configuration. Then, hbase.htable.read.consistency is set to weak for the get operation by using setAttribute. In this way, the get operation is preferentially routed to the follower replica in the idc1 IDC.
String tableName = "test";
Configuration config = HBaseConfiguration.create();
config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // Set client IDC information.
config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // Set routing policy.
Connection hbaseConnection = ConnectionFactory.createConnection(config);
Table table = hbaseConnection.getTable(TableName.valueOf(tableName));
String family = "cf1";
String rowkey = "k1";
Get get = new Get(rowkey.getBytes());
get.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // Set statement-level read consistency.
get.addColumn(family.getBytes(), "q1".getBytes());
Result result = table.get(get);
The following example first sets hbase.htable.client.idc to idc1 and hbase.htable.client.route.policy to follower_first in the configuration. Then, it sets hbase.htable.read.consistency to weak for the list<get> operation by using the setAttribute method. As a result, the list<get> operation is preferentially routed to the follower replica in the idc1 IDC.
String tableName = "test";
Configuration config = HBaseConfiguration.create();
config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // Set the client IDC information.
config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // Set the routing policy.
Connection hbaseConnection = ConnectionFactory.createConnection(config);
Table table = hbaseConnection.getTable(TableName.valueOf(tableName));
List<Get> gets = new ArrayList<>();
String family = "cf1";
String rowkey1 = "k1";
// Weak reads must be set for all get requests in the same batch. Partial weak reads are not supported.
Get get1 = new Get(rowkey1.getBytes());
get1.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // Set statement-level read consistency.
get1.addColumn(family.getBytes(), "q1".getBytes());
String rowkey2 = "k2";
Get get2 = new Get(rowkey2.getBytes());
get2.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // Set statement-level read consistency.
get2.addColumn(family.getBytes(), "q2".getBytes());
gets.add(get1, get2);
Result[] res = table.get(gets);
In this example, hbase.htable.client.idc is first set to idc1 and hbase.htable.client.route.policy to follower_first in the configuration. Then, hbase.htable.read.consistency is set to weak for the scan operation by using the setAttribute method. As a result, the scan operation is preferentially routed to the follower replica in the idc1 IDC.
String tableName = "test";
Configuration config = HBaseConfiguration.create();
config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // Set the client IDC information.
config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // Set the routing policy.
Connection hbaseConnection = ConnectionFactory.createConnection(config);
Table table = hbaseConnection.getTable(TableName.valueOf(tableName));
String family = "cf1";
String rowkey = "k1";
Scan scan = new Scan();
scan.withStartRow(rowkey.getBytes());
scan.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // Set the statement-level read consistency.
scan.addColumn(family.getBytes(), "q1".getBytes());
ResultScanner resultScanner = table.getScanner(scan);
Result result;
while ((result = resultScanner.next()) != null) {
byte[] value = result.getValue(family.getBytes(), "q1".getBytes());
}
Procedure for ODP mode
Step 1: Configure the IDC of the OceanBase AI Database cluster
Log on to the OceanBase AI Database cluster as root@sys and follow these steps to configure the IDC and region information of the cluster. Assume that the cluster contains three zones, each with one OBServer node. The following example uses z1:
Set the region of z1. The
REGIONparameter 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 of z1. The
IDCparameter specifies the IDC where the zone is located. We recommend that you set it to the actual IDC name (lowercase).ALTER SYSTEM MODIFY ZONE "z1" SET IDC = "zue";
After the configuration is completed, 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. Based on your actual deployment, this allows weak-read traffic to be routed preferentially to replicas in the corresponding IDC. For example, to preferentially route all weak-read requests to the IDC where z1 is located, use the following configuration:ALTER PROXYCONFIG SET proxy_idc_name = 'zue';You can set the
proxy_route_policyparameter to further specify the replica routing policy. The following example preferentially reads from a follower replica:ALTER PROXYCONFIG SET proxy_route_policy = 'follower_first';
Step 3: Configure client weak-read parameters
Refer to the examples in Step 2: Configure client weak-read parameters to set the weak-read parameters.