---
title: "Java SDK 接口说明 - OceanBase 数据库 V4.3.5 | OceanBase 文档中心"
description: Java SDK 接口说明 obvec_jdbc 是一个专为 OceanBase 向量存储场景和 JSON Table 虚拟表场景实现的 Java SDK。本文介绍了 obvec_jdbc 的使用方法。 安装 可选择下述任一方式安装 obvec_jdbc。 maven 依赖 在你项目的 pom.xml 文件中添加 o…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.5 LTS

# Java SDK 接口说明

更新时间：2026-04-07 20:57:20

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.5/zh-CN/640.ob-vector-search/700.ob-vector-search-reference/900.ob-vector-search-supported-clients-and-languages/300.ob-vector-search-java-sdk.md)  

obvec_jdbc 是一个专为 OceanBase 向量存储场景和 JSON Table 虚拟表场景实现的 Java SDK。本文介绍了 obvec_jdbc 的使用方法。

## 安装

可选择下述任一方式安装 obvec_jdbc。

### maven 依赖

在你项目的 `pom.xml` 文件中添加 obvec_jdbc 的依赖。

```xml
<dependency>
  <groupId>com.oceanbase</groupId>
  <artifactId>obvec_jdbc</artifactId>
  <version>1.0.6</version>
</dependency>

```

### 源码安装

1. 安装 obvec_jdbc。

   ```bash
   # 克隆 obvec_jdbc 仓库
   git clone https://github.com/oceanbase/obvec_jdbc.git
   # 进入 obvec_jdbc 目录
   cd obvec_jdbc
   # 安装 obvec_jdbc
   mvn install

   ```
 2. 添加依赖

   ```

## API 接口定义与使用

obvec_jdbc 提供了 `ObVecClient` 对象来操作 OceanBase 向量搜索功能和 JSON Table 虚拟表功能。

### 使用向量搜索功能

#### 创建一个客户端

使用以下接口定义构造 ObVecClient 对象：

```java
# uri：连接串，包含地址和端口以及连接的数据库名等
# user：用户名
# password：密码
public ObVecClient(String uri, String user, String password);

```

示例如下：

```java
import com.oceanbase.obvec_jdbc.ObVecClient;

String uri = "jdbc:oceanbase://127.0.0.1:2881/test";
String user = "root@test";
String password = "";
String tb_name = "JAVA_TEST";

ObVecClient ob = new ObVecClient(uri, user, password);

```

#### ObFieledSchema 类

该类用于定义表的列 Schema，构造函数如下：

```java
# name：列名
# dataType：列类型
public ObFieldSchema(String name, DataType dataType);

```

列类型目前支持的数据类型如下：

| DataType | 描述 |
| --- | --- |
| BOOL | 等价于 TINYINT |
| INT8 | 等价于 TINYINT |
| INT16 | 等价于 SMALLINT |
| INT32 | 等价于 INT |
| INT64 | 等价于 BIGINT |
| FLOAT | 等价于 FLOAT |
| DOUBLE | 等价于 DOUBLE |
| STRING | 等价于 LONGTEXT |
| VARCHAR | 等价于 VARCHAR |
| JSON | 等价于 JSON |
| FLOAT_VECTOR | 等价于 VECTOR |

#### 说明

对于更复杂的类型、约束等，可自行使用 OceanBase JDBC 的接口进行创建，而不使用 obvec_jdbc。

接口定义如下：

| API 接口 | 描述 |
| --- | --- |
| String getName() | 获取列名。 |
| ObFieldSchema Name(String name) | 设置列名，返回对象本身方便链式操作。 |
| ObFieldSchema DataType(DataType dataType) | 设置数据类型。 |
| boolean getIsPrimary() | 是否是主键列。 |
| ObFieldSchema IsPrimary(boolean isPrimary) | 设置是否是主键。 |
| ObFieldSchema IsAutoInc(boolean isAutoInc) | 设置是否自增。   #### 注意    IsAutoInc 需要在 IsPrimary 为真的情况才生效。 |
| ObFieldSchema IsNullable(boolean isNullable) | 设置是否可以为 NULL。   #### 注意    IsNullable 默认是假，与 MySQL 行为不同。 |
| ObFieldSchema MaxLength(int maxLength) | 对于 VARCHAR 类型设置最大长度。 |
| ObFieldSchema Dim(int dim) | 对于 VECTOR 类型设置维度。 |

#### IndexParams/IndexParam

IndexParam 用于设置单个索引参数。IndexParams 用于设置一组向量索引参数，在某张表上创建多个向量索引时使用。

#### 注意

obvec_jdbc 仅支持创建向量索引，需要创建其他索引需使用 OceanBase JDBC。

IndexParam 的构造函数如下：

```java
# vidx_name：索引名
# vector_field_name：向量列名
public IndexParam(String vidx_name, String vector_field_name);

```

接口定义如下：

| API 接口 | 描述 |
| --- | --- |
| IndexParam M(int m) | 获取 HNSW 算法中每个向量的最大邻居数。 |
| IndexParam EfConstruction(int ef_construction) | 设置 HNSW 算法构造时搜索的最大候选向量数。 |
| IndexParam EfSearch(int ef_search) | 设置 HNSW 算法中搜索时的最大候选向量数。 |
| IndexParam Lib(String lib) | 设置使用的向量库类型。 |
| IndexParam MetricType(String metric_type) | 设置向量距离函数类型。 |

IndexParams 的构造函数如下：

```
public IndexParams();

```

接口定义如下：

| API 接口 | 描述 |
| --- | --- |
| void addIndex(IndexParam index_param) | 加入一个索引定义。 |

#### ObCollectionSchema 类

在创建表时需要依赖于 ObCollectionSchema 对象的设置，所以首先介绍该类的构造方法和接口。

ObCollectionSchema 的构造函数如下：

```java
public ObCollectionSchema();

```

接口定义如下：

| API 接口 | 描述 |
| --- | --- |
| void addField(ObFieldSchema field) | 添加一个列定义。 |
| void setIndexParams(IndexParams index_params) | 设置表的向量索引参数。 |

#### 删除表

构造函数如下：

```java
# table_name：目标表名
public void dropCollection(String table_name);

```

#### 检查表是否存在

构造函数如下：

```java
# table_name：目标表名
public boolean hasCollection(String table_name);

```

#### 创建表

构造函数如下：

```java
# table_name：目标表名
# collection：ObCollectionSchema 类型数据结构，表的 Schema
public void createCollection(String table_name, ObCollectionSchema collection);

```

借助 ObFieldSchema、OCollectionSchema 以及 IndexParams 创建表的示例如下：

```java
import com.oceanbase.obvec_jdbc.DataType;
import com.oceanbase.obvec_jdbc.ObCollectionSchema;
import com.oceanbase.obvec_jdbc.ObFieldSchema;
import com.oceanbase.obvec_jdbc.IndexParam;
import com.oceanbase.obvec_jdbc.IndexParams;

# 定义表schema
ObCollectionSchema collectionSchema = new ObCollectionSchema();
ObFieldSchema c1_field = new ObFieldSchema("c1", DataType.INT32);
c1_field.IsPrimary(true).IsAutoInc(true);
ObFieldSchema c2_field = new ObFieldSchema("c2", DataType.FLOAT_VECTOR);
c2_field.Dim(3).IsNullable(false);
ObFieldSchema c3_field = new ObFieldSchema("c3", DataType.JSON);
c3_field.IsNullable(true);
collectionSchema.addField(c1_field);
collectionSchema.addField(c2_field);
collectionSchema.addField(c3_field);

# 定义索引
IndexParams index_params = new IndexParams();
IndexParam index_param = new IndexParam("vidx1", "c2");
index_params.addIndex(index_param);
collectionSchema.setIndexParams(index_params);

ob.createCollection(tb_name, collectionSchema);

```

#### 后建向量索引

构造函数如下：

```java
# table_name：目标表名
# index_param：IndexParam 类型数据结构，表的向量索引参数
public void createIndex(String table_name, IndexParam index_param)

```

#### 插入数据

构造函数如下：

```java
# table_name：目标表名
# column_names：目标表的列名数组
# rows：数据行。ArrayList<Sqlizable[]>，每行数据是一个 Sqlizable 数组。Sqlizable 是一个用于将 Java 数据类型转换为 SQL 数据类型的包装类
public void insert(String table_name, String[] column_names, ArrayList<Sqlizable[]> rows);

```

rows 支持的数据类型包括：

- SqlInteger：包装 Int 类型的数据。
 - SqlFloat：包装 Float 类型数据。
 - SqlDouble：包装 Double 类型数据。
 - SqlText：包装 String 类型数据。
 - SqlVector：包装 Vector 类型数据。

示例如下：

```java
import com.oceanbase.obvec_jdbc.SqlInteger;
import com.oceanbase.obvec_jdbc.SqlText;
import com.oceanbase.obvec_jdbc.SqlVector;
import com.oceanbase.obvec_jdbc.Sqlizable;

ArrayList<Sqlizable[]> insert_rows = new ArrayList<>();
Sqlizable[] ir1 = { new SqlVector(new float[] {1.0f, 2.0f, 3.0f}), new SqlText("{\"doc\": \"oceanbase doc 1\"}") };
insert_rows.add(ir1);
Sqlizable[] ir2 = { new SqlVector(new float[] {1.1f, 2.2f, 3.3f}), new SqlText("{\"doc\": \"oceanbase doc 2\"}") };
insert_rows.add(ir2);
Sqlizable[] ir3 = { new SqlVector(new float[] {0f, 0f, 0f}), new SqlText("{\"doc\": \"oceanbase doc 3\"}") };
insert_rows.add(ir3);
ob.insert(tb_name, new String[] {"c2", "c3"}, insert_rows);

```

#### 删除数据

构造函数如下：

```java
# table_name：目标表名
# primary_key_name：主键列名
# primary_keys：目标行的主键列值数组
public void delete(String table_name, String primary_key_name, ArrayList<Sqlizable> primary_keys);

```

示例如下：

```java
ArrayList<Sqlizable> ids = new ArrayList<>();
ids.add(new SqlInteger(2));
ids.add(new SqlInteger(1));
ob.delete(tb_name, "c1", ids);

```

#### ANN 查询

构造函数如下：

```java
# table_name：目标表名
# vec_col_name：向量列名
# metric_type：向量距离函数类型。l2：对应 l2 距离函数；cosine：对应 cosine 距离函数；ip：对应 negative_inner_product 距离函数
# qv：待查询的向量值
# topk：返回 top k 个最相似的结果
# output_fields：投影列，即返回的字段数组
# output_datatypes：投影列的数据类型，即返回的字段数据类型，用于直接转换为 Java 数据类型
# where_expr：WHERE 条件表达式
public ArrayList<HashMap<String, Sqlizable>> query(
      String table_name,
      String vec_col_name,
      String metric_type,
      float[] qv,
      int topk,
      String[] output_fields,
      DataType[] output_datatypes,
      String where_expr);

```

示例如下：

```java
ArrayList<HashMap<String, Sqlizable>> res = ob.query(tb_name, "c2", "l2",
            new float[] {0f, 0f, 0f}, 10,
            new String[] {"c1", "c3", "c2"},
            new DataType[] {
            DataType.INT32,
            DataType.JSON,
            DataType.FLOAT_VECTOR,
            "c1 > 0"});
if (res != null) {
    for (int i = 0; i < res.size(); i++) {
        for (HashMap.Entry<String, Sqlizable> entry : res.get(i).entrySet()) {
            System.out.printf("%s : %s, ", entry.getKey(), entry.getValue().toString());
        }
        System.out.print("\n");
    }
} else {
    System.out.println("res is null");
}

```

### 使用 JSON Table 功能

obvec_jdbc 的 JSON Table 功能依赖于 OceanBase 对 JSON 数据类型的操作处理能力（包括 `JSON_VALUE`/`JSON_TABLE`/`JSON_REPLACE` 等）实现了一套虚拟表机制，多个用户（以用户 id 做区分）可以在同一张物理表上实现对虚拟表的 DDL 或者 DML 操作的同时保证用户之间的数据隔离。管理员用户可以操作 DDL，普通用户可以操作 DML。

这种设计结合了关系型数据库的结构化管理能力和 JSON 的灵活性，体现了 OceanBase 数据库的多模一体化能力。用户既能享受到 SQL 的强大功能和易用性，又能处理半结构化数据，适应了现代应用对数据模型多样性的需求。操作的仍然是“表”，但底层却能以更灵活的 JSON 格式存储数据，从而更好地支持复杂多变的应用场景。

#### 原理说明

这里以一张原理图说明 JSON Table 的原理。

![JSON Table 原理](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer/V4.3.5/vector_search/JSON-Table%E5%8E%9F%E7%90%86%E5%9B%BE.png)

具体说明如下：

1. 用户操作：用户仍然使用熟悉的标准 SQL 语句（例如 `CREATE TABLE` 创建表结构，`INSERT` 插入数据，`SELECT` 查询数据）来与系统交互，无需关心数据在底层是如何存储的，就像操作普通的关系型数据库表一样。用户通过 SQL 语句创建的表是一个逻辑表，在 OceanBase 数据库内部会对应两个物理表 `meta_json_t` 和 `data_json_t`。
 2. JSON Table SDK：在应用程序内部，有一个 JSON Table SDK（软件开发工具包）。这个 SDK 是连接用户的 SQL 操作和 OceanBase 数据库实际存储的关键。当执行 SQL 语句时，SDK 会拦截这些请求，并智能地将其转换为对 OceanBase 数据库内部表 `meta_json_t` 和 `data_json_t` 的读写操作。
 3. OceanBase 数据库内部：

      - `meta_json_t` (存储表结构)：用于存储用户创建的逻辑表的元数据，也就是表的结构信息（例如，创建的表有哪些列，每个列的数据类型是什么）。当执行 `CREATE TABLE` 时，SDK 会将这些结构信息记录到 `meta_json_t` 中。
      - `data_json_t` (将行数据存储为 JSON 类型)：用于存储实际插入的数据。与传统关系型数据库直接存储行数据不同，JSON Table 功能会将插入的每一行数据封装成一个 JSON 对象，然后存储在 `data_json_t` 表的某个列中。这样，即使数据结构比较灵活，也能高效存储。
 4. 数据查询：当执行 `SELECT` 等查询操作时，SDK 会从 `data_json_t` 中读取 JSON 格式的数据，并结合 `meta_json_t` 中的表结构信息，将这些 JSON 数据重新解析并呈现为你熟悉的表格形式，返回给你的应用程序。

`meta_json_t` 表存储了 JSON Table 的元数据信息，即用户通过 `CREATE TABLE` 定义的逻辑表结构。它记录了每个逻辑表的列信息，表结构如下：

| 字段名 | 说明 | 示例 |
| --- | --- | --- |
| `user_id` | 用户 ID，用于区分不同用户的逻辑表。 | `0`, `1`, `2` |
| `jtable_name` | 逻辑表的名称。 | `test_count` |
| `jcol_id` | 逻辑表中的列 ID。 | `1`, `2`, `3` |
| `jcol_name` | 逻辑表中的列名。 | `c1`, `c2`, `c3` |
| `jcol_type` | 列的数据类型。 | `INT`, `VARCHAR(124)`, `DECIMAL(10,2)` |
| `jcol_nullable` | 列是否可为空。 | `0`, `1` |
| `jcol_has_default` | 列是否有默认值。 | `0`, `1` |
| `jcol_default` | 列的默认值。 | `{'default': null}` |

当用户执行 `CREATE TABLE` 时，JSON Table SDK 会将这些列定义信息解析并插入到 `meta_json_t` 表中。

`data_json_t` 表存储了 JSON Table 的实际数据，即用户通过 `INSERT` 插入的数据。它记录了每个逻辑表的行数据，表结构如下：

| 字段名 | 说明 | 示例 |
| --- | --- | --- |
| `user_id` | 用户 ID，用于区分不同用户的逻辑表。 | `0`, `1`, `2` |
| `admin_id` | 管理员用户 ID。 | `0` |
| `jtable_name` | 逻辑表的名称，用于关联 `meta_json_t` 中的元数据。 | `test_count` |
| `jdata_id` | 数据 ID，JSON 数据的唯一标识符，对应逻辑表中的每一行。 | `1`, `2`, `3` |
| `jdata` | 这是一个 JSON 类型的列，用于存储逻辑表中的实际行数据。 | `{"c1": 1, "c2": "test", "c3": 1.23}` |

#### 使用示例

1. 创建一个客户端

   构造函数如下：

   ```java
   # uri：连接串，包含地址和端口以及连接的数据库名等
   # user：用户名
   # password：密码
   # user_id：用户 id
   # log_level：日志级别
   public ObVecJsonClient(String uri, String user, String password, String user_id, Level log_level);

   ```

   示例如下：

   ```java
   import com.oceanbase.obvec_jdbc.ObVecJsonClient;

   String uri = "jdbc:oceanbase://127.0.0.1:2881/test";
   String user = "root@test";
   String password = "";
   ObVecJsonClient client = new ObVecJsonClient(uri, user, password, 0, Level.INFO);

   ```
 2. 执行 DDL 语句

   直接调用 `parseJsonTableSQL2NormalSQL` 接口传入具体的 SQL 语句即可使用。

      - 创建表

       ```java
       String sql = "CREATE TABLE `t2` (c1 INT NOT NULL DEFAULT 10, c2 VARCHAR(30) DEFAULT 'ca', c3 VARCHAR NOT NULL, c4 DECIMAL(10, 2), c5 TIMESTAMP DEFAULT CURRENT_TIMESTAMP);";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```
      - ALTER TABLE CHANGE COLUMN

       ```java
       sql = "ALTER TABLE t2 CHANGE COLUMN c2 changed_col INT";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```
      - ALTER TABLE ADD COLUMN

       ```java
       sql = "ALTER TABLE t2 ADD COLUMN email VARCHAR(100) default 'example@example.com'";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```
      - ALTER TABLE MODIFY COLUMN

       ```java
       sql = "ALTER TABLE t2 MODIFY COLUMN changed_col TIMESTAMP NOT NULL DEFAULT current_timestamp";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```
      - ALTER TABLE DROP COLUMN

       ```java
       sql = "ALTER TABLE t2 DROP c1";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```
      - ALTER TABLE RENAME

       ```java
       sql = "ALTER TABLE t2 RENAME TO alter_test";
       client.parseJsonTableSQL2NormalSQL(sql);

       ```

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线