# MilvusClient

Look up the MilvusClient constructor, authentication, connection options, database context, and client methods for gRPC in Node.js.

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

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/api-reference/client/

## Section links

- [Constructor](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#constructor)
- [Configuration object](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#configuration-object)
- [Legacy positional form](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#legacy-positional-form)
- [ClientConfig](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#clientconfig)
- [Static properties](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#static-properties)
- [sdkInfo](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#sdkinfo)
- [Connection lifecycle](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#connection-lifecycle)
- [connectPromise](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#connectpromise)
- [use](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#use)
- [closeConnection](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#closeconnection)
- [reconnectToPrimary](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#reconnecttoprimary)
- [session](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#session)
- [High-level createCollection overload](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#high-level-createcollection-overload)
- [Auth examples](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#auth-examples)
- [Local Milvus username/password](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#local-milvus-usernamepassword)
- [Zilliz Cloud token](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#zilliz-cloud-token)
- [Related](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#related)
- [Client telemetry (SDK 3.0.5)](https://milvus-io.github.io/milvus-sdk-node/api-reference/client/#client-telemetry-sdk-305)

`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.

## Constructor

```typescript
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.

### Configuration object

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

### Legacy positional form

```typescript
const client = new MilvusClient('localhost:19530', false, 'root', 'Milvus');
```

## ClientConfig

```typescript
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.

## Static properties

### sdkInfo

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

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

Example:

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

## Connection lifecycle

### connectPromise

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

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

### use

Set the active database for subsequent gRPC requests.

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

Example:

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

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

### closeConnection

Drain and clear the gRPC connection pool.

```typescript
closeConnection(): Promise<CONNECT_STATUS>
```

Example:

```typescript
await client.closeConnection();
```

### reconnectToPrimary

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

```typescript
reconnectToPrimary(): Promise<boolean>
```

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

### session

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

```typescript
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:

```typescript
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();
```

## High-level createCollection overload

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

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

Quick-create example:

```typescript
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:

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

## Auth examples

### Local Milvus username/password

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

### Zilliz Cloud token

```typescript
const client = new MilvusClient({
  address: 'your-cluster-endpoint:19530',
  ssl: true,
  token: process.env.ZILLIZ_CLOUD_API_KEY,
});
```

## Related

- [API Reference overview](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- [Collection Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/collections/)
- [Client Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/)

## 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.
