insert()

A MilvusClient interface. This method inserts entities into a specified collection.

R<MutationResult> insert(InsertParam requestParam);

InsertParam

Use the InsertParam.Builder to construct an InsertParam object.

import io.milvus.param.InsertParam;
InsertParam.Builder builder = InsertParam.newBuilder();

Methods of InsertParam.Builder:

Method	Description	Parameters
withCollectionName(String collectionName)	Sets the target collection name. Collection name cannot be empty or null.	collectionName: The name of the collection to insert data into.
withDatabaseName(String databaseName)	Sets the database name. database name can be null for default database.	databaseName: The database name.
withPartitionName(String partitionName)	Sets the target partition name(optional).	partitionName: The name of the partition to insert data into.
withFields(List<InsertParam.Field> fields)	Sets the data to be inserted. The field list cannot be empty. Note that no input is required for the primary key field if auto_id is enabled.	fields: A list of Field objects, each representing a field.
withRows(List<gson.JsonObject> rows)	Sets the row-based data to be inserted. The row list cannot be empty. Note that if the withFields() is called, the rows by withRows() will be ignored.	rows: A list of gson.JsonObject objects, each representing a row in key-value format. For each field: - If dataType is Bool/Int8/Int16/Int32/Int64/Float/Double/Varchar, use JsonObject.addProperty(key, value) to input; - If dataType is FloatVector, use JsonObject.add(key, gson.toJsonTree(List[Float]) to input; - If dataType is BinaryVector/Float16Vector/BFloat16Vector, use JsonObject.add(key, gson.toJsonTree(byte[])) to input; - If dataType is SparseFloatVector, use JsonObject.add(key, gson.toJsonTree(SortedMap[Long, Float])) to input; - If dataType is Array, use JsonObject.add(key, gson.toJsonTree(List of Boolean/Integer/Short/Long/Float/Double/String)) to input; - If dataType is JSON, use JsonObject.add(key, JsonElement) to input; Note: 1. For scalar numeric values, value will be cut according to the type of the field. For example: An Int8 field named "XX", you set the value to be 128 by JsonObject.addProperty("XX", 128), the value 128 is cut to -128. An Int64 field named "XX", you set the value to be 3.9 by JsonObject.addProperty("XX", 3.9), the value 3.9 is cut to 3. 2. String value can be parsed to numeric/boolean type if the value is valid. For example: A Bool field named "XX", you set the value to be "TRUE" by JsonObject.addProperty("XX", "TRUE"), the string "TRUE" is parsed as true. A Float field named "XX", you set the value to be "3.5" by JsonObject.addProperty("XX", "3.5", the string "3.5" is parsed as 3.5.
build()	Constructs an InsertParam object.	N/A

📘Notes

In Java SDK versions v2.4.1 or earlier versions, the input is a fastjson.JSONObject. But fastjson is not recommended to use now because of its unsafe deserialization vulnerability. Therefore, replace fastjson with gson if you use the Java SDK of v2.4.2 or later releases.

The InsertParam.Builder.build() can throw the following exceptions:

• ParamException: error if the parameter is invalid.

Field

A tool class to hold a data field.

Methods of InsertParam.Field:

Method	Description	Parameters
Field(String name, List<?> values)	This class only provides a constructor to create a Field object.	name: The name of the data field. values: Requires List<Boolean> if the data type is Bool. Requires List<Long> if the data type is Int64. Requires List<Integer> or List<Short> if the data type is Int8/Int16/Int32. Requires List<Float> if the data type is Float. Requires List<Double> if the data type is Double. Requires List<String> if the data type is Varchar. Requires List<List<?>gt; if the data type is Array, the inner List type must be equal to the element type of the Array field. Requires List<List<Float>gt;, if the data type is FloatVector. Requires List<ByteBuffer>, if the data type is BinaryVector/Float16Vector/BFloat16Vector. Requires List<SortedMap<Long, Float>gt; if the data type is SparseFloatVector.

Returns

This method catches all the exceptions and returns an R<MutationResult> object.

• If the API fails on the server side, it returns the error code and message from the server.

• If the API fails by RPC exception, it returns R.Status.Unknown and the error message of the exception.

• If the API succeeds, it returns a valid MutationResult held by the R template. You can use MutationResultWrapper to get the returned information.

MutationResultWrapper

A tool class to encapsulate the MutationResult.

import io.milvus.response.MutationResultWrapper;
MutationResultWrapper wrapper = new MutationResultWrapper(mutationResult);

Methods of MutationResultWrapper:

Method	Description	Returns
getInsertCount()	Gets the row count of the inserted entities.	long
getLongIDs()	Gets the long ID array returned by the insert() interface if the primary key field is int64 type. Throw ParamException if the primary key type is not int64.	List<Long>
getStringIDs()	Gets the string ID array returned by the insert() interface if the primary key field is varchar type. Throw ParamException if the primary key type is not varchar type.	List<String>
getDeleteCount()	Gets the row count of the deleted entities. Currently, this value is always equal to the input row count.	long
getOperationTs()	Gets the timestamp of the operation marked by the server.	long

Example

import io.milvus.param.*;
import io.milvus.response.MutationResultWrapper;
import io.milvus.grpc.MutationResult;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

int rowCount = 10000;
List<List<Float>> vectors = generateFloatVectors(rowCount);

// insert data by columns
List<Long> ids = new ArrayList<>();
for (long i = 0L; i < rowCount; ++i) {
    ids.add(i);
}

List<InsertParam.Field> fields = new ArrayList<>();
fields.add(new InsertParam.Field("id", ids));
fields.add(new InsertParam.Field("vector", vectors));

R<MutationResult> response = client.insert(InsertParam.newBuilder()
        .withCollectionName(COLLECTION_NAME)
        .withFields(fields)
        .build());
if (response.getStatus() != R.Status.Success.getCode()) {
    System.out.println(response.getMessage());
}

MutationResultWrapper wrapper = new MutationResultWrapper(response.getData());
System.out.println(wrapper.getInsertCount() + " rows inserted");

// insert data by rows
Gson gson = new Gson();
List<JsonObject> rows = new ArrayList<>();
for (int i = 1; i <= rowCount; ++i) {
    JsonObject row = new JsonObject();
    row.addProperty("id", (long)i);
    row.add("vector", gson.toJsonTree(vectors.get(i)));
    rows.add(row);
}

response = client.insert(InsertParam.newBuilder()
        .withCollectionName(COLLECTION_NAME)
        .withRows(rows)
        .build());
if (response.getStatus() != R.Status.Success.getCode()) {
    System.out.println(response.getMessage());
}