Skip to content
MilvusNode SDK
Sections

HttpClient

Markdown

Copy for agent

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.

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,
});

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 }
);

createCollection(data, options?)

Create a collection by dimension shortcut or explicit schema.

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.

Try the REST operation.

dropCollection(data, options?)

Drop a collection.

addCollectionField(data, options?)

Add a field to an existing collection.

alterCollectionProperties(data, options?)

Add or update collection properties.

alterCollectionFieldProperties(data, options?)

Alter field-level properties such as max_length, max_capacity, or mmap_enabled.

dropCollectionProperties(data, options?)

Remove collection properties by key.

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.

Try the REST operation.

hasCollection(data, options?)

Check whether a collection exists.

renameCollection(data, options?)

Rename a collection, optionally into another database.

getCollectionStatistics(data, options?)

Get collection statistics such as row count.

flushCollection(data, options?)

Flush a collection.

loadCollection(data, options?)

Load a collection into memory.

releaseCollection(data, options?)

Release a loaded collection.

getCollectionLoadState(data, options?)

Get load progress and load state.

compactCollection(data, options?)

Start collection compaction.

getCompactionState(data, options?)

Get compaction progress by compaction ID.

refreshLoad(data, options?)

Refresh an existing loaded collection.

await client.flushCollection({ collectionName: 'books' });
const loadState = await client.getCollectionLoadState({
collectionName: 'books',
});
const compaction = await client.compactCollection({
collectionName: 'books',
});

insert(data, options?)

Insert rows.

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.

Try the REST operation.

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.

Try the REST operation.

hybridSearch(data, options?)

Hybrid search over multiple vector requests with reranking.

delete(data, options?)

Delete rows by filter.

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.

createDatabase(data, options?)

Create a database.

dropDatabase(data, options?)

Drop a database.

describeDatabase(data, options?)

Describe database metadata and properties.

listDatabases(options?)

List databases.

alterDatabaseProperties(data, options?)

Add or update database properties.

dropDatabaseProperties(data, options?)

Remove database properties by key.

createIndex(data, options?)

Create one or more indexes.

dropIndex(data, options?)

Drop an index.

describeIndex(data, options?)

Describe indexes.

listIndexes(data, options?)

List index names.

alterIndexProperties(data, options?)

Add or update index properties.

dropIndexProperties(data, options?)

Remove index properties by key.

listPartitions(data, options?)

List partitions.

createPartition(data, options?)

Create a partition.

dropPartition(data, options?)

Drop a partition.

loadPartitions(data, options?)

Load partitions.

releasePartitions(data, options?)

Release partitions.

hasPartition(data, options?)

Check whether a partition exists.

getPartitionStatistics(data, options?)

Get partition statistics such as row count.

listAliases(data, options?)

List aliases in a database or collection.

createAlias(data, options?)

Create an alias for a collection.

describeAlias(data, options?)

Describe an alias.

alterAlias(data, options?)

Move an alias to another collection.

dropAlias(data, options?)

Drop an alias.

HTTP import APIs are separate from the gRPC bulkInsert, getImportState, and listImportTasks APIs.

listImportJobs(data, options?)

List REST import jobs for a collection.

createImportJobs(data, options?)

Create REST import jobs from staged files.

getImportJobProgress(data, options?)

Get progress for a REST import job.

commitImportJob(data, options?)

Commit an Uncommitted import job.

abortImportJob(data, options?)

Abort an import job before it commits.

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.

These methods were verified on Milvus 3.0.6.

Add a nullable StructArray field using schema.

Remove a field by fieldName or fieldId.

Add a function, its output field, and the bound index together.

Remove a function together with its output field and index.

Update supported settings for an existing function, such as a text embedding function’s description. Milvus 3.0.6 rejects BM25 function alterations.

Remove all rows while keeping the schema and indexes.

These methods were verified on Milvus 3.0.6.

Submit a refresh for an external collection.

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 });

List refresh jobs for a collection or database.

The SDK preserves snapshot job IDs, pin IDs, and int64 metadata as decimal strings. These methods were verified on Milvus 3.0.6.

Create a named snapshot of a collection.

List snapshot names and summary metadata for a collection.

Read a named snapshot’s metadata and storage location.

Delete a named collection snapshot.

Protect snapshot data for the requested lifetime and return a pin ID.

Release protection using its pin ID.

Restore into a new collection. Omitted source and target database names default to the configured database.

Get restore progress by job ID.

List restore jobs for a collection or database.

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 });

Check export progress and retrieve snapshotMetadataURI when complete.

Restore a portable snapshot using the exported snapshotMetadataURI.

These methods were verified on Milvus 3.0.6.

Create a resource group with the requested node allocation.

Read the top-level resource_group object. The SDK returns query node IDs as decimal strings.

List resource group names.

Drop a resource group.

Pass { resource_groups } to update requests, limits, transfer preferences, and node labels.

Transfer collection replicas in the default database with sourceRgName, targetRgName, collectionName, and replicaNum. The target group needs available query nodes.

createUser(data, options?)

Create a user.

updateUserPassword(data, options?)

Update a user’s password.

dropUser(data, options?)

Drop a user.

describeUser(data, options?)

Describe user details.

listUsers(options?)

List users.

grantRoleToUser(data, options?)

Grant a role to a user.

revokeRoleFromUser(data, options?)

Revoke a role from a user.

createRole(data, options?)

Create a role.

alterRole(data, options?)

Update the description of a role.

dropRole(data, options?)

Drop a role.

describeRole(data, options?)

Describe role privileges.

listRoles(options?)

List roles.

grantPrivilegeToRole(data, options?)

Grant a privilege to a role.

revokePrivilegeFromRole(data, options?)

Revoke a privilege from a role.

await client.grantPrivilegeToRole({
roleName: 'reader',
objectType: 'Collection',
objectName: 'books',
privilege: 'Search',
});

Grant a privilege or privilege group by roleName, dbName, collectionName, and privilege. Milvus requires authentication for v2 grants.

Revoke a v2 grant using the same scope and privilege fields.

Create a group by privilegeGroupName.

Pass privilegeGroupName and a privileges array to add permissions.

Pass privilegeGroupName and a privileges array to remove permissions.

List privilege groups. The server returns each group’s privileges as a comma-separated string.

Drop a group by privilegeGroupName.

These methods were verified on Milvus 3.0.6.

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.

Register { name, path } for a file in the server’s storage.

List file resource registrations. File resource IDs are returned as decimal strings.

Remove a registration by name.

These methods were verified on Milvus 3.0.6.

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.

Inspect quota center metrics. The response’s data contains JSON text.

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.