feat: support partial array upsert ops (#553)

Signed-off-by: ryjiang <jiangruiyi@gmail.com>

Author: shanghaikid

3.0_change.md

@@ -164,17 +164,28 @@ message UpsertRequest {
 }
 ```
 
-Node SDK impact:
+Node SDK support:
 
-```text
-milvus/types/Data.ts or upsert request types
-  - Add field_ops support.
-  - Expose op values REPLACE, ARRAY_APPEND, ARRAY_REMOVE.
+```typescript
+import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';
 
-milvus/grpc/Data.ts and request preparation logic
-  - Pass field_ops through to UpsertRequest.
+await client.upsert({
+  collection_name: 'my_collection',
+  data: [{ id: 1, tags: ['new'], scores: [3] }],
+  field_ops: [
+    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
+    { field_name: 'scores', op: 'ARRAY_REMOVE' },
+  ],
+});
 ```
 
+Implementation notes:
+
+- `UpsertReq.field_ops` is passed through to `UpsertRequest.field_ops`.
+- `FieldPartialUpdateOpType` exposes `REPLACE`, `ARRAY_APPEND`, and `ARRAY_REMOVE`.
+- Numeric enum values are converted to proto enum names before sending the gRPC request.
+- Providing `field_ops` automatically sends `partial_update: true`.
+
 ## Element-Level Query/Search
 
 `common.proto` adds element-level placeholder support:

README.md

@@ -184,6 +184,25 @@ await client.upsert({
   collection_name: string;
   data: Record<string, any>[];
   partition_name?: string;
+  partial_update?: boolean;
+  field_ops?: Array<{
+    field_name: string;
+    op: 'REPLACE' | 'ARRAY_APPEND' | 'ARRAY_REMOVE';
+  }>;
+});
+```
+
+Partial array upsert can append to or remove from existing Array fields:
+
+```typescript
+import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';
+
+await client.upsert({
+  collection_name: 'articles',
+  data: [{ id: 1, tags: ['featured'] }],
+  field_ops: [
+    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
+  ],
 });
 ```
 

docs/content/operations/data-operations-insert.mdx

@@ -69,7 +69,9 @@ Insert large amounts of data efficiently:
 
 ```javascript
 const batchSize = 1000;
-const allData = [/* large array of data */];
+const allData = [
+  /* large array of data */
+];
 
 for (let i = 0; i < allData.length; i += batchSize) {
   const batch = allData.slice(i, i + batchSize);
@@ -196,6 +198,49 @@ await client.upsert({
 });
 ```
 
+### Partial Array Upsert
+
+For Array fields, use `field_ops` to append values to or remove values from the existing array instead of replacing the whole field.
+
+```javascript
+import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';
+
+await client.upsert({
+  collection_name: 'my_collection',
+  data: [
+    {
+      id: 1,
+      tags: ['new-tag'], // Appended to the existing tags array
+      scores: [3], // Removed from the existing scores array
+    },
+  ],
+  field_ops: [
+    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
+    { field_name: 'scores', op: FieldPartialUpdateOpType.ARRAY_REMOVE },
+  ],
+});
+```
+
+You can also pass operation names as strings:
+
+```javascript
+await client.upsert({
+  collection_name: 'my_collection',
+  data: [{ id: 1, tags: ['urgent'] }],
+  field_ops: [{ field_name: 'tags', op: 'ARRAY_APPEND' }],
+});
+```
+
+Notes:
+
+- `field_ops` is supported only by `upsert()`.
+- Each `field_ops[].field_name` must refer to an Array field.
+- The primary key must be included in each upsert row.
+- Fields not included in the upsert row remain unchanged.
+- `ARRAY_APPEND` must not make the array exceed its `max_capacity`.
+- `ARRAY_REMOVE` removes matching values from the existing array.
+- When `field_ops` is provided, the SDK automatically sends `partial_update: true`.
+
 ## Insert Transformers
 
 For Float16 and BFloat16 vectors, use transformers:
@@ -211,7 +256,7 @@ await client.insert({
     },
   ],
   transformers: {
-    vector: (data) => f32ArrayToF16Bytes(data), // Convert to f16 bytes
+    vector: data => f32ArrayToF16Bytes(data), // Convert to f16 bytes
   },
 });
 ```
@@ -223,7 +268,9 @@ The insert operation returns mutation results:
 ```javascript
 const result = await client.insert({
   collection_name: 'my_collection',
-  data: [/* ... */],
+  data: [
+    /* ... */
+  ],
 });
 
 console.log('IDs:', result.IDs); // Array of inserted IDs
@@ -251,7 +298,9 @@ Handle insertion errors:
 try {
   await client.insert({
     collection_name: 'my_collection',
-    data: [/* ... */],
+    data: [
+      /* ... */
+    ],
   });
 } catch (error) {
   if (error.message.includes('field does not exist')) {
@@ -335,4 +384,3 @@ await client.flush({
 - Learn about [Query Operations](./data-operations-query)
 - Explore [Delete Operations](./data-operations-delete)
 - Check out [Data Management](./data-management)
-

docs/content/reference/api-reference.mdx

@@ -302,6 +302,42 @@ Upsert data (insert or update).
 upsert(data: UpsertReq): Promise<MutationResult>
 ```
 
+**Parameters**:
+
+- `collection_name`: Collection name
+- `data` or `fields_data`: Array of row objects
+- `partition_name?`: Partition name
+- `partial_update?`: Whether to update only provided fields
+- `field_ops?`: Per-field partial update operations for Array fields. Providing `field_ops` automatically enables `partial_update`.
+
+```typescript
+type FieldPartialUpdateOp = {
+  field_name: string;
+  op:
+    | FieldPartialUpdateOpType.REPLACE
+    | FieldPartialUpdateOpType.ARRAY_APPEND
+    | FieldPartialUpdateOpType.ARRAY_REMOVE
+    | 'REPLACE'
+    | 'ARRAY_APPEND'
+    | 'ARRAY_REMOVE';
+};
+```
+
+Example:
+
+```typescript
+import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';
+
+await client.upsert({
+  collection_name: 'my_collection',
+  data: [{ id: 1, tags: ['new'], scores: [3] }],
+  field_ops: [
+    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
+    { field_name: 'scores', op: 'ARRAY_REMOVE' },
+  ],
+});
+```
+
 ### query
 
 Query entities by filter.

milvus/const/milvus.ts

@@ -304,6 +304,13 @@ export enum DataType {
   Struct = 201,
 }
 
+// partial update operation enum for array fields in upsert
+export enum FieldPartialUpdateOpType {
+  REPLACE = 0,
+  ARRAY_APPEND = 1,
+  ARRAY_REMOVE = 2,
+}
+
 export enum PlaceholderType {
   None = 0,
   BinaryVector = 100,

milvus/grpc/Data.ts

@@ -79,6 +79,8 @@ import {
   GetQuerySegmentInfoResponse,
   SearchData,
   FloatVector,
+  FieldPartialUpdateOpType,
+  FieldPartialUpdateOp,
 } from '../';
 import { Collection } from './Collection';
 
@@ -144,6 +146,9 @@ export class Data extends Collection {
       throw new Error(ERROR_REASONS.INSERT_CHECK_FIELD_DATA_IS_REQUIRED);
     }
     const { collection_name } = data;
+    const fieldOps = upsert
+      ? this.normalizeFieldOps((data as UpsertReq).field_ops)
+      : [];
 
     const describeReq = { collection_name, cache: enable_cache };
     if (data.db_name) {
@@ -234,7 +239,8 @@ export class Data extends Collection {
 
     // Track which fields are present in the original row data for partial updates
     const isPartialUpdate =
-      'partial_update' in data && data.partial_update === true;
+      ('partial_update' in data && data.partial_update === true) ||
+      fieldOps.length > 0;
     const originalRowKeys = new Set<string>();
 
     // Loop through each row and set the corresponding field values in the Map.
@@ -297,10 +303,11 @@ export class Data extends Collection {
       schema_timestamp:
         collectionInfo.update_timestamp_str ||
         (collectionInfo.update_timestamp as string | number | undefined),
-      // Ensure partial_update is passed for upsert operations
-      ...(upsert && (data as UpsertReq).partial_update
-        ? { partial_update: true }
-        : {}),
+      // Ensure partial_update is passed for explicit partial updates and
+      // non-REPLACE field_ops. Milvus server also auto-promotes non-REPLACE
+      // ops, but setting the flag keeps the request self-descriptive.
+      ...(upsert && isPartialUpdate ? { partial_update: true } : {}),
+      ...(upsert && fieldOps.length > 0 ? { field_ops: fieldOps } : {}),
     };
     /* istanbul ignore next if */
     if (data.skip_check_schema) {
@@ -529,6 +536,35 @@ export class Data extends Collection {
     return promise;
   }
 
+  private normalizeFieldOps(
+    fieldOps?: FieldPartialUpdateOp[]
+  ): { field_name: string; op: keyof typeof FieldPartialUpdateOpType }[] {
+    if (!fieldOps || fieldOps.length === 0) {
+      return [];
+    }
+
+    return fieldOps.map(({ field_name, op }) => {
+      if (!field_name) {
+        throw new Error('field_ops field_name is required');
+      }
+
+      if (typeof op === 'number') {
+        const opName = FieldPartialUpdateOpType[op] as
+          | keyof typeof FieldPartialUpdateOpType
+          | undefined;
+        if (typeof opName === 'undefined') {
+          throw new Error(`unsupported field partial update op: ${op}`);
+        }
+        return { field_name, op: opName };
+      }
+
+      if (typeof FieldPartialUpdateOpType[op] === 'undefined') {
+        throw new Error(`unsupported field partial update op: ${op}`);
+      }
+      return { field_name, op };
+    });
+  }
+
   /**
    * Delete entities in a Milvus collection.
    *

milvus/types/Insert.ts

@@ -19,6 +19,7 @@ import {
   VectorTypes,
   BFloat16Vector,
   Float16Vector,
+  FieldPartialUpdateOpType,
 } from '../';
 
 // Represents the possible data types for a field(cell)
@@ -72,8 +73,19 @@ interface BaseInsertReq extends collectionNameReq {
 
 // Union type to enforce mutual exclusivity
 export type InsertReq = DataInsertReq | FieldsDataInsertReq;
+export type FieldPartialUpdateOpName = keyof typeof FieldPartialUpdateOpType;
+export type FieldPartialUpdateOpValue =
+  | FieldPartialUpdateOpType
+  | FieldPartialUpdateOpName;
+
+export interface FieldPartialUpdateOp {
+  field_name: string;
+  op: FieldPartialUpdateOpValue;
+}
+
 export type UpsertReq = (DataInsertReq | FieldsDataInsertReq) & {
   partial_update?: boolean;
+  field_ops?: FieldPartialUpdateOp[];
 };
 
 // Variant with data property