客户端简介与使用说明 | OceanBase 文档中心

客户端简介与使用说明

更新时间：2023-08-03 17:20:32

编辑

TableAPI 是 OceanBase 针对 NOSQL 场景推出的一种 OBServer 服务端的访问模式。本篇将简单介绍如何使用客户端 ob_table_client_java 进行接口访问。

客户端简介

总体上看，应用层可通过 TableAPI 或 SQL 两种方式访问到 OBServer，分别对应 NOSQL 模式和 SQL 模式。

NOSQL 模式下，客户端接口 JavaClient 通过 RPC 协议与 OBServer 通信，同时客户端支持丰富多样的操作函数，功能上基本可以满足大部分场景的需求。

相比于 SQL 模式，整体流程上，TableAPI 并没有复杂的 SQL 语法语义等繁琐的解析以及生成执行计划等过程，但却具有与 SQL 模式几乎同等的事务以及存储能力，使用起来相对简单。整体流程图如下：

TableApi 客户端流程图

使用参考

本章节将介绍如何使用 ob_table_client_java 客户端以及具体的接口。

创建 OceanBase 数据库

您可使用 obclient 或 MySQL 客户端登录 OceanBase，具体方法可参考通过 obclient 连接 OceanBase 租户和通过 MySQL 客户端连接 OceanBase 数据库。

执行 CREATE TABLE 指令创建表。

CREATE TABLE IF NOT EXISTS `test_varchar_table_00` (
    `c1` varchar(20) NOT NULL,
    `c2` varchar(20) DEFAULT NULL,
    `c3` varchar(20) DEFAULT NULL,
    PRIMARY KEY (`c1`)
);

引入 maven obkv-table-client 依赖

打开 pom.xml 文件，添加如下信息：

<groupId>com.oceanbase</groupId>
<artifactId>obkv-table-client</artifactId>
<version>0.1.0</version>

init 接口

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

示例如下：

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

参数说明：

setFullUserName：设置数据库用户名，您需自行定义。
setParamURL：若使用 OCP 部署，则输入 OCP URL。
setPassword：数据库访问密码，您需自行定义，如果没有可以不设置。

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。

说明

具体如何使用客户端，您可参考客户端使用示例。