OBKV-Table Java 客户端支持的接口

更新时间：2024-10-28 23:00:00

init 接口

您可使用该接口初始化客户端操作对象 ObTableClient。

示例如下：

final ObTableClient client = new ObTableClient();  // 创建客户端实例
client.setFullUserName("your user name");  
client.setParamURL("your OCP addr url");  
client.setPassword("your password"); 
obTableClient.setSysUserName("your sys user name"); 
obTableClient.setSysPassword("your sys password");
client.init();

参数说明：

setFullUserName：设置数据库用户名，您需自行定义。
setParamURL：若使用 OCP 部署，则输入 OCP URL。
setPassword：数据库访问密码，您需自行定义，如果没有可以不设置。
setSysUserName：系统租户用户名，例如 proxyro@sys，请求路由时用于获取路由信息相关内部表。
setSysPassword：系统租户用户密码。

insert 接口

您可使用该接口插入一行记录，但如果主键冲突（即行已存在），则插入失败。

示例如下：

long insert(String tableName, Object rowkey, String[] columns, Object[] values);
long insert(String tableName, Object[] rowkeys, String[] columns, Object[] values);

// 样例，rowkey 对应表中的 primary key
client.insert( "testHash", 
     new Object[] { 1L, "partition".getBytes(), timeStamp },
     new String[] { "V" },       
     new Object[] { "value".getBytes() }
);

参数说明：

tableName：表名
rowkey：主键值
columns：插入的列名（一列或多列）
values：插入的列值
long：返回值，表示具体的插入数量（1行）

get 接口

您可使用该接口取回一行记录，如果行存在，则取回行，否则返回 empty。

示例如下：

Map<String, Object> get(String tableName, Object rowkey, String[] columns);
Map<String, Object> get(String tableName, Object[] rowkeys, String[] columns);

// rowkey 即 primary key
Map<String, Object> res = client.get("testHash",
           new Object[] { 1L, "partition".getBytes(), timestamp }, 
           new String[] { "K", "Q", "T","V" }
);

// 返回的结果 value 是 object，直接强转一下就行 例如 Long k = (Long) res.get("K");

参数说明：

tableName：表名
rowkey：主键值
columns：获取的列名（一行或多列）
Map<String, Object>：返回值，成功返回所选列结果，失败返回 empty

delete 接口

您可使用该接口删除一行记录，如果该行不存在，返回 affectrows = 0，否则返回具体删除的行数量（1）。

示例如下：

long delete(String tableName, Object rowkey);
long delete(String tableName, Object[] rowkeys);

// 样例，rowkey 对应表中的 primary key
client.delete("testHash", new Object[] { 1L, "partition".getBytes(), timeStamp });

// 返回结果表示 affectrows，这里返回 1L

参数说明：

tableName：表名
rowkey：需要删除的主键记录
long：返回值，表示具体删除的行数量（1行）

update 接口

您可使用该接口更新一行记录，如果目标行不存在，返回 affectrows = 0，否则返回具体更新的行数量（1）。

示例如下：

long update(String tableName, Object rowkey, String[] columns, Object[] values);
long update(String tableName, Object[] rowkeys, String[] columns, Object[] values);

// 样例，rowkey 为表的 primary_key
client.update("testHash",
              new Object[] { 1L, "partition".getBytes(), timeStamp }, 
              new String[] { "V" },
              new Object[] { "value1L".getBytes() }
);

// 返回结果表示 affectrows，这里返回 1L

参数说明：

tableName：表名
rowkey：更新的主键名
columns：更新的目标列（一列或多列）
values：需要更新的列值（一列或多列）
long 返回值，表示具体更新的行数量（1行）

replace 接口

您可使用该接口替换一行记录，使用该接口会出现以下三种情况：

目标行不存在，则插入记录。
目标行已存在（即主键冲突），则删除原纪录，然后再插入这行记录。
如果有唯一索引冲突，则删除所有引起冲突的行，然后再插入这行记录。

示例如下：

long replace(String tableName, Object rowkey, String[] columns, Object[] values);
long replace(String tableName, Object[] rowkeys, String[] columns, Object[] values);

// 样例，rowkey 为表的 primary_key
client.replace("testHash",
            new Object[] { 1L, "partition".getBytes(), timeStamp }, 
            new String[] { "V" },
            new Object[] { "value1L".getBytes() }
);

// 返回结果表示 affectrows，这里返回 1L

参数说明：

tableName：表名
rowkey：主键名
columns：替换目标的列名（一列或多列）
values：替换目标的列值（一列或多列）
long：返回值，表示具体 replace 的行数量（1行）

insertOrupdate 接口

您可使用该接口插入或修改一行记录，使用该接口会出现以下三种情况：

目标行不存在，则插入记录。
目标行已存在（即主键冲突），则更新这行记录。
如果插入有唯一索引冲突，则也执行更新操作。

示例如下：

long insertOrUpdate(String tableName, Object rowkey, String[] columns, Object[] values);
long insertOrUpdate(String tableName, Object[] rowkeys, String[] columns, Object[] values);

// 样例，rowkey 为表的 primary_key
client.insertOrUpdate("testHash",
            new Object[] { 1L, "partition".getBytes(), timestamp }, 
            new String[] { "V" },
            new Object[] { "bb".getBytes() }
);

// 返回结果表示 affectrows，这里返回 1L

参数说明：

tableName：表名
rowkey：主键名
columns：操作的目标列名（一列或多列）
values：目标列值（一列或多列）
long：返回值，表示具体 insert_or_update 的行数量（1行）

increment 接口

您可使用该接口把指定列的值原子地增加某个增量值（可以为负数），使用该接口会出现以下三种情况：

计算结果溢出列类型的值域，报错。
目标行不存在，则插入，把增量值设置为初值（即等价于原值为 0）。
目标行存在，但是指定列的值为 NULL，把增量值设置为初值（即等价于原值为 0）。

说明

该接口是 OceanBase 1.4.75 开始新增特性，支持操作整型列类型，含 tinyint、smallint、mediumint、int、bigint 及对应的无符号列类型，其他列类型报错。

示例如下：

Map<String, Object> increment(String tableName, Object rowkey, String[] columns,Object[] values, boolean withResult);

Map<String, Object> increment(String tableName, Object[] rowkeys, String[] columns, Object[] values, boolean withResult);

// 样例，rowkey 为表的 primary_key，默认为 null，所以最后结果为 c2=1,c3=2
Client.increment("test_increment", 
"test_null", 
         new String[] { "c2", "c3" }, 
         new Object[] { 1, 2 }, true );

参数说明：

tableName：表名
rowkey：主键值
columns：自增目标列名（一列或多列）
values：目标列自增值（一列或多列）
withResult：判断是否返回自增结果集
Map<String, Object>：返回值，如果 withResult = false，返回结果为 Map.empty。

append 接口

您可使用该接口把指定列的值原子地追加某个串，使用该接口会出现以下三种情况：

计算结果溢出列类型的值域，报错。
目标行不存在，则插入，把增量值设置为初值（即等价于原值为空串）。
目标行存在，但是指定列的值为 NULL，把增量值设置为初值（即等价于原值为空串）。

说明

该接口是 OceanBase 1.4.75 开始新增特性，支持操作 varchar/varbinary 类型，其他列类型报错。

示例如下：

Map<String, Object> append(String tableName, Object rowkey, String[] columns, Object[] values,boolean withResult);

Map<String, Object> append(String tableName, Object[] rowkeys, String[] columns, Object[] values, boolean withResult);

// 先插入一条数据 c2 = {1} , c3 = {"P"}
client.insert("test_append", "test_normal", new String[] { "c2", "c3" }, new Object[] { new byte[] { 1 }, "P" });
// append 以后，c2 = {1, 2}, c3 = {"PY"}
Map<String, Object> res = client.append("test_append", "test_normal", new String[] { "c2", "c3" }, new Object[] { new byte[] { 2 }, "Y" }, true);

参数说明：

tableName：表名
rowkey：主键值
columns：增加串的目标列名（一列或多列）
values：目标列增加串值（一列或多列）
withResult：判断是否返回增加串结果集
Map<String, Object>：返回值，如果 withResult = false，返回结果为 Map.empty。

scan 接口

您可使用该接口进行范围查找，支持根据主键或主键的前缀进行范围扫描，也可以不指定主键，根据索引或者索引前缀范围进行扫描查询，接口支持多 range 扫描和逆序扫描。

示例如下：

// 样例
TableQuery tableQuery = client.query("table_name"); // 根据表名，创建扫描对象
re"sultSet = tableQuery.select("column2").primaryIndex().addScanRange("min1", "max1).addScanRange("min2", "max2").setBatchSize(batch_size).execute();

while(resultSet.next()) {
 Map<String, Object> value = resultSet.getRow();
}

参数说明：

table_name：待扫描的表名。
primaryIndex：设定根据主键值扫描。
column2：设定获取结果的列，例如一张表有 4 列，column1~column4，而只需要返回 column2 这一列的数据。
addScanRange：添加查找范围，其中 min，max 为范围的左右区间值。
batch_size：在满足扫描条件的行记录中，每一批需要返回的数量。

batch 接口

您可使用该接口批量执行多种操作组合。

示例如下：

TableBatchOps batchOps = client.batch("test_varchar_table");
batchOps.insert("foo", new String[] { "c2" }, new String[] { "bar" });
batchOps.get("foo", new String[] { "c2" });
batchOps.delete("foo");

List<Object> results = batchOps.execute();
// 上面返回结果的list，insert 返回 affectedRows, get 返回 map 结果，delete 返回 affectedRows

参数说明：

TableBatchOps：操作对象，通过 ObTableClient 对象创建，如上述的 client.batch(table_name)。
List<Object>：返回值，包含所有操作的结果集合，如上述的 insert、get、delete。