# Data Operations

Look up Milvus Node.js SDK methods for writes, queries, vector searches, deletes, iterators, compaction, and bulk import.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/api-reference/data/

## Section links

- [insert](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#insert)
- [upsert](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#upsert)
- [deleteEntities](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#deleteentities)
- [delete](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#delete)
- [query](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#query)
- [Query aggregation](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#query-aggregation)
- [get](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#get)
- [count](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#count)
- [search](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#search)
- [Simple search parameters](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#simple-search-parameters)
- [Search aggregation](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#search-aggregation)
- [Hybrid search](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#hybrid-search)
- [searchIterator](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#searchiterator)
- [queryIterator](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#queryiterator)
- [Flush APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#flush-apis)
- [flush](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#flush)
- [flushSync](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#flushsync)
- [getFlushState](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getflushstate)
- [flushAll](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#flushall)
- [flushAllSync](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#flushallsync)
- [getFlushAllState](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getflushallstate)
- [Compaction and segment APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#compaction-and-segment-apis)
- [compact](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#compact)
- [getCompactionState](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getcompactionstate)
- [getQuerySegmentInfo](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getquerysegmentinfo)
- [getPersistentSegmentInfo](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getpersistentsegmentinfo)
- [Load balancing](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#load-balancing)
- [loadBalance](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#loadbalance)
- [Bulk import APIs](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#bulk-import-apis)
- [bulkInsert](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#bulkinsert)
- [listImportTasks](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#listimporttasks)
- [getImportState](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#getimportstate)
- [Related](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#related)

Data APIs write, read, search, delete, flush, compact, and bulk-import collection data. Most request types extend `collectionNameReq`, so they accept `collection_name`, optional `db_name`, optional `timeout`, and optional request tracing fields.

## insert

Insert rows into a collection.

```typescript
insert(data: InsertReq): Promise<MutationResult>
```

**Parameters**:

- `collection_name`: Collection name.
- `data` or `fields_data`: Array of row objects. These two fields are aliases and are mutually exclusive.
- `partition_name?`: Target partition.
- `hash_keys?`: Hash keys generated from primary key values.
- `transformers?`: Custom transformers for `Float16Vector` or `BFloat16Vector` insert data.
- `skip_check_schema?`: Skip schema validation.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

Example:

```typescript
const res = await client.insert({
  collection_name: 'books',
  data: [
    {
      id: 1,
      title: 'Vector databases',
      embedding: [0.1, 0.2, 0.3, 0.4],
      category: 'database',
    },
  ],
});
```

**Response**:

```typescript
interface MutationResult {
  status: ResStatus;
  succ_index: Number[];
  err_index: Number[];
  acknowledged: boolean;
  insert_cnt: string;
  delete_cnt: string;
  upsert_cnt: string;
  timestamp: string;
  IDs: StringArrayId | NumberArrayId;
}
```

## upsert

Insert or update rows by primary key.

```typescript
upsert(data: UpsertReq): Promise<MutationResult>
```

In addition to `InsertReq` fields, `UpsertReq` accepts:

- `partial_update?`: Update only provided fields.
- `field_ops?`: Per-field partial update operations. Providing `field_ops` automatically enables partial update behavior. Milvus 3.0

```typescript
type FieldPartialUpdateOp = {
  field_name: string;
  op:
    | FieldPartialUpdateOpType.REPLACE
    | FieldPartialUpdateOpType.ARRAY_APPEND
    | FieldPartialUpdateOpType.ARRAY_REMOVE
    | FieldPartialUpdateOpType.PATH_REPLACE
    | 'REPLACE'
    | 'ARRAY_APPEND'
    | 'ARRAY_REMOVE'
    | 'PATH_REPLACE';
  path?: string; // Required for PATH_REPLACE on Milvus 3.0.6+
};
```

Example:

```typescript
import { FieldPartialUpdateOpType } from '@zilliz/milvus2-sdk-node';

await client.upsert({
  collection_name: 'books',
  data: [{ id: 1, tags: ['database'], scores: [0.9] }],
  field_ops: [
    { field_name: 'tags', op: FieldPartialUpdateOpType.ARRAY_APPEND },
    { field_name: 'scores', op: 'ARRAY_APPEND' },
  ],
});
```

## deleteEntities

Delete rows with an explicit boolean expression. This is the lower-level delete API.

```typescript
deleteEntities(data: DeleteEntitiesReq): Promise<MutationResult>
```

**Parameters**:

- `collection_name`: Collection name.
- `expr` or `filter`: Boolean expression. One is required.
- `exprValues?`: Template values for filter expressions.
- `partition_name?`: Partition name.
- `consistency_level?`: Consistency level.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

## delete

Delete rows by primary keys or by filter.

```typescript
delete(data: DeleteReq): Promise<MutationResult>
```

**Parameters**:

- `collection_name`: Collection name.
- `ids?`: Primary key values. The SDK converts these into the correct primary-key expression.
- `filter?`: Filter expression. Takes precedence over `ids`.
- `expr?`: Alias for filter expression.
- `exprValues?`: Template values for filter expressions.
- `partition_name?`: Partition name.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

Examples:

```typescript
await client.delete({
  collection_name: 'books',
  ids: [1, 2, 3],
});

await client.delete({
  collection_name: 'books',
  filter: 'category == "archived"',
});
```

## query

Query rows by primary key or scalar filter.

```typescript
query(data: QueryReq): Promise<QueryResults>
```

**Parameters**:

- `collection_name`: Collection name.
- `ids?`: Primary key values. Converted to a primary-key `in` expression.
- `expr?` / `filter?`: Scalar filter expression.
- `exprValues?`: Template values for filter expressions.
- `output_fields?`: Fields to return. Defaults to `['*']`.
- `partition_names?`: Partition names.
- `offset?`: Number of rows to skip.
- `limit?`: Number of rows to return.
- `group_by_fields?`: Scalar fields used to group aggregation results.
- `order_by_fields?`: Sort fields, such as `'price:asc'` or `[{ field: 'price', order: 'asc' }]`.
- `order_by?`: Alias for `order_by_fields`.
- `params?`: Additional query parameters forwarded to Milvus.
- `consistency_level?`: Consistency level.
- `transformers?`: Custom transformers for vector outputs.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

Example:

```typescript
const res = await client.query({
  collection_name: 'books',
  filter: 'category == "database"',
  output_fields: ['id', 'title', 'category'],
  limit: 10,
  order_by_fields: 'id:asc',
});
```

### Query aggregation

 Milvus 3.0 

Specify aggregation expressions in `output_fields`. Use `group_by_fields` to return one row per scalar group. Supported aggregation functions are `count`, `min`, `max`, `sum`, and `avg`.

```typescript
const res = await client.query({
  collection_name: 'sales',
  filter: 'price > 0',
  group_by_fields: ['category'],
  output_fields: [
    'category',
    'count(price)',
    'min(price)',
    'max(price)',
    'sum(price)',
    'avg(price)',
  ],
  limit: 20,
});

for (const row of res.data) {
  console.log(row.category, row['count(price)'], row['avg(price)']);
}
```

Without `group_by_fields`, aggregation expressions return collection-level values. Response keys use the expressions supplied in `output_fields`.

**Response**:

```typescript
interface QueryResults {
  status: ResStatus;
  data: Record<string, any>[];
}
```

## get

Get rows by primary key. This is a convenience wrapper around `query`.

```typescript
get(data: GetReq): Promise<QueryResults>
```

**Parameters**:

- `collection_name`: Collection name.
- `ids`: Primary key values.
- `output_fields?`: Fields to return.
- `partition_names?`: Partition names.
- `offset?`: Number of rows to skip.
- `limit?`: Number of rows to return.
- `consistency_level?`: Consistency level.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

## count

Count rows matching a filter.

```typescript
count(data: CountReq): Promise<CountResult>
```

**Parameters**:

- `collection_name`: Collection name.
- `expr?`: Filter expression. Defaults to all rows when omitted.
- `filter?`: Alias for `expr`.
- `exprValues?`: Values for placeholders in the filter expression.
- `partition_names?`: Partition names to count within.
- `consistency_level?`: Query consistency level (`ConsistencyLevelEnum`).
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.
- `client_request_id?` / `client-request-id?`: Request ID for tracing.

**Response**:

- `status`: Response status.
- `data`: Count as a number, or `0` when the query fails.

Check `status.error_code` before using `data`. When the server rejects the query, `count()` returns the original error status and reason with `data: 0`.

## search

Perform vector, text, search-by-primary-key, or hybrid search. `hybridSearch` is an alias of `search` with `HybridSearchReq`.

```typescript
search<T extends SearchReq | SearchSimpleReq | HybridSearchReq>(params: T): Promise<SearchResults<T>>
hybridSearch(data: HybridSearchReq): Promise<SearchResults<HybridSearchReq>> // alias
```

### Simple search parameters

- `collection_name`: Collection name.
- `data?` / `vector?`: Query vector, text, or array of query vectors/text.
- `ids?`: Primary key IDs for Search By PK. Vector data is not required when `ids` is provided.
- `anns_field?`: Vector field name. Required for multi-vector collections.
- `partition_names?`: Partition names.
- `output_fields?`: Fields to return.
- `limit?` / `topk?`: Number of hits per query.
- `offset?`: Result offset.
- `filter?` / `expr?`: Scalar filter.
- `exprValues?`: Template values for filter expressions.
- `params?`: Search params such as `nprobe`, `ef`, or `radius`.
- `metric_type?`: Distance metric.
- `consistency_level?`: Consistency level.
- `ignore_growing?`: Ignore growing segments.
- `group_by_field?`, `group_size?`, `strict_group_size?`: Grouping controls.
- `order_by_fields?`: Sort fields.
- `hints?`: Search hints.
- `round_decimal?`: Score rounding.
- `transformers?`: Custom output transformers.
- `rerank?`: Reranker configuration.
- `highlighter?`: Text highlight configuration.
- `search_aggregation?`: Bucket aggregation configuration.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

Example:

```typescript
const res = await client.search({
  collection_name: 'books',
  data: [[0.1, 0.2, 0.3, 0.4]],
  anns_field: 'embedding',
  limit: 5,
  filter: 'category == "database"',
  output_fields: ['title', 'category'],
  params: { ef: 64 },
});
```

### Search aggregation

 Milvus 3.0 

`search_aggregation` groups search candidates into buckets and can calculate metrics, return sorted top hits, and recursively create nested buckets.

```typescript
const res = await client.search({
  collection_name: 'products',
  anns_field: 'embedding',
  data: [0.1, 0.2, 0.3, 0.4],
  limit: 100,
  filter: 'in_stock == true',
  output_fields: ['category', 'brand', 'price'],
  search_aggregation: {
    fields: ['category'],
    size: 5,
    metrics: {
      item_count: { op: 'count', field_name: '*' },
      average_price: { op: 'avg', field_name: 'price' },
    },
    order: [{ key: 'average_price', direction: 'desc' }],
    top_hits: {
      size: 2,
      sort: [{ field_name: 'price', direction: 'asc' }],
    },
    sub_aggregation: {
      fields: ['brand'],
      size: 3,
    },
  },
});

console.log(res.agg_buckets);
```

```typescript
interface SearchAggregation {
  fields: string[];
  size: number;
  metrics?: Record<
    string,
    { op: 'avg' | 'sum' | 'count' | 'min' | 'max'; field_name: string }
  >;
  order?: { key: string; direction: 'asc' | 'desc' }[];
  top_hits?: {
    size: number;
    sort?: { field_name: string; direction: 'asc' | 'desc' }[];
  };
  sub_aggregation?: SearchAggregation;
}
```

A single query vector returns `AggregationBucket[]`; multiple query vectors return `AggregationBucket[][]`. Aggregation searches return their grouped data through `agg_buckets` instead of regular hit rows. Search aggregation cannot be combined with hybrid search, highlighters, `group_by_field`, `group_by_fields`, or a positive offset.

Search by primary key:

```typescript
const res = await client.search({
  collection_name: 'books',
  ids: [1, 2, 3],
  output_fields: ['title'],
});
```

### Hybrid search

```typescript
type HybridSearchReq = {
  collection_name: string;
  data: HybridSearchSingleReq[];
  rerank?: RerankerObj | FunctionObject | FunctionScore;
  limit?: number;
  output_fields?: string[];
  partition_names?: string[];
  filter?: string;
  params?: Record<string, any>;
};
```

Example:

```typescript
const res = await client.hybridSearch({
  collection_name: 'books',
  data: [
    {
      anns_field: 'dense_embedding',
      data: [0.1, 0.2, 0.3, 0.4],
      params: { ef: 64 },
    },
    {
      anns_field: 'sparse_embedding',
      data: { 10: 0.8, 42: 0.3 },
    },
  ],
  rerank: { strategy: 'rrf', params: { k: 60 } },
  limit: 10,
  output_fields: ['title'],
});
```

**Search response**:

Milvus 3.0 Milvus 3.0 can return element-level offsets and grouped search metadata. The SDK exposes them as `offset` and `group_by_field_values` on each result row.

```typescript
interface SearchResults<T> {
  status: ResStatus;
  results: SearchResultData[] | SearchResultData[][];
  recalls: number[];
  session_ts: number;
  collection_name: string;
  all_search_count?: number;
  agg_buckets?: AggregationBucket[] | AggregationBucket[][];
}

interface SearchResultData {
  [fieldName: string]: any;
  score: number;
  id: string;
  offset?: number | string; // Milvus 3.0 element-level result offset
  group_by_field_values?: Record<string, FieldData>; // Milvus 3.0 grouped result metadata
  highlight?: HighlightResult;
}
```

## searchIterator

Iterate search results by batch.

```typescript
searchIterator(data: SearchIteratorReq): Promise<AsyncIterable<SearchResultData[]>>
```

**Parameters**:

- All relevant `SearchSimpleReq` fields except `offset`, `limit`, and `topk`.
- `batchSize`: Number of items to return in each batch. Values above 16384 are capped.
- `limit?`: Maximum number of items to iterate. Omit for no limit.
- `external_filter_fn?`: Client-side row filter.

Example:

```typescript
const iterator = await client.searchIterator({
  collection_name: 'books',
  data: [0.1, 0.2, 0.3, 0.4],
  batchSize: 100,
  limit: 1000,
});

for await (const batch of iterator) {
  console.log(batch);
}
```

## queryIterator

Iterate query results by batch.

```typescript
queryIterator(data: QueryIteratorReq): Promise<AsyncIterable<Record<string, any>[]>>
```

**Parameters**:

- All relevant `QueryReq` fields except `ids`, `offset`, and `limit`.
- `batchSize`: Number of items to return in each batch. Values above 16384 are capped.
- `limit?`: Maximum number of items to iterate. Omit for no limit.

Example:

```typescript
const iterator = await client.queryIterator({
  collection_name: 'books',
  filter: 'category == "database"',
  output_fields: ['id', 'title'],
  batchSize: 100,
});

for await (const rows of iterator) {
  console.log(rows);
}
```

## Flush APIs

### flush

Flush specified collections asynchronously.

```typescript
flush(data: FlushReq): Promise<FlushResult>
```

**Parameters**:

- `collection_names`: Collection names.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

### flushSync

Flush specified collections and wait for flush completion.

```typescript
flushSync(data: FlushReq): Promise<GetFlushStateResponse>
```

### getFlushState

Check flush state by segment IDs or collection/timestamp.

```typescript
getFlushState(data: GetFlushStateReq): Promise<GetFlushStateResponse>
```

**Parameters**:

- `segmentIDs?`: Segment IDs returned by `flush`.
- `flush_ts?`: Flush timestamp.
- `collection_name?`: Collection name.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

### flushAll

Flush all collections asynchronously.

```typescript
flushAll(data?: FlushAllReq): Promise<FlushAllResponse>
```

**Response** includes `flush_all_tss`, `flush_all_msgs`, and `cluster_info`.

### flushAllSync

Flush all collections and wait for completion.

```typescript
flushAllSync(data?: FlushAllReq): Promise<GetFlushAllStateResponse>
```

### getFlushAllState

```typescript
getFlushAllState(data: GetFlushAllStateReq): Promise<GetFlushAllStateResponse>
```

Use `flush_all_tss` returned by `flushAll`.

## Compaction and segment APIs

### compact

Trigger compaction for a collection.

```typescript
compact(data: CompactReq): Promise<CompactionResponse>
```

**Parameters**:

- `collection_name`: Collection name.
- `timetravel?`: Timestamp boundary.
- `majorCompaction?`: Request major compaction.
- `partition_id?`: Target partition ID.
- `channel?`: Target DML channel.
- `segment_ids?`: Target segment IDs.
- `l0Compaction?`: Request L0 compaction.
- `target_size?`: Target segment size in bytes.
- `db_name?`: Database name.

### getCompactionState

```typescript
getCompactionState(data: GetCompactionStateReq): Promise<GetCompactionStateResponse>
```

**Parameters**:

- `compactionID`: Compaction ID returned by `compact`.
- `timeout?`: Request timeout in milliseconds.

### getQuerySegmentInfo

Get growing segment information from query nodes.

```typescript
getQuerySegmentInfo(data: GetQuerySegmentInfoReq): Promise<GetQuerySegmentInfoResponse>
```

### getPersistentSegmentInfo

Get segment information from data nodes.

```typescript
getPersistentSegmentInfo(data: GePersistentSegmentInfoReq): Promise<GePersistentSegmentInfoResponse>
```

## Load balancing

### loadBalance

Perform load balancing from a source query node to destination query nodes.

```typescript
loadBalance(data: LoadBalanceReq): Promise<ResStatus>
```

**Parameters**:

- `src_nodeID`: Source query node ID.
- `dst_nodeIDs?`: Destination query node IDs.
- `sealed_segmentIDs?`: Sealed segment IDs.
- `collectionName?`: Collection name.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

## Bulk import APIs

### bulkInsert

Import data from files.

```typescript
bulkInsert(data: ImportReq): Promise<ImportResponse>
```

**Parameters**:

- `collection_name`: Collection name.
- `files`: File paths.
- `partition_name?`: Partition name.
- `channel_names?`: Channel names.
- `options?`: Import options as `KeyValuePair[]`.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

**Response**:

- `tasks`: Import task IDs.

### listImportTasks

```typescript
listImportTasks(data: ListImportTasksReq): Promise<ListImportTasksResponse>
```

**Parameters**:

- `collection_name`: Collection name.
- `limit?`: Max tasks returned. `0` lists all tasks.
- `db_name?`: Database name.
- `timeout?`: Request timeout in milliseconds.

### getImportState

```typescript
getImportState(data: GetImportStateReq): Promise<GetImportStateResponse>
```

**Parameters**:

- `task`: Import task ID.
- `timeout?`: Request timeout in milliseconds.

**Response** includes `state`, `row_count`, `id_list`, `infos`, `collection_id`, and `segment_ids`.

## Related

- [API Reference overview](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- [Insert & Update guide](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-insert/)
- [Query & Search guide](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/)
- [Index Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/indexes/)
