Insert documents into a collection using the Java SDK - DashVector

Insert one or more documents into a DashVector collection using the Java SDK. A document consists of an ID, a dense vector, and optional fields or sparse vectors.

If a document ID already exists in the collection, the insert operation skips that document without overwriting it.

Before you begin

API definition

The DashVectorCollection class provides both synchronous and asynchronous insert methods:

Java

// Synchronous insert
public Response<Void> insert(InsertDocRequest insertDocRequest);

// Asynchronous insert
public ListenableFuture<Response<Void>> insertAsync(InsertDocRequest insertDocRequest);

Examples

All examples use a collection named quickstart with 4-dimensional vectors.

Note

Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with your cluster endpoint.
Create the quickstart collection before running these examples. See the "Example" section in Create a collection.

Insert 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.InsertDocRequest;
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();

        // Insert the document
        Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

        // Verify the result
        if (response.isSuccess()) {
            System.out.println("Document inserted successfully.");
        } else {
            System.out.println("Insert failed: " + response.getCMessage());
        }
    }
}

Insert a document with fields

Add predefined or schema-free fields as key-value pairs.

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

// Insert the document
Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

if (response.isSuccess()) {
    System.out.println("Document inserted successfully.");
} else {
    System.out.println("Insert failed: " + response.getCMessage());
}

Insert multiple documents in a batch

Pass a list of Doc objects to insert them in a single request.

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

InsertDocRequest request = InsertDocRequest.builder().docs(docs).build();
Response<Void> response = collection.insert(request);

if (response.isSuccess()) {
    System.out.println("Batch insert succeeded.");
} else {
    System.out.println("Batch insert failed: " + response.getCMessage());
}

Insert documents asynchronously

insertAsync returns a ListenableFuture so the calling thread is not blocked. Call future.get() to wait for the result.

Java

import com.google.common.util.concurrent.ListenableFuture;

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

InsertDocRequest request = InsertDocRequest.builder().docs(docs).build();
ListenableFuture<Response<Void>> future = collection.insertAsync(request);

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

if (response.isSuccess()) {
    System.out.println("Async insert succeeded.");
} else {
    System.out.println("Async insert failed: " + response.getCMessage());
}

Insert a document with a sparse vector

Provide a sparse vector as a Map<Integer, Float> alongside the dense vector. Each entry maps a dimension index to a non-zero value.

Java

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

// Build a sparse vector
Map<Integer, Float> sparseVector = new HashMap<>();
sparseVector.put(1, 0.4f);
sparseVector.put(10000, 0.6f);
sparseVector.put(222222, 0.8f);

// Build a document with both dense and sparse vectors
Doc doc = Doc.builder()
    .id("28")
    .vector(vector)
    .sparseVector(sparseVector)
    .build();

// Insert the document
Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

if (response.isSuccess()) {
    System.out.println("Document with sparse vector inserted.");
} else {
    System.out.println("Insert failed: " + response.getCMessage());
}

Request parameters

InsertDocRequest builder

Build an InsertDocRequest object using InsertDocRequest.builder():

Method	Required	Default	Description
`docs(List<Doc> docs)`	Yes	-	Sets the list of documents to insert.
`doc(Doc doc)`	No	-	Adds a single document to the list. Call multiple times to add more.
`partition(String partition)`	No	default	Specifies the target partition.
`build()`	-	-	Builds the `InsertDocRequest` object.

Doc builder

Build a Doc object using Doc.builder():

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)`	No	-	Adds a single field. Call multiple times to add more.
`build()`	-	-	Builds the `Doc` object.

Field type rules:

The key must be a String.
The value can be String, Integer, Boolean, or Float.
If a field key is predefined during collection creation, the value must match the predefined type.
If the key is not predefined, it is treated as a schema-free field.

For more details about the Doc data structure, see Data type definition.

Response parameters

Both insert and insertAsync return a Response<Void> object:

Method	Return type	Description	Example
`getCode()`	int	Status code. For details, see Status codes.	0
`getCMessage()`	String	Status message.	success
`getRequestId()`	String	Unique request ID.	19215409-ea66-4db9-8764-26ce2eb5bb99
`isSuccess()`	Boolean	Whether the operation succeeded.	true