Java SDK を使用したコレクションへのドキュメント挿入 - DashVector

Java SDK を使用して、1 つ以上のドキュメントを DashVector コレクションに挿入します。ドキュメントは、ID、密ベクトル、およびオプションのフィールドまたは疎ベクトルで構成されます。

ドキュメント ID がコレクションにすでに存在する場合、挿入操作はそのドキュメントを上書きせずにスキップします。

事前準備

API 定義

DashVectorCollection クラスは、同期と非同期の両方の挿入メソッドを提供します：

Java

// 同期挿入
public Response<Void> insert(InsertDocRequest insertDocRequest);

// 非同期挿入
public ListenableFuture<Response<Void>> insertAsync(InsertDocRequest insertDocRequest);

例

すべての例では、quickstart という名前の 4 次元のベクターを持つコレクションを使用します。

説明

YOUR_API_KEY をご自身の API キーに、YOUR_CLUSTER_ENDPOINT をご自身のクラスターエンドポイントに置き換えてください。
これらの例を実行する前に、quickstart コレクションを作成してください。詳細については、「コレクションの作成」の「例」セクションをご参照ください。

単一ドキュメントの挿入

Java

import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorCollection;
import com.aliyun.dashvector.common.DashVectorException;
import com.aliyun.dashvector.models.Doc;
import com.aliyun.dashvector.models.Vector;
import com.aliyun.dashvector.models.requests.InsertDocRequest;
import com.aliyun.dashvector.models.responses.Response;

import java.util.*;

public class Main {
    public static void main(String[] args) throws DashVectorException {
        DashVectorClient client = new DashVectorClient("YOUR_API_KEY", "YOUR_CLUSTER_ENDPOINT");
        DashVectorCollection collection = client.get("quickstart");

        // 4 次元のベクターを構築
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

        // ID "1" のドキュメントを構築
        Doc doc = Doc.builder().id("1").vector(vector).build();

        // ドキュメントを挿入
        Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

        // 結果を検証
        if (response.isSuccess()) {
            System.out.println("Document inserted successfully.");
        } else {
            System.out.println("Insert failed: " + response.getCMessage());
        }
    }
}

フィールドを持つドキュメントの挿入

事前定義されたフィールド、またはスキーマフリーのフィールドをキーと値のペアとして追加します。

Java

// 4 次元のベクターを構築
Vector vector = Vector.builder().value(Arrays.asList(0.2f, 0.2f, 0.3f, 0.4f)).build();

// 事前定義フィールドとスキーマフリーフィールドを持つドキュメントを構築
Doc doc = Doc.builder()
    .id("2")
    .vector(vector)
    // 事前定義フィールド (型はコレクションスキーマと一致する必要があります)
    .field("name", "zhangshan")
    .field("age", 20)
    .field("weight", 100f)
    .field("id", 1234567890l)
    // スキーマフリーフィールド (String、Integer、Boolean、または Float)
    .field("anykey1", "String")
    .field("anykey2", 1)
    .field("anykey3", true)
    .field("anykey4", 3.1415926f)
    .build();

// ドキュメントを挿入
Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

if (response.isSuccess()) {
    System.out.println("Document inserted successfully.");
} else {
    System.out.println("Insert failed: " + response.getCMessage());
}

複数ドキュメントのバッチ挿入

Doc オブジェクトのリストを渡して、単一のリクエストで挿入します。

Java

// ID "3" から "12" までの 10 個のドキュメントを構築
List<Doc> docs = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    docs.add(
        Doc.builder()
            .id(Integer.toString(i + 3))
            .vector(Vector.builder().value(Collections.nCopies(4, (float) i + 3)).build())
            .build()
    );
}

InsertDocRequest request = InsertDocRequest.builder().docs(docs).build();
Response<Void> response = collection.insert(request);

if (response.isSuccess()) {
    System.out.println("Batch insert succeeded.");
} else {
    System.out.println("Batch insert failed: " + response.getCMessage());
}

ドキュメントの非同期挿入

insertAsync は ListenableFuture を返すため、呼び出し元のスレッドはブロックされません。future.get() を呼び出して結果を待ちます。

Java

import com.google.common.util.concurrent.ListenableFuture;

// ID "13" から "22" までの 10 個のドキュメントを構築
List<Doc> docs = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    docs.add(
        Doc.builder()
            .id(Integer.toString(i + 13))
            .vector(Vector.builder().value(Collections.nCopies(4, (float) i + 13)).build())
            .build()
    );
}

InsertDocRequest request = InsertDocRequest.builder().docs(docs).build();
ListenableFuture<Response<Void>> future = collection.insertAsync(request);

// 非同期操作が完了するまでブロック
Response<Void> response = future.get();

if (response.isSuccess()) {
    System.out.println("Async insert succeeded.");
} else {
    System.out.println("Async insert failed: " + response.getCMessage());
}

疎ベクトルを持つドキュメントの挿入

密ベクトルとともに、疎ベクトルを Map<Integer, Float> として提供します。各エントリは、ディメンションのインデックスをゼロ以外の値にマッピングします。

Java

Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// 疎ベクトルを構築
Map<Integer, Float> sparseVector = new HashMap<>();
sparseVector.put(1, 0.4f);
sparseVector.put(10000, 0.6f);
sparseVector.put(222222, 0.8f);

// 密ベクトルと疎ベクトルの両方を持つドキュメントを構築
Doc doc = Doc.builder()
    .id("28")
    .vector(vector)
    .sparseVector(sparseVector)
    .build();

// ドキュメントを挿入
Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

if (response.isSuccess()) {
    System.out.println("Document with sparse vector inserted.");
} else {
    System.out.println("Insert failed: " + response.getCMessage());
}

リクエストパラメーター

InsertDocRequest ビルダー

InsertDocRequest.builder() を使用して InsertDocRequest オブジェクトを構築します：

メソッド	必須	デフォルト	説明
`docs(List<Doc> docs)`	はい	-	挿入するドキュメントのリストを設定します。
`doc(Doc doc)`	いいえ	-	リストに単一のドキュメントを追加します。複数回呼び出すことで、さらに追加できます。
`partition(String partition)`	いいえ	default	ターゲットパーティションを指定します。
`build()`	-	-	`InsertDocRequest` オブジェクトを構築します。

Doc ビルダー

Doc.builder() を使用して Doc オブジェクトを構築します：

メソッド	必須	デフォルト	説明
`id(String id)`	はい	-	プライマリキーを設定します。
`vector(Vector vector)`	はい	-	密ベクトルを設定します。
`sparseVector(Map<Integer, Float>)`	いいえ	-	疎ベクトルを設定します。
`fields(Map<String, Object>)`	いいえ	-	すべてのフィールドを一度に設定します。
`field(String key, Object value)`	いいえ	-	単一のフィールドを追加します。複数回呼び出すことで、さらに追加できます。
`build()`	-	-	`Doc` オブジェクトを構築します。

フィールド型のルール：

キーは String である必要があります。
値は String、Integer、Boolean、または Float にすることができます。
フィールドキーがコレクション作成時に事前定義されている場合、値は事前定義された型と一致する必要があります。
キーが事前定義されていない場合、それはスキーマフリーフィールドとして扱われます。

Doc データ構造の詳細については、「データ型定義」をご参照ください。

レスポンスパラメーター

insert と insertAsync はどちらも Response<Void> オブジェクトを返します：

メソッド	戻り値の型	説明	例
`getCode()`	int	ステータスコード。詳細については、「ステータスコード」をご参照ください。	0
`getCMessage()`	String	ステータスメッセージ。	success
`getRequestId()`	String	一意のリクエスト ID。	19215409-ea66-4db9-8764-26ce2eb5bb99
`isSuccess()`	Boolean	操作が成功したかどうか。	true