# Configure the Milvus Client

Configure the Milvus Node.js client with an address, credentials, TLS, timeouts, retries, and connection pooling.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/

## Section links

- [Basic Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#basic-configuration)
- [Configuration Options](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#configuration-options)
- [Address and Endpoints](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#address-and-endpoints)
- [Authentication](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#authentication)
- [Username and Password](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#username-and-password)
- [Token (for Zilliz Cloud)](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#token-for-zilliz-cloud)
- [SSL/TLS Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#ssltls-configuration)
- [Timeout Settings](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#timeout-settings)
- [Retry Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#retry-configuration)
- [Database Selection](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#database-selection)
- [Logging Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#logging-configuration)
- [Connection Pooling](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#connection-pooling)
- [gRPC Channel Options](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#grpc-channel-options)
- [Connect Reserved Options](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#connect-reserved-options)
- [Environment-Specific Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#environment-specific-configuration)
- [Development](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#development)
- [Production](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#production)
- [Zilliz Cloud Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#zilliz-cloud-configuration)
- [Complete Configuration Example](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#complete-configuration-example)
- [Configuration Interface](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#configuration-interface)
- [Request Tracing](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#request-tracing)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#next-steps)
- [Client telemetry (SDK 3.0.5)](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/#client-telemetry-sdk-305)

Create a gRPC `MilvusClient` with your cluster’s `address` and credentials if authentication is enabled. Use a [REST endpoint](https://milvus-io.github.io/milvus-sdk-node/api-reference/http-client/#constructor) 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. |

## Basic Configuration

The simplest configuration requires only the Milvus server address:

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

## Configuration Options

### Address and Endpoints

```javascript
const client = new MilvusClient({
  address: 'localhost:19530', // Required: Milvus server address
});
```

### Authentication

#### Username and Password

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  username: 'root',
  password: 'Milvus',
});
```

#### Token (for Zilliz Cloud)

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

### SSL/TLS Configuration

Enable SSL/TLS encryption:

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

Full TLS options:

```javascript
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: {},
  },
});
```

### Timeout Settings

Configure request timeouts:

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

### Retry Configuration

Configure retry behavior:

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

### Database Selection

Specify which database to use:

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

### Logging Configuration

Configure logging levels:

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

### Connection Pooling

Configure connection pool options:

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

### gRPC Channel Options

Advanced gRPC channel configuration:

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

### Connect Reserved Options

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.

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

`option` values must be strings.

## Environment-Specific Configuration

### Development

```javascript
const client = new MilvusClient({
  address: process.env.MILVUS_ADDRESS || 'localhost:19530',
  logLevel: 'debug',
});
```

### Production

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

## Zilliz Cloud Configuration

For Zilliz Cloud, use the endpoint and API key:

```javascript
const client = new MilvusClient({
  address: 'https://your-endpoint.zillizcloud.com:443',
  token: 'your-api-key',
  ssl: true,
});
```

## Complete Configuration Example

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

## Configuration Interface

The `ClientConfig` interface includes:

```typescript
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;
}
```

## Request Tracing

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

```javascript
// 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](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#request-tracing-traceid) in Advanced Features.

## Next Steps

- Learn about [Data Types & Schemas](https://milvus-io.github.io/milvus-sdk-node/core-concepts/data-types-schemas/)
- Explore [Collection Management](https://milvus-io.github.io/milvus-sdk-node/management/collection-management/)
- Check out [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/) for production configurations

## Client telemetry (SDK 3.0.5)

`telemetry` configures heartbeat reporting and is enabled by default. See [Client Telemetry](https://milvus-io.github.io/milvus-sdk-node/advanced/client-telemetry/) for defaults, collected information, disabling, and `getTelemetry()` inspection. `TelemetryConfig` is exported from the package root.
