Upsert documents - DashVector - Alibaba Cloud Documentation Center

This topic describes how to upsert documents into a collection by using the SDK for Java.

Note

If the ID of a target document already exists, the operation of updating a document is performed. Otherwise, the operation of inserting a document is performed.

Prerequisites

A cluster is created. For more information, see Create a cluster.
An API key is obtained. For more information, see Manage API keys.
The SDK of the latest version is installed. For more information, see Install DashVector SDK.

API definition

Java

// The DashVectorCollection class.

// The method working in synchronous mode.
public Response<Void> upsert(UpsertDocRequest upsertDocRequest);

// The method working in asynchronous mode.
public ListenableFuture<Response<Void>> upsertAsync(UpsertDocRequest upsertDocRequest);

Example

Note

You need to replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster in the sample code for the code to run properly.

You need to create a collection named quickstart in advance. For more information, see the "Example" section of the Create a collection topic.

Upsert a document

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");
        // Build a vector.
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
        
        // Build a document.
      	Doc doc = Doc.builder().id("1").vector(vector).build();
        
        // Upsert the document.
        Response<Void> response = collection.upsert(UpsertDocRequest.builder().doc(doc).build());
        
        // Check whether the operation is successful.
      	assert response.isSuccess() 
    }
}

Upsert a document with fields

Java

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

// Upsert a document and specify the values of related fields.
Doc doc = Doc.builder()
  .id("2")
  .vector(vector)
  // Specify the values of fields that are predefined during collection creation.
  .field("name", "zhangshan")
  .field("age", 20)
  .field("weight", 100f)
  // Specify schema-free fields and values.
  .field("anykey1", "String")
  .field("anykey2", 1)
  .field("anykey3", true)
  .field("anykey4", 3.1415926f)
  .build();

// Upsert the document.
Response<Void> response = collection.upsert(UpsertDocRequest.builder().doc(doc).build());

// Check whether the operation is successful.
assert response.isSuccess()

Upsert multiple documents at a time

Java

// Use UpsertDocRequest objects to upsert 10 documents at a time.
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<Void> response = collection.upsert(request);

// Check whether the operation is successful.
assert response.isSuccess();

Asynchronously upsert documents

Java

// Asynchronously upsert 10 documents at a time.
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<Void>> response = collection.upsertAsync(request);

// Wait for the result of the asynchronous upsert operation.
Response<Void> ret = response.get();

Upsert a document containing a sparse vector

Java

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

// Build a Doc object containing a sparse vector.
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();

// Upsert the document with the sparse vector.
Response<Void> response = collection.upsert(UpsertDocRequest.builder().doc(doc).build());

Request parameters

You can use an UpsertDocRequestBuilder instance to build an UpsertDocRequest object. The following table describes the methods that can be called by the instance.

Method	Required	Default value	Description
docs(List<Doc> docs)	Yes	-	Sets a list of documents.
doc(Doc doc)	Yes	-	Adds a document to the document list. This method can be called multiple times.
partition(String partition)	No	default	Sets the name of the partition.
build()	-	-	Builds an `UpsertDocRequest` object.

You can use a DocBuilder instance to build a Doc object. The following table describes the methods that can be called by the instance.

Method	Required	Default value	Description
id(String id)	Yes	-	Sets the primary key.
vector(Vector vector)	Yes	-	Sets the vector.
sparseVector(Map(Integer, Float))	No	-	Sets the sparse vector.
fields(Map<String, Object>)	No	-	Sets fields.
field(String key, Object value)	No	-	Adds a field to the fields parameter. This method can be called multiple times.
build()	-	-	Builds a `Doc` object.

Note

Each field in a Doc object can be set to a user-defined key-value pair. In a key-value pair, the key must be of the String type, and the value can be of the String, Integer, Boolean, or Float type.
1. If a key is predefined during collection creation, the value must be of the predefined type.
2. If the key is not predefined during collection creation, the value can be of the String, Integer, Boolean, or Float type.

For more information about predefining fields, see Schema-free.

Response parameters

Note

A Response<Void> object is returned, which contains the operation result, as described in the following table.

Method	Type	Description	Example
getCode()	int	The returned status code. For more information, see Status codes.	0
getMessage()	String	The returned message.	success
getRequestId()	String	The unique ID of the request.	19215409-ea66-4db9-8764-26ce2eb5bb99
isSuccess()	Boolean	Specifies whether the operation is successful.	true