Insert documents - DashVector - Alibaba Cloud Documentation Center

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

Note

If the ID of a document to be inserted already exists, the existing document is not overwritten, and the insert operation is invalid for the document.

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> insert(InsertDocRequest insertDocRequest);

// The method working in asynchronous mode.
public ListenableFuture<Response<Void>> insertAsync(InsertDocRequest insertDocRequest);

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.

Insert a document

Java

import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorClientConfig;
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 com.google.common.util.concurrent.ListenableFuture;

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();
        
        // Insert the document.
        Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());
        
        // Check whether the insert method is successfully called.
      	assert response.isSuccess() 
    }
}

Insert a document with fields

Java

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

// Insert 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)
  .field("id", 1234567890l)
  // Specify schema-free fields and values.
  .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());

// Check whether the insert method is successfully called.
assert response.isSuccess()

Insert multiple documents at a time

Java

// Use InsertDocRequest objects to insert 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()
  );
}

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

// Check whether the insert method is successfully called.
assert response.isSuccess();

Asynchronously insert documents

Java

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

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

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

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

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

Request parameters

You can use an InsertDocRequestBuilder instance to build an InsertDocRequest 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 `InsertDocRequest` 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
getCMessage()	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