插入Doc_向量检索服务(VRS)-阿里云帮助中心

本文介绍如何通过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。

插入Doc

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)
  // 设置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();

    List<Doc> docs = new ArrayList<>();
    docs.add(Doc.builder().id("0")
            .vector("title", (Vector.builder().value(Collections.nCopies(4, 0.1f))).build())
            .vector("content", (Vector.builder().value(Collections.nCopies(6, 0.1f))).build())
            .build());
    // 允许部分向量字段缺失
    docs.add(Doc.builder().id("1")
            .vector("title", (Vector.builder().value(Collections.nCopies(4, 0.2f))).build())
            .build());
    docs.add(Doc.builder().id("2")
            .vector("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();

}

入参描述

可通过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 or Float。
1. 当Key在创建Collection时预先定义过，则Value的类型必须为预定义时的类型
2. 当Key未在创建Collection时预先定义过，则Value的类型可为String, Integer, Boolean or Float
是否预先定义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的结果
getUsage()	RequestUsage	对Serverless实例（按量付费）集合的Doc插入请求，成功后返回实际消耗的写请求单元数
isSuccess()	Boolean	判断请求是否成功	true