Connect to Global Cluster

After your global cluster is running, connect to it using an endpoint and an authentication token. This page covers the two endpoint types, when to use each, and how routing behaves during switchover and failover.

📘Notes

This feature is available only to Dedicated clusters in a Business Critical project.

Choose an endpoint type

A global cluster provides two ways to connect:

• Via a global endpoint

• Via the public or private endpoints of the primary or secondary cluster in a global cluster

The following table compares the two connection endpoints.

	Global endpoint	The endpoint of a primary or secondary cluster
Write routing	Automatically routed to the primary cluster	Only the primary's public endpoint accepts writes
Read routing	Routed to the primary cluster (Intelligent routing to the nearest available cluster based on latency will be supported soon.)	Reads go to the specific cluster you connect to
Switchover / Failover	Re-routes automatically — no code changes	You must update your connection to point to the new primary
Private Link	Not supported (requires public internet)	Supported.
Best for	Production applications that need automatic failover and latency-based routing	Direct access to a specific cluster (e.g., environment replication, testing, debugging)

📘Notes

It is recommended to use the global endpoint for production workloads. It eliminates the need to handle endpoint changes in your application code during switchover or failover.

Get your endpoint and token

1

Navigate to your global cluster or target cluster:

• For the global endpoint: Go to the Global Cluster page.

• For a public endpoint: Go to the Cluster Details page of the specific primary or secondary cluster.

2

On the Connect card, copy the Global Endpoint or Public Endpoint.

3

Prepare your authentication token. This can be either an API key or a cluster credential (username:password).

Check SDK version

Ensure you have installed SDKs. Before connecting to a global cluster, ensure your SDK meets the minimum version requirement.

SDK	Minimum Version
Python	2.6.9
Node.js	2.6.10
Java	2.6.14
Go	2.6.2

Connect using the global endpoint

The global endpoint is a single URL that routes requests to the appropriate cluster in the global cluster. Use it as the uri in your SDK client.

Python

from pymilvus import MilvusClient

# Use the global endpoint for automatic routing
client = MilvusClient(
    uri="YOUR_GLOBAL_ENDPOINT",  # Global endpoint from the console
    token="YOUR_CLUSTER_TOKEN"   # API key or username:password
)

Java

import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.client.ConnectConfig;

// Use the global endpoint for automatic routing
ConnectConfig connectConfig = ConnectConfig.builder()
    .uri("YOUR_GLOBAL_ENDPOINT")  // Global endpoint from the console
    .token("YOUR_CLUSTER_TOKEN")  // API key or username:password
    .build();

MilvusClientV2 client = new MilvusClientV2(connectConfig);

NodeJS

const { MilvusClient } = require("@zilliz/milvus2-sdk-node")

// Use the global endpoint for automatic routing
const client = new MilvusClient({
    address: "YOUR_GLOBAL_ENDPOINT",  // Global endpoint from the console
    token: "YOUR_CLUSTER_TOKEN"       // API key or username:password
})

Go

import "github.com/milvus-io/milvus/client/v2/milvusclient"

// Use the global endpoint for automatic routing
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_GLOBAL_ENDPOINT", // Global endpoint from the console
    APIKey:  "YOUR_CLUSTER_TOKEN", // API key or username:password
})

cURL

curl --request POST \
  --url "YOUR_GLOBAL_ENDPOINT" \
  --header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"dbName": "default"}'

Connect using a public endpoint

Each cluster in the global cluster has its own public endpoint. Use this when you need to target a specific cluster directly.

Python

from pymilvus import MilvusClient

# Connect directly to a specific cluster
client = MilvusClient(
    uri="YOUR_CLUSTER_PUBLIC_ENDPOINT",  # Public endpoint of a specific cluster
    token="YOUR_CLUSTER_TOKEN" # API key or username:password
)

Java

import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.client.ConnectConfig;

// Connect directly to a specific cluster
ConnectConfig connectConfig = ConnectConfig.builder()
    .uri("YOUR_CLUSTER_PUBLIC_ENDPOINT")  // Public endpoint of a specific cluster
    .token("YOUR_CLUSTER_TOKEN")  // API key or username:password
    .build();

MilvusClientV2 client = new MilvusClientV2(connectConfig);

NodeJS

const { MilvusClient } = require("@zilliz/milvus2-sdk-node")

// Connect directly to a specific cluster
const client = new MilvusClient({
    address: "YOUR_CLUSTER_PUBLIC_ENDPOINT",  // Public endpoint of a specific cluster
    token: "YOUR_CLUSTER_TOKEN"  // API key or username:password
})

Go

import "github.com/milvus-io/milvus/client/v2/milvusclient"

// Connect directly to a specific cluster
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_PUBLIC_ENDPOINT",  // Public endpoint of a specific cluster
    APIKey:  "YOUR_CLUSTER_TOKEN",  // API key or username:password
})

cURL

curl --request POST \
  --url "YOUR_CLUSTER_PUBLIC_ENDPOINT" \
  --header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"dbName": "default"}'

📘Notes

When using public endpoints, only the primary cluster's public endpoint accepts write operations. Writing to a secondary cluster's public endpoint will fail.

Routing behavior

During normal operation

Request type	Global endpoint	Public endpoint
Write (insert, upsert, delete)	Routed to the primary cluster	Only accepted on the primary cluster's endpoint
Read (search, query)	Routed to the primary cluster (Intelligent routing to the nearest available cluster based on latency will be supported soon.)	Served by the specific cluster you connect to

During and after switchover / failover

Scenario	Global endpoint	Public endpoint
Switchover in progress	Writes briefly paused, then resume on the new primary. Reads continue.	No change to endpoints. Old primary becomes secondary.
Failover in progress	Writes unavailable until new primary is promoted. Reads continue on secondaries.	Old primary's endpoint becomes unreachable.
After completion	Automatically routes to the new primary. No code changes.	Update your code to use the new primary's public endpoint for writes.

SDK automatic reconnection

When using the global endpoint, the Zilliz Cloud SDKs handle endpoint re-routing during switchover and failover. Your application does not need to implement retry logic for the routing change itself. However, writes that are in-flight at the moment of the switch may receive a transient error — standard retry logic in your application will handle these cases.