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

本文介绍如何通过Java SDK向Collection中插入或更新Doc。

说明

若调用本接口时Doc Id已存在，则等同于更新Doc；Doc Id不存在，则等同于插入Doc。
若调用本接口时不指定Doc Id，则等同于插入Doc，DashVector会自动生成Doc Id，并在返回结果中携带id信息。

前提条件

已创建Cluster：创建Cluster。
已获得API-KEY：API-KEY管理。
已安装最新版SDK：安装DashVector SDK。

接口定义

Java

// class DashVectorCollection

// 同步接口
public Response<List<DocOpResult>> upsert(UpsertDocRequest upsertDocRequest);

// 异步接口
public ListenableFuture<Response<List<DocOpResult>>> upsertAsync(UpsertDocRequest upsertDocRequest);

使用示例

说明

需要使用您的api-key替换示例中的YOUR_API_KEY、您的Cluster Endpoint替换示例中的YOUR_CLUSTER_ENDPOINT，代码才能正常运行。
本示例需要参考新建Collection-使用示例提前创建好名称为quickstart的Collection。

插入或更新Doc

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.UpsertDocRequest;
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");
        // 构建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.upsert(UpsertDocRequest.builder().doc(doc).build());
        
        // 判断插入或更新Doc是否成功
      	// 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.upsert(UpsertDocRequest.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.upsert(UpsertDocRequest.builder().doc(doc).build());

// 判断插入或更新Doc是否成功
assert response.isSuccess()

批量插入或更新Doc

Java

// 通过UpsertDocRequest对象，批量插入或更新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()
  );
}

UpsertDocRequest request = UpsertDocRequest.builder().docs(docs).build();
Response<List<DocOpResult>> response = collection.upsert(request);

// 判断插入或更新Doc是否成功
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()
  );
}

UpsertDocRequest request = UpsertDocRequest.builder().docs(docs).build();
ListenableFuture<Response<List<DocOpResult>>> response = collection.upsertAsync(request);

// 等待并获取异步upsert结果
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.upsert(UpsertDocRequest.builder().doc(doc).build());

入参描述

使用UpsertDocRequestBuilder构造UpsertDocRequest对象，其可用方法如下：

方法	必填	默认值	描述
docs(List<Doc> docs)	是	-	设置Doc列表
doc(Doc doc)	是	-	追加Doc至Doc列表，可多次调用
partition(String partition)	否	default	分区名称
build()	-	-	构造`UpsertDocRequest`对象

使用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