< Docs
  • Java


A MilvusClient interface. This method inserts new entities into a specified collection, and replaces them if the entities already exist.

R<MutationResult> upsert(UpsertParam requestParam);


Use the UpsertParam.Builder to construct an UpsertParam object.

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

Methods of UpsertParam.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.
withPartitionName(String partitionName) Sets the target partition name(optional). partitionName: The name of the partition to insert data into.
withFields(List\ fields) Sets the column-based data to be inserted. The fields 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\ 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 JSONObject objects, each representing a row in key-value format.
- Requires List\ if the data type is Bool.
- Requires List\ if the data type is Int64.
- Requires List\ or List\ if the data type is Int8/Int16/Int32.
- Value is List\ if the data type is Float.
- Value is List\ if the data type is Double.
- Value is List\ if the data type is Varchar.
- Value is List\gt; if the data type is Array, the inner List type must be equal to the element type of the Array field.
- Value is List\gt;, if the data type is FloatVector.
- Value is List\, if the data type is BinaryVector
build() Constructs an InsertParam object. N/A

The can throw the following exceptions:

  • ParamException: error if the parameter is invalid.


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.


import io.milvus.param.*;
import io.milvus.response.MutationResultWrapper;
import io.milvus.grpc.MutationResult;

List<List<Float>> vectors = generateFloatVectors(1);
List<JSONObject> rows = new ArrayList<>();
JSONObject row = new JSONObject();
row.put("id", 1L);
row.put("vec", vectors.get(0);

UpsertParam param = UpsertParam.newBuilder()

R<MutationResult> response = client.upsert(param);
if (response.getStatus() != R.Status.Success.getCode()) {

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