插入Doc

本文介紹如何通過Java SDK向Collection中插入Doc。

說明

插入Doc時若指定id已存在，已存在的Doc不會被覆蓋，本次插入Doc操作無效。
插入Doc時若不指定id，則在插入過程中會自動產生id，並在返回結果中攜帶id資訊。

前提條件

已建立Cluster：建立Cluster。
已獲得API-KEY：API-KEY管理。
已安裝最新版SDK：安裝DashVector SDK。

介面定義

Java

// class DashVectorCollection

// 同步介面
public Response<List<DocOpResult>> insert(InsertDocRequest insertDocRequest);

// 非同步介面
public ListenableFuture<Response<List<DocOpResult>>> insertAsync(InsertDocRequest insertDocRequest);

使用樣本

說明

需要使用您的api-key替換樣本中的YOUR_API_KEY、您的Cluster Endpoint替換樣本中的YOUR_CLUSTER_ENDPOINT，代碼才能正常運行。
本樣本需要參考建立Collection提前建立好名稱為quickstart的Collection。

Java

import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorClientConfig;
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 com.google.common.util.concurrent.ListenableFuture;

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");
        // 構建Vector
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
        
        // 構建Doc
      	Doc doc = Doc.builder().id("1").vector(vector).build();
        
        // 插入Doc
        Response<List<DocOpResult>> response = collection.insert(InsertDocRequest.builder().doc(doc).build());
        
        // 判斷插入是否成功
      	// assert response.isSuccess() 
    }
}

插入不帶有Id的Doc

Java

// 構建Vector
Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
        
// 構建Doc
Doc doc = Doc.builder().vector(vector).build();
        
// 插入Doc
Response<List<DocOpResult>> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

插入帶有Fields的Doc

Java

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

// 插入單條資料，並設定Fields Value
Doc doc = Doc.builder()
  .id("2")
  .vector(vector)
  // 設定建立Collection時預定義的Fields Value
  .field("name", "zhangshan")
  .field("age", 20)
  .field("weight", 100f)
  .field("id", 1234567890l)
  .field("tags", Arrays.asList("hello", "world"))
  .field("numbers", Arrays.asList(1, 2, 3))
  .field("grades", Arrays.asList(1.1f, 2.2f, 3.3f))
  .field("bankCards", Arrays.asList(1L, 2L, 3L))
  // 設定Schema-Free的Field & Value
  .field("anykey1", "String")
  .field("anykey2", 1)
  .field("anykey3", true)
  .field("anykey4", 3.1415926f)
  .build();

// 插入Doc
Response<List<DocOpResult>> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

// 判斷插入Doc是否成功
assert response.isSuccess()

批量插入Doc

Java

// 通過InsertDocRequest對象，批量插入10條Doc
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<List<DocOpResult>> response = collection.insert(request);

// 判斷插入是否成功
assert response.isSuccess();

非同步插入Doc

Java

// 非同步批量插入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<List<DocOpResult>>> response = collection.insertAsync(request);

// 等待並擷取非同步insert結果
Response<List<DocOpResult>> ret = response.get();

插入帶有Sparse Vector的Doc

Java

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

// 構建帶有Sparse Vector的Doc
Doc doc = Doc.builder()
  .id("28")
  .sparseVector(
  new Map<Integer, Float>() {
    {
      put(1, 0.4f);
      put(10000, 0.6f);
      put(222222, 0.8f);
    }
  })
  .vector(vector)
  .build();

// 插入帶有Sparse Vector的Doc
Response<List<DocOpResult>> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

插入多向量Doc

Java

public void insert() {
    collection = client.get(collectionName);
    assert collection.isSuccess();
    SparseVector abstruct_vector = SparseVector.builder()
            .value(0, 0.3)
            .value(1, 0.232)
            .value(2, 0.4482)
            .value(3, 0.6672)
            .build();

    List<Doc> docs = new ArrayList<>();
    docs.add(Doc.builder().id("0")
            .vectors("title", Vector.builder().value(Collections.nCopies(4, 0.1f)).build())
            .vectors("content", Vector.builder().value(Collections.nCopies(6, 0.1f)).build())
            .sparseVectors("abstruct", abstruct_vector)
            .build());
    // 允許部分向量欄位缺失
    docs.add(Doc.builder().id("1")
            .vectors("title", (Vector.builder().value(Collections.nCopies(4, 0.2f))).build())
            .build());
    docs.add(Doc.builder().id("2")
            .vectors("content", (Vector.builder().value(Collections.nCopies(6, 0.3f))).build())
            .build());
    InsertDocRequest insertRequest = InsertDocRequest.builder().docs(docs).build();
    Response<List<DocOpResult>> insertResponse = collection.insert(insertRequest);
    System.out.println(insertResponse);
    assert insertResponse.isSuccess();
}

說明

多向量Collection中，稠密向量+稀疏向量欄位總共不能超過4條

入參描述

可通過InsertDocRequestBuilder構造InsertDocRequest對象，其可用方法如下：

方法	必填	預設值	描述
docs(List<Doc> docs)	是	-	設定Doc列表
doc(Doc doc)	是	-	追加Doc至Doc列表，可多次調用
partition(String partition)	否	default	分區名稱
build()	-	-	構造`InsertDocRequest`對象

可通過DocBuilder構造Doc對象，其可用方法如下：

方法	必填	預設值	描述
id(String id)	否	-	主鍵
vector(Vector vector)	是	-	向量資料
sparseVector(Map(Integer, Float))	否	-	稀疏向量
fields(Map<String, Object>)	否	-	設定Fields
field(String key, Object value)	否	-	追加Field至Fields，可多次調用
build()	-	-	構造`Doc`對象

說明

Doc對象的fields參數，可自由設定“任意”的KeyValue資料，Key必須為String類型，Value必須為String, Integer, Boolean, Float, Long, List<String>, List<Integer>, List<Float> or List<Long>。
1. 當Key在建立Collection時預先定義過，則Value的類型必須為預定義時的類型
2. 當Key未在建立Collection時預先定義過，則Value的類型可為String, Integer, Boolean or Float or Long
是否預先定義Fields，可參考Schema Free。

出參描述

說明

返回結果為Response<List<DocOpResult>>對象，Response<List<DocOpResult>>對象中可擷取本次操作結果資訊，如下表所示。

方法	傳回型別	描述	樣本
getCode()	int	傳回值，參考返回狀態代碼說明	0
getMessage()	String	返回訊息	success
getRequestId()	String	請求唯一id	19215409-ea66-4db9-8764-26ce2eb5bb99
getOutput()	List<DocOpResult>	返回插入Doc的結果
isSuccess()	Boolean	判斷請求是否成功	true