HttpClient
HttpClient is the REST client exported by @zilliz/milvus2-sdk-node. Use it when an environment prefers HTTP over gRPC, such as serverless platforms, HTTP-only runtimes, or proxy-restricted deployments.
HTTP request fields use the REST API’s camelCase naming convention, for example collectionName, dbName, outputFields, and indexParams. gRPC APIs on MilvusClient use snake_case fields such as collection_name and output_fields.
Constructor
Section titled “Constructor”new HttpClient(config: HttpClientConfig)type HttpClientConfig = | { endpoint: string; baseURL?: string; database?: string; token?: string; username?: string; password?: string; timeout?: number; fetch?: typeof fetch; acceptInt64?: boolean; } | { baseURL: string; endpoint?: string; database?: string; token?: string; username?: string; password?: string; timeout?: number; fetch?: typeof fetch; acceptInt64?: boolean; };endpoint is the cluster origin, such as https://your-cluster.example.com. The SDK appends /v2 automatically. If you set baseURL directly, include the full versioned base URL, such as https://your-cluster.example.com/v2. A base URL without /v2 can produce 404 responses.
Example:
import { HttpClient, HttpError } from '@zilliz/milvus2-sdk-node';
const client = new HttpClient({ endpoint: 'https://your-cluster.example.com', token: process.env.MILVUS_TOKEN, database: 'default', timeout: 30_000, acceptInt64: true,});Per-request options
Section titled “Per-request options”Every HTTP method accepts an optional FetchOptions object.
type FetchOptions = { abortController: AbortController; timeout: number;};Example:
await client.search( { collectionName: 'books', data: [[0.1, 0.2, 0.3, 0.4]], outputFields: ['title'], limit: 10, }, { abortController: new AbortController(), timeout: 10_000 });Collection APIs
Section titled “Collection APIs”createCollection
Section titled “createCollection”createCollection(data, options?)
Create a collection by dimension shortcut or explicit schema.
describeCollection
Section titled “describeCollection”describeCollection(data: HttpBaseReq, options?: FetchOptions): Promise<HttpCollectionDescribeResponse>Pass collectionName. Optionally set dbName.
const { code, data } = await client.describeCollection({ collectionName: 'books',});Returns a Milvus response envelope with collection metadata, including schema fields, indexes, and load state.
dropCollection
Section titled “dropCollection”dropCollection(data, options?)
Drop a collection.
addCollectionField
Section titled “addCollectionField”addCollectionField(data, options?)
Add a field to an existing collection.
alterCollectionProperties
Section titled “alterCollectionProperties”alterCollectionProperties(data, options?)
Add or update collection properties.
alterCollectionFieldProperties
Section titled “alterCollectionFieldProperties”alterCollectionFieldProperties(data, options?)
Alter field-level properties such as max_length, max_capacity, or mmap_enabled.
dropCollectionProperties
Section titled “dropCollectionProperties”dropCollectionProperties(data, options?)
Remove collection properties by key.
listCollections
Section titled “listCollections”listCollections(data?: HttpCollectionListReq, options?: FetchOptions): Promise<HttpCollectionListResponse>All inputs are optional. Set dbName to choose the database.
const { code, data } = await client.listCollections({ dbName: 'default' });Returns a Milvus response envelope with collection names as a string array.
hasCollection
Section titled “hasCollection”hasCollection(data, options?)
Check whether a collection exists.
renameCollection
Section titled “renameCollection”renameCollection(data, options?)
Rename a collection, optionally into another database.
getCollectionStatistics
Section titled “getCollectionStatistics”getCollectionStatistics(data, options?)
Get collection statistics such as row count.
flushCollection
Section titled “flushCollection”flushCollection(data, options?)
Flush a collection.
loadCollection
Section titled “loadCollection”loadCollection(data, options?)
Load a collection into memory.
releaseCollection
Section titled “releaseCollection”releaseCollection(data, options?)
Release a loaded collection.
getCollectionLoadState
Section titled “getCollectionLoadState”getCollectionLoadState(data, options?)
Get load progress and load state.
compactCollection
Section titled “compactCollection”compactCollection(data, options?)
Start collection compaction.
getCompactionState
Section titled “getCompactionState”getCompactionState(data, options?)
Get compaction progress by compaction ID.
refreshLoad
Section titled “refreshLoad”refreshLoad(data, options?)
Refresh an existing loaded collection.
Collection maintenance example
Section titled “Collection maintenance example”await client.flushCollection({ collectionName: 'books' });
const loadState = await client.getCollectionLoadState({ collectionName: 'books',});
const compaction = await client.compactCollection({ collectionName: 'books',});Data APIs
Section titled “Data APIs”insert
Section titled “insert”insert(data, options?)
Insert rows.
upsert
Section titled “upsert”upsert(data, options?)
Insert or update rows.
get(data, options?)
Fetch rows by ID.
query(data: HttpVectorQueryReq, options?: FetchOptions): Promise<HttpVectorQueryResponse>Pass collectionName and outputFields. Use filter to select rows or set a limit for an unfiltered query.
const { code, data } = await client.query({ collectionName: 'books', outputFields: ['title'], limit: 5,});Returns a Milvus response envelope with matching rows.
search
Section titled “search”search(data: HttpVectorSearchReq | HttpVectorSearchByIdsReq, options?: FetchOptions): Promise<HttpVectorSearchResponse>Pass collectionName, outputFields, and either a batch of search inputs in data or stored primary keys in ids. Specify annsField when the collection has multiple vector fields.
const { code, data } = await client.search({ collectionName: 'books', data: [[0.1, 0.2, 0.3, 0.4]], annsField: 'vector', outputFields: ['title'], limit: 5,});Returns a Milvus response envelope with search hits with IDs, distances, and requested fields. The aggregation overload takes HttpVectorSearchAggregationReq and returns HttpVectorSearchAggregationResponse with buckets.
hybridSearch
Section titled “hybridSearch”hybridSearch(data, options?)
Hybrid search over multiple vector requests with reranking.
delete
Section titled “delete”delete(data, options?)
Delete rows by filter.
Filtering, ordering, and grouping
Section titled “Filtering, ordering, and grouping”Use exprParams to bind filter placeholders such as label in {labels} in query, delete, search, or individual hybrid search requests. For query results, use orderByFields with keys such as 'price:desc'. To group rows, pass scalar groupByFields and aggregation expressions such as 'count(*)' in outputFields. These options were verified on Milvus 3.0.6.
REST search() accepts a batch of vectors or text in data, or searches using stored primary keys in ids. Pass large int64 primary keys as decimal strings. Use orderByFields for scalar ordering and groupingField, groupSize, and strictGroupSize for grouped search. Hybrid search also accepts the grouping options.
Use functionChains for REST search and hybrid reranking. A chain sends the protobuf stage name as a string such as 'FunctionChainStageL2Rerank', followed by its ops. In an expression argument, send a column as { column: '$score' } or a JSON literal as { literal: 2 }. Hybrid search accepts chains on the full request and on each sub-search. These options were verified on Milvus 3.0.6.
Pass searchAggregation to search() to return buckets for each query vector. Set fields and size, and use metrics, order, topHits, or subAggregation to customize the buckets. The response returns each query’s buckets in data and the corresponding counts in aggTopks. Int64 bucket values and counts are decimal strings with the default acceptInt64: false. Milvus 3.0.6 supports this option on vector search.
Database APIs
Section titled “Database APIs”createDatabase
Section titled “createDatabase”createDatabase(data, options?)
Create a database.
dropDatabase
Section titled “dropDatabase”dropDatabase(data, options?)
Drop a database.
describeDatabase
Section titled “describeDatabase”describeDatabase(data, options?)
Describe database metadata and properties.
listDatabases
Section titled “listDatabases”listDatabases(options?)
List databases.
alterDatabaseProperties
Section titled “alterDatabaseProperties”alterDatabaseProperties(data, options?)
Add or update database properties.
dropDatabaseProperties
Section titled “dropDatabaseProperties”dropDatabaseProperties(data, options?)
Remove database properties by key.
Index APIs
Section titled “Index APIs”createIndex
Section titled “createIndex”createIndex(data, options?)
Create one or more indexes.
dropIndex
Section titled “dropIndex”dropIndex(data, options?)
Drop an index.
describeIndex
Section titled “describeIndex”describeIndex(data, options?)
Describe indexes.
listIndexes
Section titled “listIndexes”listIndexes(data, options?)
List index names.
alterIndexProperties
Section titled “alterIndexProperties”alterIndexProperties(data, options?)
Add or update index properties.
dropIndexProperties
Section titled “dropIndexProperties”dropIndexProperties(data, options?)
Remove index properties by key.
Partition APIs
Section titled “Partition APIs”listPartitions
Section titled “listPartitions”listPartitions(data, options?)
List partitions.
createPartition
Section titled “createPartition”createPartition(data, options?)
Create a partition.
dropPartition
Section titled “dropPartition”dropPartition(data, options?)
Drop a partition.
loadPartitions
Section titled “loadPartitions”loadPartitions(data, options?)
Load partitions.
releasePartitions
Section titled “releasePartitions”releasePartitions(data, options?)
Release partitions.
hasPartition
Section titled “hasPartition”hasPartition(data, options?)
Check whether a partition exists.
getPartitionStatistics
Section titled “getPartitionStatistics”getPartitionStatistics(data, options?)
Get partition statistics such as row count.
Alias APIs
Section titled “Alias APIs”listAliases
Section titled “listAliases”listAliases(data, options?)
List aliases in a database or collection.
createAlias
Section titled “createAlias”createAlias(data, options?)
Create an alias for a collection.
describeAlias
Section titled “describeAlias”describeAlias(data, options?)
Describe an alias.
alterAlias
Section titled “alterAlias”alterAlias(data, options?)
Move an alias to another collection.
dropAlias
Section titled “dropAlias”dropAlias(data, options?)
Drop an alias.
Import APIs
Section titled “Import APIs”HTTP import APIs are separate from the gRPC bulkInsert, getImportState, and listImportTasks APIs.
listImportJobs
Section titled “listImportJobs”listImportJobs(data, options?)
List REST import jobs for a collection.
createImportJobs
Section titled “createImportJobs”createImportJobs(data, options?)
Create REST import jobs from staged files.
getImportJobProgress
Section titled “getImportJobProgress”getImportJobProgress(data, options?)
Get progress for a REST import job.
commitImportJob
Section titled “commitImportJob”commitImportJob(data, options?)
Commit an Uncommitted import job.
abortImportJob
Section titled “abortImportJob”abortImportJob(data, options?)
Abort an import job before it commits.
Import job example
Section titled “Import job example”const job = await client.createImportJobs({ collectionName: 'books', files: [['imports/books/part-0.parquet']],});
const progress = await client.getImportJobProgress({ jobId: job.data.jobId,});On Milvus 3.0.6, create a manual-commit job with options: { auto_commit: 'false' }. Poll getImportJobProgress() until the state is Uncommitted, then call commitImportJob({ jobId }) to make the imported rows visible. To discard a staged import, call abortImportJob({ jobId }) before committing. Poll the job again for its final state.
For Zilliz Cloud import workflows, include projectId and regionId when required by the cloud endpoint.
Collection Schema Changes
Section titled “Collection Schema Changes”These methods were verified on Milvus 3.0.6.
addCollectionStructField
Section titled “addCollectionStructField”Add a nullable StructArray field using schema.
dropCollectionField
Section titled “dropCollectionField”Remove a field by fieldName or fieldId.
addFunctionField
Section titled “addFunctionField”Add a function, its output field, and the bound index together.
dropFunctionField
Section titled “dropFunctionField”Remove a function together with its output field and index.
alterCollectionFunction
Section titled “alterCollectionFunction”Update supported settings for an existing function, such as a text embedding function’s description. Milvus 3.0.6 rejects BM25 function alterations.
truncateCollection
Section titled “truncateCollection”Remove all rows while keeping the schema and indexes.
External Collection Refresh
Section titled “External Collection Refresh”These methods were verified on Milvus 3.0.6.
refreshExternalCollection
Section titled “refreshExternalCollection”Submit a refresh for an external collection.
getRefreshExternalCollectionProgress
Section titled “getRefreshExternalCollectionProgress”Poll a refresh job. Pass the decimal job ID as returned by the SDK.
const { data: { jobId },} = await client.refreshExternalCollection({ collectionName: 'external_books',});const { data } = await client.getRefreshExternalCollectionProgress({ jobId });listRefreshExternalCollectionJobs
Section titled “listRefreshExternalCollectionJobs”List refresh jobs for a collection or database.
Snapshot APIs
Section titled “Snapshot APIs”The SDK preserves snapshot job IDs, pin IDs, and int64 metadata as decimal strings. These methods were verified on Milvus 3.0.6.
createSnapshot
Section titled “createSnapshot”Create a named snapshot of a collection.
listSnapshots
Section titled “listSnapshots”List snapshot names and summary metadata for a collection.
describeSnapshot
Section titled “describeSnapshot”Read a named snapshot’s metadata and storage location.
dropSnapshot
Section titled “dropSnapshot”Delete a named collection snapshot.
pinSnapshotData
Section titled “pinSnapshotData”Protect snapshot data for the requested lifetime and return a pin ID.
unpinSnapshotData
Section titled “unpinSnapshotData”Release protection using its pin ID.
restoreSnapshot
Section titled “restoreSnapshot”Restore into a new collection. Omitted source and target database names default to the configured database.
getRestoreSnapshotState
Section titled “getRestoreSnapshotState”Get restore progress by job ID.
listRestoreSnapshotJobs
Section titled “listRestoreSnapshotJobs”List restore jobs for a collection or database.
exportSnapshot
Section titled “exportSnapshot”Copy a snapshot to an object storage destination and return a job ID.
const { data: { jobId },} = await client.exportSnapshot({ collectionName: 'books', snapshotName: 'before_migration', targetS3Path: 'exports/books',});const { data } = await client.getExportSnapshotState({ jobId });getExportSnapshotState
Section titled “getExportSnapshotState”Check export progress and retrieve snapshotMetadataURI when complete.
restoreExternalSnapshot
Section titled “restoreExternalSnapshot”Restore a portable snapshot using the exported snapshotMetadataURI.
Resource Group APIs
Section titled “Resource Group APIs”These methods were verified on Milvus 3.0.6.
createResourceGroup
Section titled “createResourceGroup”Create a resource group with the requested node allocation.
describeResourceGroup
Section titled “describeResourceGroup”Read the top-level resource_group object. The SDK returns query node IDs as decimal strings.
listResourceGroups
Section titled “listResourceGroups”List resource group names.
dropResourceGroup
Section titled “dropResourceGroup”Drop a resource group.
updateResourceGroups
Section titled “updateResourceGroups”Pass { resource_groups } to update requests, limits, transfer preferences, and node labels.
transferReplica
Section titled “transferReplica”Transfer collection replicas in the default database with sourceRgName, targetRgName, collectionName, and replicaNum. The target group needs available query nodes.
User and Role APIs
Section titled “User and Role APIs”createUser
Section titled “createUser”createUser(data, options?)
Create a user.
updateUserPassword
Section titled “updateUserPassword”updateUserPassword(data, options?)
Update a user’s password.
dropUser
Section titled “dropUser”dropUser(data, options?)
Drop a user.
describeUser
Section titled “describeUser”describeUser(data, options?)
Describe user details.
listUsers
Section titled “listUsers”listUsers(options?)
List users.
grantRoleToUser
Section titled “grantRoleToUser”grantRoleToUser(data, options?)
Grant a role to a user.
revokeRoleFromUser
Section titled “revokeRoleFromUser”revokeRoleFromUser(data, options?)
Revoke a role from a user.
createRole
Section titled “createRole”createRole(data, options?)
Create a role.
alterRole
Section titled “alterRole”alterRole(data, options?)
Update the description of a role.
dropRole
Section titled “dropRole”dropRole(data, options?)
Drop a role.
describeRole
Section titled “describeRole”describeRole(data, options?)
Describe role privileges.
listRoles
Section titled “listRoles”listRoles(options?)
List roles.
grantPrivilegeToRole
Section titled “grantPrivilegeToRole”grantPrivilegeToRole(data, options?)
Grant a privilege to a role.
revokePrivilegeFromRole
Section titled “revokePrivilegeFromRole”revokePrivilegeFromRole(data, options?)
Revoke a privilege from a role.
Role privilege example
Section titled “Role privilege example”await client.grantPrivilegeToRole({ roleName: 'reader', objectType: 'Collection', objectName: 'books', privilege: 'Search',});grantPrivilegeV2
Section titled “grantPrivilegeV2”Grant a privilege or privilege group by roleName, dbName, collectionName, and privilege. Milvus requires authentication for v2 grants.
revokePrivilegeV2
Section titled “revokePrivilegeV2”Revoke a v2 grant using the same scope and privilege fields.
createPrivilegeGroup
Section titled “createPrivilegeGroup”Create a group by privilegeGroupName.
addPrivilegesToGroup
Section titled “addPrivilegesToGroup”Pass privilegeGroupName and a privileges array to add permissions.
removePrivilegesFromGroup
Section titled “removePrivilegesFromGroup”Pass privilegeGroupName and a privileges array to remove permissions.
listPrivilegeGroups
Section titled “listPrivilegeGroups”List privilege groups. The server returns each group’s privileges as a comma-separated string.
dropPrivilegeGroup
Section titled “dropPrivilegeGroup”Drop a group by privilegeGroupName.
Analyzer and File Resource APIs
Section titled “Analyzer and File Resource APIs”These methods were verified on Milvus 3.0.6.
runAnalyzer
Section titled “runAnalyzer”Use { text, analyzerParams } to preview tokens for strings, or pass collectionName and fieldName to reuse a field’s analyzer. Set withDetail for offsets and positions or withHash for token hashes.
addFileResource
Section titled “addFileResource”Register { name, path } for a file in the server’s storage.
listFileResources
Section titled “listFileResources”List file resource registrations. File resource IDs are returned as decimal strings.
removeFileResource
Section titled “removeFileResource”Remove a registration by name.
Diagnostics APIs
Section titled “Diagnostics APIs”These methods were verified on Milvus 3.0.6.
getSegmentsInfo
Section titled “getSegmentsInfo”Pass collectionID, segmentIDs, or both to inspect segment state, row counts, and binlog IDs. Use decimal strings for large IDs. The SDK returns IDs and row counts as decimal strings.
getQuotaMetrics
Section titled “getQuotaMetrics”Inspect quota center metrics. The response’s data contains JSON text.
Errors
Section titled “Errors”Non-2xx responses throw HttpError. For HTTP success responses, inspect the Milvus response envelope. A code of 0 indicates success.
try { await client.describeCollection({ collectionName: 'missing' });} catch (error) { if (error instanceof HttpError) { console.error(error.status, error.statusText, error.url); }}Milvus 3.0.6 returns a top-level resource_group object on successful describeResourceGroup() calls. Handle that response shape directly.