Java SDKインターフェースの説明

obvec_jdbcは、OceanBaseのベクトルストレージシナリオおよびJSONテーブル仮想テーブルシナリオ向けに実装されたJava SDKです。本記事では、obvec_jdbcの使用方法について説明します。

インストール

obvec_jdbcは以下のいずれかの方法でインストールできます。

Maven依存関係の追加

プロジェクトのpom.xmlファイルにobvec_jdbcの依存関係を追加します。

<dependency>
  <groupId>com.oceanbase</groupId>
  <artifactId>obvec_jdbc</artifactId>
  <version>1.0.4</version>
</dependency>

ソースコードからのインストール

1. obvec_jdbcをインストールします。

   # obvec_jdbcリポジトリをクローン
   git clone https://github.com/oceanbase/obvec_jdbc.git
   # obvec_jdbcディレクトリに移動
   cd obvec_jdbc
   # obvec_jdbcをインストール
   mvn install
   

2. 依存関係を追加します。

   <dependency>
     <groupId>com.oceanbase</groupId>
     <artifactId>obvec_jdbc</artifactId>
     <version>1.0.4</version>
   </dependency>
   

APIの定義と使用

obvec_jdbcは、OceanBaseのベクトル検索機能およびJSONテーブル仮想テーブル機能を操作するためのObVecClientオブジェクトを提供します。

ベクトル検索機能の使用

クライアントの作成

以下のインターフェース定義を使用してObVecClientオブジェクトを構築します：

# uri：接続文字列。アドレス、ポート、接続するデータベース名などが含まれます。
# user：ユーザー名
# password：パスワード
public ObVecClient(String uri, String user, String password);

例：

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クラス

このクラスはテーブルの列スキーマを定義するために使用されます。コンストラクタは以下のとおりです：

# name：列名
# dataType：列のデータ型
public ObFieldSchema(String name, DataType dataType);

現在サポートされている列データ型は以下のとおりです：

インターフェースの定義は以下のとおりです：

IndexParams/IndexParam

IndexParamは単一のインデックスパラメータを設定するために使用されます。IndexParamsはベクトルインデックスパラメータのセットを設定するために使用され、特定のテーブルに複数のベクトルインデックスを作成する場合に使用します。

IndexParamのコンストラクタは以下のとおりです：

# vidx_name：インデックス名
# vector_field_name：ベクトル列名
public IndexParam(String vidx_name, String vector_field_name);

インターフェースの定義は以下のとおりです：

IndexParamsのコンストラクタは以下のとおりです：

public IndexParams();

インターフェースの定義は以下のとおりです：

ObCollectionSchemaクラス

テーブル作成時にはObCollectionSchemaオブジェクトの設定に依存するため、まずこのクラスのコンストラクタとインターフェースについて説明します。

ObCollectionSchemaのコンストラクタは以下のとおりです：

public ObCollectionSchema();

インターフェースの定義は以下のとおりです：

テーブルの削除

コンストラクタは以下のとおりです：

# table_name：対象テーブル名
public void dropCollection(String table_name);

テーブルの存在チェック

コンストラクタは以下のとおりです：

# table_name：対象テーブル名
public boolean hasCollection(String table_name);

テーブルの作成

コンストラクタは以下のとおりです：

# table_name：対象テーブル名
# collection：ObCollectionSchema型データ構造、テーブルのスキーマ
public void createCollection(String table_name, ObCollectionSchema collection);

ObFieldSchema、OCollectionSchema、およびIndexParamsを使用してテーブルを作成する例は以下のとおりです：

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;

# テーブルスキーマの定義
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);

ベクトルインデックスの追加作成

コンストラクタは以下のとおりです：

# table_name：対象テーブル名
# index_param：IndexParam型データ構造、テーブルのベクトルインデックスパラメータ
public void createIndex(String table_name, IndexParam index_param)

データの挿入

コンストラクタは以下のとおりです：

# 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型のデータをラップします。

例：

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);

データの削除

コンストラクタは以下のとおりです：

# table_name：ターゲットテーブル名
# primary_key_name：主キー列名
# primary_keys：ターゲット行の主キー列値配列
public void delete(String table_name, String primary_key_name, ArrayList<Sqlizable> primary_keys);

例：

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

ANNクエリ

コンストラクタは以下のとおりです：

# table_name：ターゲットテーブル名
# vec_col_name：ベクトル列名
# metric_type：ベクトル距離関数のタイプ。l2：l2距離関数に対応します。cosine：cosine距離関数に対応します。ip：negative_inner_product距離関数に対応します。
# qv：クエリ対象のベクトル値
# topk：最も類似した上位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);

例：

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テーブル機能の使用

obvec_jdbc の JSONテーブル機能は、OceanBase の JSON データ型に対する操作処理能力（JSON_VALUE/JSON_TABLE/JSON_REPLACE などを含む）に依存しており、仮想テーブルメカニズムを実装しています。複数のユーザー（ユーザーIDで区別）が同一の物理テーブル上で仮想テーブルに対するDDLまたはDML操作を実行できると同時に、ユーザー間のデータ分離を保証します。管理者ユーザーはDDL操作を、一般ユーザーはDML操作を実行できます。

この設計は、リレーショナルデータベースの構造的な管理能力とJSONの柔軟性を組み合わせており、OceanBaseデータベースのマルチモーダル統合能力を体現しています。ユーザーはSQLの強力な機能と使いやすさを享受しつつ、半構造化データも処理できるため、現代のアプリケーションが求める多様なデータモデルに対応できます。操作対象は依然として「テーブル」ですが、基盤となるストレージではより柔軟なJSON形式でデータを格納できるため、複雑で多様なアプリケーションシナリオをより効果的にサポートできます。

原理の説明

ここでは、原理図を用いてJSONテーブルの仕組みを説明します。

具体的な説明は以下の通りです：

1. ユーザー操作：ユーザーは引き続き、慣れ親しんだ標準SQL文（例えば CREATE TABLE でテーブル構造を作成、INSERT でデータを挿入、SELECT でデータをクエリする）を使用してシステムとやり取りします。データが下層でどのように保存されているかを気にする必要はなく、通常のリレーショナルデータベースのテーブルを操作するのと同じです。ユーザーがSQL文で作成するテーブルは論理テーブルであり、OceanBaseデータベース内部では meta_json_t と data_json_t の2つの物理テーブルに対応します。

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テーブルのメタデータ情報、すなわちユーザーが CREATE TABLE で定義した論理テーブル構造を保存します。それは各論理テーブルの列情報を記録しており、テーブル構造は以下の通りです：

ユーザーが CREATE TABLE を実行すると、JSON Table SDKはこれらの列定義情報を解析し、meta_json_t テーブルに挿入します。

data_json_t テーブルは、JSONテーブルの実際のデータ、すなわちユーザーが INSERT で挿入したデータを保存します。それは各論理テーブルの行データを記録しており、テーブル構造は以下の通りです：

使用例

1. クライアントの作成

   コンストラクタは以下のとおりです：

   # uri：接続文字列。アドレス、ポート、接続するデータベース名などを含みます。
   # user：ユーザー名
   # password：パスワード
   # user_id：ユーザーID
   # log_level：ログレベル
   public ObVecJsonClient(String uri, String user, String password, String user_id, Level log_level);
   

   例：

   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ステートメントを渡すことで使用できます。

   • テーブルの作成

     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

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

   • ALTER TABLE ADD COLUMN

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

   • ALTER TABLE MODIFY COLUMN

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

   • ALTER TABLE DROP COLUMN

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

   • ALTER TABLE RENAME

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