Skip to content
MilvusNode SDK
Sections

Configure the Milvus Client

Markdown

Copy for agent

Create a gRPC MilvusClient with your cluster’s address and credentials if authentication is enabled. Use a REST endpoint when configuring HttpClient.

Option What it controls
address Required Milvus gRPC address, for example localhost:19530 or your Zilliz Cloud endpoint.
token Zilliz Cloud API key or a username:password token.
username / password Separate credentials for an authenticated deployment.
database Database to use after connecting. Defaults to default.
ssl / tls Enable TLS and configure certificates or server identity.
timeout Request timeout in milliseconds.
pool gRPC connection pool settings, such as minimum and maximum sizes.
maxRetries Maximum retry count for retryable gRPC failures. Defaults to 3.
telemetry Client metrics, heartbeats, and server commands. Enabled by default.

The simplest configuration requires only the Milvus server address:

const client = new MilvusClient({
address: 'localhost:19530',
});
const client = new MilvusClient({
address: 'localhost:19530', // Required: Milvus server address
});
const client = new MilvusClient({
address: 'localhost:19530',
username: 'root',
password: 'Milvus',
});
const client = new MilvusClient({
address: 'https://your-endpoint.zillizcloud.com:443',
token: 'your-api-key', // Can be 'username:password' or API key
});

Enable SSL/TLS encryption:

const client = new MilvusClient({
address: 'localhost:19530',
ssl: true,
tls: {
rootCertPath: '/path/to/ca.pem',
serverName: 'milvus.example.com',
},
});

Full TLS options:

const client = new MilvusClient({
address: 'localhost:19530',
ssl: true,
tls: {
// Certificate Authority PEM file path
rootCertPath: '/path/to/ca.pem',
// Or certificate buffer
rootCert: Buffer.from('...'),
// Private key path (for client authentication)
privateKeyPath: '/path/to/key.pem',
// Or private key buffer
privateKey: Buffer.from('...'),
// Certificate chain path
certChainPath: '/path/to/cert.pem',
// Or certificate buffer
certChain: Buffer.from('...'),
// Server name for SNI
serverName: 'milvus.example.com',
// Skip certificate verification (not recommended for production)
skipCertCheck: false,
// Additional verify options
verifyOptions: {},
},
});

Configure request timeouts:

const client = new MilvusClient({
address: 'localhost:19530',
timeout: 30000, // 30 seconds in milliseconds
});

Configure retry behavior:

const client = new MilvusClient({
address: 'localhost:19530',
maxRetries: 3, // Maximum number of retries
retryDelay: 1000, // Delay between retries in milliseconds
});

Specify which database to use:

const client = new MilvusClient({
address: 'localhost:19530',
database: 'my_database',
});

Configure logging levels:

const client = new MilvusClient({
address: 'localhost:19530',
logLevel: 'debug', // 'error', 'warn', 'info', 'debug'
logPrefix: 'milvus-client', // Prefix for log messages
});

Configure connection pool options:

const client = new MilvusClient({
address: 'localhost:19530',
pool: {
min: 2, // Minimum pool size
max: 10, // Maximum pool size
idleTimeoutMillis: 30000, // Idle timeout
},
});

Advanced gRPC channel configuration:

const client = new MilvusClient({
address: 'localhost:19530',
channelOptions: {
'grpc.keepalive_time_ms': 30000,
'grpc.keepalive_timeout_ms': 5000,
'grpc.keepalive_permit_without_calls': 1,
'grpc.http2.max_pings_without_data': 0,
'grpc.http2.min_time_between_pings_ms': 10000,
'grpc.http2.min_ping_interval_without_data_ms': 300000,
},
});

Use option to pass reserved key-value metadata in the initial Milvus Connect request. These values are sent as client_info.reserved and are useful for deployment-specific routing, attribution, or internal integrations.

const client = new MilvusClient({
address: 'localhost:19530',
option: {
app: 'recommendation-service',
environment: 'production',
},
});

option values must be strings.

const client = new MilvusClient({
address: process.env.MILVUS_ADDRESS || 'localhost:19530',
logLevel: 'debug',
});
const client = new MilvusClient({
address: process.env.MILVUS_ADDRESS,
username: process.env.MILVUS_USERNAME,
password: process.env.MILVUS_PASSWORD,
ssl: true,
tls: {
rootCertPath: process.env.MILVUS_CA_CERT,
},
timeout: 60000,
maxRetries: 5,
logLevel: 'warn',
});

For Zilliz Cloud, use the endpoint and API key:

const client = new MilvusClient({
address: 'https://your-endpoint.zillizcloud.com:443',
token: 'your-api-key',
ssl: true,
});
const client = new MilvusClient({
// Required
address: 'localhost:19530',
// Authentication (choose one)
username: 'root',
password: 'Milvus',
// OR
token: 'api-key',
// SSL/TLS
ssl: true,
tls: {
rootCertPath: '/path/to/ca.pem',
serverName: 'milvus.example.com',
},
// Timeouts and retries
timeout: 30000,
maxRetries: 3,
retryDelay: 1000,
// Database
database: 'default',
// Logging
logLevel: 'info',
logPrefix: 'milvus',
// Connection pooling
pool: {
min: 2,
max: 10,
},
});

The ClientConfig interface includes:

interface ClientConfig {
address: string; // Required
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;
}

All API requests support optional trace IDs for tracking and debugging:

// Add trace ID to any request
await client.listCollections({
client_request_id: 'trace-id-123', // Optional trace ID
});
// Alternative format (compatible with pymilvus)
await client.listCollections({
'client-request-id': 'trace-id-123',
});

Features:

  • Automatic timestamp: Every request includes client-request-unixmsec
  • Trace ID support: Add client_request_id or client-request-id to track requests
  • Global support: All API methods automatically support trace IDs
  • Priority: client_request_id takes priority over client-request-id (JavaScript convention)

For more details, see Request Tracing in Advanced Features.

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.