# Global Cluster

Connect the Milvus Node.js SDK to a multi-region deployment and configure topology discovery, routing, and failover.

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

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/

## Section links

- [Enabling Global Cluster Mode](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#enabling-global-cluster-mode)
- [Auto-Detection](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#auto-detection)
- [How It Works](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#how-it-works)
- [Manual Primary Reconnection](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#manual-primary-reconnection)
- [Cluster-pinned DQL Sessions](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#cluster-pinned-dql-sessions)
- [Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#configuration)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/advanced/global-cluster/#next-steps)

Global cluster mode enables multi-region Milvus deployments with automatic failover. The SDK fetches cluster topology from the endpoint and routes requests to the primary cluster.

## Enabling Global Cluster Mode

Set `isGlobal: true` in the client configuration:

```javascript
import { MilvusClient } from '@zilliz/milvus2-sdk-node';

const client = new MilvusClient({
  address: 'your-global-endpoint:19530',
  isGlobal: true,
  token: 'your-token',
});
```

### Auto-Detection

When `isGlobal` is not explicitly set, the SDK auto-detects global cluster mode by checking if the address URI contains `global-cluster`. You can override this by explicitly setting `isGlobal: true` or `isGlobal: false`.

## How It Works

When global cluster mode is enabled:

1. **Connection:** The SDK connects to the provided endpoint and queries the cluster topology
2. **Routing:** Requests are routed to the primary cluster automatically
3. **Failover:** If the primary cluster becomes unavailable, the SDK can reconnect to a new primary

## Manual Primary Reconnection

Use `reconnectToPrimary()` to manually trigger a reconnection to the current primary cluster:

```javascript
const changed = await client.reconnectToPrimary();

if (changed) {
  console.log('Reconnected to new primary cluster');
} else {
  console.log('Primary unchanged, no reconnection needed');
}
```

This method:

- Queries the endpoint for the current primary cluster
- If the primary has changed, creates a new connection pool for the new primary
- Drains the old connection pool gracefully
- Returns `true` if a reconnection occurred, `false` if the primary is unchanged

## Cluster-pinned DQL Sessions

Use `session(clusterId)` when you need search/query/get requests to target a specific cluster explicitly. The session reuses the parent client’s connection and only injects `cluster_id`; it does not create or close a separate connection pool.

```javascript
const session = client.session('cluster-a');

const results = await session.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  anns_field: 'vector',
  limit: 10,
});

session.close();
```

Supported session methods are `search()`, `hybridSearch()`, `searchIterator()`, `query()`, `queryIterator()`, `get()`, and `close()`.

## Configuration

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `isGlobal` | `boolean` | Auto-detected | Enable/disable global cluster mode |
| `address` | `string` | Required | Global cluster endpoint address |
| `token` | `string` | - | Authentication token |

## Next Steps

- Learn about [Client Configuration](https://milvus-io.github.io/milvus-sdk-node/core-concepts/client-configuration/) for all connection options
- Explore [Advanced Features](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/) for connection pooling and retries
