Data Operations

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.

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:

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:

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.

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

type FieldPartialUpdateOp = {
  field_name: string;
  op:
    | FieldPartialUpdateOpType.REPLACE
    | FieldPartialUpdateOpType.ARRAY_APPEND
    | FieldPartialUpdateOpType.ARRAY_REMOVE
    | 'REPLACE'
    | 'ARRAY_APPEND'
    | 'ARRAY_REMOVE';
};

Example:

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.

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.

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:

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.

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.
• order_by_fields?: Sort fields, such as 'price:asc' or [{ field: 'price', order: 'asc' }].
• order_by?: Alias for order_by_fields.
• consistency_level?: Consistency level.
• transformers?: Custom transformers for vector outputs.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

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

Response:

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

get

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

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.

count(data: CountReq): Promise<CountResult>

Parameters:

• collection_name: Collection name.
• expr?: Filter expression. Defaults to all rows when omitted.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Response:

• status: Response status.
• data: Count as a number.

search

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

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.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

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 by primary key:

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

Hybrid search

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:

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.

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

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.

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:

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.

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:

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.

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.

flushSync(data: FlushReq): Promise<GetFlushStateResponse>

getFlushState

Check flush state by segment IDs or collection/timestamp.

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.

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

Response includes flush_all_tss, flush_all_msgs, and cluster_info.

flushAllSync

Flush all collections and wait for completion.

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

getFlushAllState

getFlushAllState(data: GetFlushAllStateReq): Promise<GetFlushAllStateResponse>

Use flush_all_tss returned by flushAll.

Compaction and segment APIs

compact

Trigger compaction for a collection.

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

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.

getQuerySegmentInfo(data: GetQuerySegmentInfoReq): Promise<GetQuerySegmentInfoResponse>

getPersistentSegmentInfo

Get segment information from data nodes.

getPersistentSegmentInfo(data: GePersistentSegmentInfoReq): Promise<GePersistentSegmentInfoResponse>

Load balancing

loadBalance

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

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.

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

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

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
• Insert & Update guide
• Query & Search guide
• Index Operations