Upsert documents to a collection with the Java SDK - DashVector

The upsert operation inserts a new document or overwrites an existing one based on the document ID:

ID does not exist: Inserts the document.
ID already exists: The update operation is performed.
No ID specified: DashVector auto-generates an ID and returns it in the response.

Prerequisites

A running DashVector cluster. See Create a cluster.
An API key. See Manage API keys.
The latest DashVector Java SDK. See Install DashVector SDK.

API reference

The DashVectorCollection class provides synchronous and asynchronous upsert methods:

Java

// Synchronous upsert
public Response<Void> upsert(UpsertDocRequest upsertDocRequest);

// Asynchronous upsert
public ListenableFuture<Response<Void>> upsertAsync(UpsertDocRequest upsertDocRequest);

Examples

The following examples use a 4-dimensional collection named quickstart. To create one, see Create a collection.

Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster.

Upsert a single 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 4-dimensional vector
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

        // Build a document with ID "1"
        Doc doc = Doc.builder().id("1").vector(vector).build();

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

        // Verify the operation succeeded
        assert response.isSuccess();
    }
}

Upsert a document with fields

Attach metadata fields to a document. Fields defined during collection creation must match their predefined types. Additional schema-free fields accept String, Integer, Boolean, or Float values.

Java

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

// Build a document with predefined and schema-free fields
Doc doc = Doc.builder()
    .id("2")
    .vector(vector)
    // Predefined fields (types must match the collection schema)
    .field("name", "zhangshan")
    .field("age", 20)
    .field("weight", 100f)
    // Schema-free fields (any supported type)
    .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());

// Verify the operation succeeded
assert response.isSuccess();

Upsert multiple documents in a batch

Java

// Build 10 documents with IDs "3" through "12"
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);

// Verify the operation succeeded
assert response.isSuccess();

Upsert documents asynchronously

Use upsertAsync for non-blocking writes. The method returns a ListenableFuture that resolves to the response.

Java

// Build 10 documents with IDs "13" through "22"
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>> future = collection.upsertAsync(request);

// Block until the asynchronous operation completes
Response<Void> response = future.get();

Upsert a document with a sparse vector

Java

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

// Build a document with both dense and sparse vectors
Doc doc = Doc.builder()
    .id("28")
    .vector(vector)
    .sparseVector(new HashMap<Integer, Float>() {{
        put(1, 0.4f);
        put(10000, 0.6f);
        put(222222, 0.8f);
    }})
    .build();

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

Request parameters

UpsertDocRequest builder

Build an UpsertDocRequest object using UpsertDocRequestBuilder:

Method	Required	Default	Description
`docs(List<Doc> docs)`	Yes	-	Sets the list of documents to upsert.
`doc(Doc doc)`	-	-	Adds a single document. Can be called multiple times.
`partition(String partition)`	No	`default`	Specifies the target partition.
`build()`	-	-	Builds the `UpsertDocRequest` object.

Doc builder

Build a Doc object using DocBuilder:

Method	Required	Default	Description
`id(String id)`	Yes	-	Sets the document 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)`	-	-	Adds a field. Can be called multiple times.
`build()`	-	-	Builds the `Doc` object.

Note

Each field in a Doc is a key-value pair. The key must be a String. The value can be a String, Integer, Boolean, or Float.

Predefined fields: The value type must match the type defined during collection creation.
Schema-free fields: The value can be any of the four supported types. For details about predefined fields, see Schema-free.

Response parameters

Note

All upsert methods return a Response<Void> object:

Method	Return type	Description	Example
`getCode()`	`int`	Status code. See Status codes.	`0`
`getMessage()`	`String`	Status message.	`"success"`
`getRequestId()`	`String`	Request ID for troubleshooting.	`"19215409-ea66-4db9-8764-26ce2eb5bb99"`
`isSuccess()`	`Boolean`	Whether the operation succeeded.	`true`

DashVector:insert or update a doc

Prerequisites

API reference

Examples

Upsert a single document

Upsert a document with fields

Upsert multiple documents in a batch

Upsert documents asynchronously

Upsert a document with a sparse vector

Request parameters

UpsertDocRequest builder

Doc builder

Response parameters

What's next