Update documents using the SDK for Java - DashVector

Update the vector, fields, or sparse vector of existing documents in a DashVector collection using the Java SDK.

Warning

Unspecified fields are set to null. When you update a document with only some fields, DashVector resets all omitted fields to null rather than preserving their previous values. To avoid unintended data loss, include every field in the update request -- even those that remain unchanged. To insert a new document or fully overwrite an existing one, use Upsert documents instead.

Note

If the document ID does not exist in the collection, the update operation has no effect on that ID. No error is returned.

Prerequisites

Before you begin, ensure that you have:

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

API reference

The DashVectorCollection class provides both synchronous and asynchronous update methods:

Java

// Synchronous
public Response<Void> update(UpdateDocRequest updateDocRequest);

// Asynchronous
public ListenableFuture<Response<Void>> updateAsync(UpdateDocRequest updateDocRequest);

Request parameters

Build an UpdateDocRequest with UpdateDocRequestBuilder:

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

Build a Doc with DocBuilder:

Method	Required	Default	Description
`id(String id)`	Yes	-	Sets the primary key.
`vector(Vector vector)`	Yes	-	Sets the dense vector.
`sparseVector(Map<Integer, Float>)`	No	-	Sets the sparse vector.
`fields(Map<String, Object>)`	No	-	Sets all fields at once.
`field(String key, Object value)`	-	-	Adds a single field. Can be called multiple times.
`build()`	-	-	Builds the `Doc` object.

Note

Each field is a key-value pair where the key is a String and the value is one of String, Integer, Boolean, or Float. If the key was predefined during collection creation, the value must match the predefined type. For schema-free fields, any supported type is accepted. For more information, see Schema-free.

Response parameters

The update method returns a Response<Void> object:

Method	Type	Description	Example
`getCode()`	`int`	Status code. For more information, see Status codes.	`0`
`getMessage()`	`String`	Response message.	`success`
`getRequestId()`	`String`	Unique request ID.	`19215409-ea66-4db9-8764-26ce2eb5bb99`
`getOutput()`	`List<DocOpResult>`	The result of the doc update operation.
`isSuccess()`	`Boolean`	Whether the operation succeeded.	`true`

Examples

All examples below assume the quickstart collection exists with a 4-dimensional vector. To create this collection, see the "Example" section of Create a collection.

Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster before you run the sample code.

Update 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.UpdateDocRequest;
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();

        // Send the update request
        Response<Void> response = collection.update(UpdateDocRequest.builder().doc(doc).build());

        // Verify success
        assert response.isSuccess();
    }
}

Update a document with fields

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 (String, Integer, Boolean, or Float)
  .field("anykey1", "String")
  .field("anykey2", 1)
  .field("anykey3", true)
  .field("anykey4", 3.1415926f)
  .build();

// Send the update request
Response<Void> response = collection.update(UpdateDocRequest.builder().doc(doc).build());

// Verify success
assert response.isSuccess();

Update multiple documents in a batch

Java

// Build 10 documents (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()
  );
}

UpdateDocRequest request = UpdateDocRequest.builder().docs(docs).build();
Response<Void> response = collection.update(request);

// Verify success
assert response.isSuccess();

Update documents asynchronously

Java

// Build 10 documents (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()
  );
}

UpdateDocRequest request = UpdateDocRequest.builder().docs(docs).build();
ListenableFuture<Response<Void>> response = collection.updateAsync(request);

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

Update 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();

// Send the update request
Response<Void> response = collection.update(UpdateDocRequest.builder().doc(doc).build());

What's next

Upsert documents -- Insert new documents or overwrite existing ones entirely
Query documents -- Retrieve documents by ID
Delete documents -- Remove documents from a collection
Doc data type definition -- Full specification of the Doc object