---
title: "客户端简介与使用说明 | OceanBase 文档中心"
description: 客户端简介与使用说明 TableAPI 是 OceanBase 针对 NOSQL 场景推出的一种 OBServer 服务端的访问模式。本篇将简单介绍如何使用客户端 ob_table_client_java 进行接口访问。 客户端简介 总体上看，应用层可通过 TableAPI 或 SQL 两种方式访问到 OBServe…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言
- 中文站 - 简体中文
- International - English
- 日本站 - 日本語
文档反馈 OceanBase 数据库分布式版 - V 3.1.4 社区版
# 客户端简介与使用说明
更新时间：2023-08-03 17:20:32
[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V3.1.4/zh-CN/1800.supporting-tools/600.tableapi/200.use-of-the-tableapi-client/100.introduction-to-the-client-and-instructions-of-use.md)
TableAPI 是 OceanBase 针对 NOSQL 场景推出的一种 OBServer 服务端的访问模式。本篇将简单介绍如何使用客户端 ob_table_client_java 进行接口访问。
## 客户端简介
总体上看，应用层可通过 TableAPI 或 SQL 两种方式访问到 OBServer，分别对应 NOSQL 模式和 SQL 模式。
NOSQL 模式下，客户端接口 JavaClient 通过 RPC 协议与 OBServer 通信，同时客户端支持丰富多样的操作函数，功能上基本可以满足大部分场景的需求。
相比于 SQL 模式，整体流程上，TableAPI 并没有复杂的 SQL 语法语义等繁琐的解析以及生成执行计划等过程，但却具有与 SQL 模式几乎同等的事务以及存储能力，使用起来相对简单。整体流程图如下：
## 使用参考
本章节将介绍如何使用 ob_table_client_java 客户端以及具体的接口。
### 创建 OceanBase 数据库
您可使用 obclient 或 MySQL 客户端登录 OceanBase，具体方法可参考 [通过 obclient 连接 OceanBase 租户](https://www.oceanbase.com/docs/community-observer-cn-10000000000449575) 和 [通过 MySQL 客户端连接 OceanBase 数据库](https://www.oceanbase.com/docs/community-observer-cn-10000000000449574)。
执行 CREATE TABLE 指令创建表。
```sql
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 文件，添加如下信息：
```basic
com.oceanbase
obkv-table-client
0.1.0
```
### init 接口
您可使用该接口初始化客户端操作对象 ObTableClient。
示例如下：
```java
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 接口
您可使用该接口插入一行记录，但如果主键冲突（即行已存在），则插入失败。
示例如下：
```java
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。
示例如下：
```java
Map get(String tableName, Object rowkey, String[] columns);
Map get(String tableName, Object[] rowkeys, String[] columns);
// rowkey 即 primary key
Map 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：返回值，成功返回所选列结果，失败返回 empty
### delete 接口
您可使用该接口删除一行记录，如果该行不存在，返回 affectrows = 0，否则返回具体删除的行数量（1）。
示例如下：
```java
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）。
示例如下：
```java
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() }
);
```
参数说明：
- tableName：表名
- rowkey：更新的主键名
- columns：更新的目标列（一列或多列）
- values：需要更新的列值（一列或多列）
- long 返回值，表示具体更新的行数量（1行）
### replace 接口
您可使用该接口替换一行记录，使用该接口会出现以下三种情况：
- 目标行不存在，则插入记录。
- 目标行已存在（即主键冲突），则删除原纪录，然后再插入这行记录。
- 如果有唯一索引冲突，则删除所有引起冲突的行，然后再插入这行记录。
示例如下：
```java
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() }
);
```
参数说明：
- tableName：表名
- rowkey：主键名
- columns：替换目标的列名（一列或多列）
- values：替换目标的列值 （一列或多列）
- long：返回值，表示具体 replace 的行数量（1行）
### insertOrupdate 接口
您可使用该接口插入或修改一行记录，使用该接口会出现以下三种情况：
- 目标行不存在，则插入记录。
- 目标行已存在（即主键冲突），则更新这行记录。
- 如果插入有唯一索引冲突，则也执行更新操作。
示例如下：
```java
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 及对应的无符号列类型，其他列类型报错。
示例如下：
```java
Map increment(String tableName, Object rowkey, String[] columns,Object[] values, boolean withResult);
Map 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：返回值，如果 withResult = false ，返回结果为 Map.empty。
### append 接口
您可使用该接口把指定列的值原子地追加某个串，使用该接口会出现以下三种情况：
- 计算结果溢出列类型的值域，报错。
- 目标行不存在，则插入，把增量值设置为初值（即等价于原值为空串）。
- 目标行存在，但是指定列的值为 NULL，把增量值设置为初值（即等价于原值为空串）。
> **说明**
>
>
>
> 该接口是 OceanBase 1.4.75 开始新增特性，支持操作 varchar/varbinary 类型，其他列类型报错。
示例如下：
```java
Map append(String tableName, Object rowkey, String[] columns, Object[] values,boolean withResult);
Map 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 res = client.append("test_append", "test_normal", new String[] { "c2", "c3" }, new Object[] { new byte[] { 2 }, "Y" }, true);
```
参数说明：
- tableName：表名
- rowkey：主键值
- columns：增加串的目标列名（一列或多列）
- values：目标列增加串值 （一列或多列）
- withResult：判断是否返回增加串结果集
- Map：返回值，如果 withResult = false ，返回结果为 Map.empty。
### scan 接口
您可使用该接口进行范围查找，支持根据主键或主键的前缀进行范围扫描，也可以不指定主键，根据索引或者索引前缀范围进行扫描查询，接口支持多 range 扫描和逆序扫描。
示例如下：
```java
// 样例
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 value = resultSet.getRow();
}
```
参数说明：
- table_name：待扫描的表名。
- primaryIndex：设定根据主键值扫描。
- column2：设定获取结果的列，例如一张表有 4 列，column1~column4，而只需要返回 column2 这一列的数据。
- addScanRange：添加查找范围，其中 min，max 为范围的左右区间值。
- batch_size：在满足扫描条件的行记录中，每一批需要返回的数量。
### batch 接口
您可使用该接口批量执行多种操作组合。
示例如下：
```java
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