Skip to content
MilvusNode SDK
Sections

MilvusClient

Markdown

Copy for agent

MilvusClient is the main gRPC client for Milvus. It owns connection metadata, authentication, retry behavior, database context, and all high-level APIs exposed by the SDK.

new MilvusClient(
config: ClientConfig | string,
ssl?: boolean,
username?: string,
password?: string,
channelOptions?: ChannelOptions
)

You can construct the client with either a configuration object or the legacy positional arguments.

const client = new MilvusClient({
address: 'localhost:19530',
ssl: false,
username: 'root',
password: 'Milvus',
database: 'default',
timeout: 30_000,
maxRetries: 3,
retryDelay: 200,
});
await client.connectPromise;
const client = new MilvusClient('localhost:19530', false, 'root', 'Milvus');
interface ClientConfig {
address: string;
token?: string;
ssl?: boolean;
username?: string;
password?: string;
channelOptions?: ChannelOptions;
option?: Record<string, string>;
timeout?: number | string;
maxRetries?: number;
retryDelay?: number;
database?: string;
logLevel?: string;
logPrefix?: string;
tls?: {
rootCertPath?: string;
rootCert?: Buffer;
privateKeyPath?: string;
privateKey?: Buffer;
certChainPath?: string;
certChain?: Buffer;
verifyOptions?: Record<string, any>;
serverName?: string;
skipCertCheck?: boolean;
};
pool?: Options;
loaderOptions?: LoaderOption;
telemetry?: TelemetryConfig;
trace?: boolean;
isGlobal?: boolean;
}

Important fields:

  • address: Milvus gRPC address, for example localhost:19530.
  • token: Auth token. Accepts username:password or a Zilliz Cloud API key.
  • username / password: Alternative auth fields when token is not provided.
  • ssl: Enables TLS when true.
  • tls: Certificate and verification options for TLS connections.
  • database: Initial database context. Defaults to default.
  • timeout: Default request timeout in milliseconds.
  • maxRetries / retryDelay: gRPC retry behavior.
  • pool: generic-pool options for the gRPC channel pool.
  • loaderOptions: protobuf loader options. longs: String is the default to avoid int64 precision loss.
  • trace: Enables request tracing metadata.
  • isGlobal: Explicitly enables or disables global-cluster routing.

Return SDK version and the recommended Milvus version encoded at build time.

MilvusClient.sdkInfo;
// { version: string, recommendMilvus: string }

Example:

console.log('SDK version:', MilvusClient.sdkInfo.version);
console.log('Recommended Milvus:', MilvusClient.sdkInfo.recommendMilvus);

MilvusClient starts connecting during construction unless __SKIP_CONNECT__ is set. Await connectPromise before the first operation when you want explicit connection readiness.

const client = new MilvusClient({ address: 'localhost:19530' });
await client.connectPromise;

Set the active database for subsequent gRPC requests.

use(data?: { db_name: string }): Promise<ResStatus>
useDatabase(data?: { db_name: string }): Promise<ResStatus> // alias

Example:

await client.use({ db_name: 'analytics' });
await client.showCollections();

Calling use() with no database resets the context to default.

Drain and clear the gRPC connection pool.

closeConnection(): Promise<CONNECT_STATUS>

Example:

await client.closeConnection();

For global-cluster connections, refresh topology and reconnect to a new primary cluster if failover occurred.

reconnectToPrimary(): Promise<boolean>

Returns true when the primary endpoint changed and reconnection was performed.

Create a lightweight DQL session pinned to a target cluster id.

session(clusterId: string): MilvusClientSession

The session reuses the parent client’s connection and injects cluster_id into supported requests. Closing the session prevents future session calls, but it does not close the parent MilvusClient or the gRPC channel pool.

Supported session methods:

Method Description
search(params) Search with the session cluster id.
hybridSearch(params) Hybrid search with the session cluster id.
searchIterator(params) Create a search iterator with the session cluster id.
query(params) Query with the session cluster id.
queryIterator(params) Create a query iterator with the session cluster id.
get(params) Get rows by primary key with the session cluster id.
close() Close only this session wrapper.

Example:

const session = client.session('cluster-a');
const results = await session.search({
collection_name: 'books',
data: [[0.1, 0.2, 0.3, 0.4]],
anns_field: 'vector',
limit: 10,
});
session.close();

MilvusClient#createCollection extends the lower-level collection API with a quick-create form that aligns with the Python SDK.

createCollection(
data: CreateColReq | CreateColWithSchemaAndIndexParamsReq | CreateCollectionReq
): Promise<ResStatus>

Quick-create example:

await client.createCollection({
collection_name: 'quick_start',
dimension: 768,
metric_type: 'COSINE',
primary_field_name: 'id',
vector_field_name: 'embedding',
auto_id: false,
});

Schema + index example:

await client.createCollection({
collection_name: 'books',
fields: [
{ name: 'id', data_type: DataType.Int64, is_primary_key: true },
{ name: 'embedding', data_type: DataType.FloatVector, dim: 768 },
],
index_params: {
field_name: 'embedding',
index_type: 'AUTOINDEX',
metric_type: 'COSINE',
},
});
const client = new MilvusClient({
address: 'localhost:19530',
username: 'root',
password: 'Milvus',
});
const client = new MilvusClient({
address: 'your-cluster-endpoint:19530',
ssl: true,
token: process.env.ZILLIZ_CLOUD_API_KEY,
});

telemetry configures heartbeat reporting and is enabled by default. See Client Telemetry for defaults, collected information, disabling, and getTelemetry() inspection. TelemetryConfig is exported from the package root.