グローバルクラスターへの接続
この機能は、Business Critical(SaaS)および BYOC デプロイメントでのみ使用できます。
この機能は、サポートされているすべての AWS リージョンで使用できます。Google Cloud の us-central1 および us-east4 リージョンでも、リクエストに応じて使用できます。この機能は Microsoft Azure では使用できません。
グローバルクラスターが稼働したら、エンドポイントと認証トークンを使用して接続します。このページでは、2 種類のエンドポイント、それぞれの使い分け、およびスイッチオーバーとフェイルオーバー中のルーティング動作について説明します。
エンドポイントの種類を選択する
グローバルクラスターでは、次の 2 つの方法で接続できます。
-
グローバルエンドポイント経由
-
グローバルクラスター内のプライマリクラスターまたはセカンダリクラスターのパブリックエンドポイントまたはプライベートエンドポイント経由
次の表では、2 つの接続エンドポイントを比較しています。
| グローバルエンドポイント | プライマリクラスターまたはセカンダリクラスターのエンドポイント | |
|---|---|---|
| 書き込みルーティング | プライマリクラスターに自動的にルーティングされます | プライマリのパブリックエンドポイントのみが書き込みを受け付けます |
| 読み取りルーティング | プライマリクラスターにルーティングされます (レイテンシーに基づき、使用可能な最も近いクラスターへのインテリジェントルーティングが近日中にサポートされる予定です。) | 読み取りは、接続先の特定のクラスターに送られます |
| スイッチオーバー / フェイルオーバー | 自動的に再ルーティングされます。コードの変更は必要ありません | 新しいプライマリを指すように接続を更新する必要があります |
| Private Link | サポートされません(パブリックインターネットが必要です) | サポートされています。 |
| 最適な用途 | 自動フェイルオーバーとレイテンシーベースのルーティングが必要な本番アプリケーション | 特定のクラスターへの直接アクセス(環境のレプリケーション、テスト、デバッグなど) |
本番ワークロードには、グローバルエンドポイントの使用を推奨します。これにより、スイッチオーバーまたはフェイルオーバー中にアプリケーションコードでエンドポイントの変更を処理する必要がなくなります。
エンドポイントとトークンを取得する
グローバルクラスターまたはターゲットクラスターに移動します。
-
For the global endpoint: Go to the Global Cluster page.
-
パブリックエンドポイントの場合: 特定のプライマリクラスターまたはセカンダリクラスターの Cluster Details ページに移動します。
Connect カードで、Global Endpoint または Public Endpoint をコピーします。

グローバルエンドポイントを使用して接続する
グローバルエンドポイントは、グローバルクラスター内の現在のプライマリクラスターに常にリクエストをルーティングする単一の URL です。
スイッチオーバーまたはフェイルオーバーが発生すると、Zilliz Cloud はグローバルエンドポイントを自動的に更新して新しいプライマリクラスターを指すようにします。これにより、アプリケーションはクラスター URI を手動で変更することなく、同じエンドポイントを引き続き使用できます。
Zilliz Cloud では、SDK と RESTful API の両方を使用してグローバルエンドポイントに接続できます。本番アプリケーションには、SDK クライアントの使用を推奨します。
RESTful API 接続よりも SDK 接続が推奨されるのはなぜですか?
SDK クライアントは、エンドポイント一覧、プライマリおよびセカンダリのロール、クラスターのヘルスを含むグローバルクラスタートポロジーを取得できます。この情報により、SDK クライアントはプライマリクラスターが変更されたときに迅速に対応できます。SDK クライアントは将来、read/write 分割もサポートする予定です。この機能では、書き込みリクエストはプライマリクラスターにルーティングされ、条件を満たす読み取りリクエストはグローバルクラスタートポロジーに基づいてルーティングされます。
ただし、RESTful API 接続はグローバルクラスタートポロジー情報を保持しません。そのため、スイッチオーバーまたはフェイルオーバー後に新しいプライマリクラスターへの切り替えに時間がかかる場合があります。同じ理由で、RESTful API 接続は read/write 分割をサポートできません。
次の表では、SDK 接続と RESTful API 接続を比較しています。
| 項目 | SDK 接続 | RESTful API 接続 |
|---|---|---|
| 最適な用途 | ロール変更時の迅速な復旧と将来の read/write 分割を必要とする本番アプリケーション。 | 軽量なスクリプト、シンプルな REST 統合、単発の管理操作。 |
| トポロジーの認識 | エンドポイント一覧、プライマリおよびセカンダリのロール、クラスターのヘルスを含むグローバルクラスタートポロジーを取得します。 | グローバルクラスタートポロジー情報を保持しません。 |
| プライマリ変更時の処理 | スイッチオーバーまたはフェイルオーバー後にプライマリクラスターが変更された場合、通常は数秒以内により迅速に対応できます。 | クライアントがトポロジー情報を保持しないため、新しいプライマリへの切り替えに通常は数分かかる場合があります。 |
| read/write 分割 | 近日中にサポートされる予定です。 | サポートされていません |
SDK バージョンを確認する
開始する前に、SDK をインストール済みであること、および SDK が最小バージョン要件を満たしていることを確認してください。
| SDK | 最小バージョン |
|---|---|
| Python | 2.6.9 |
| Java | 2.6.14 |
接続ガイド
- Python
- Java
- Go
- Rust
- C++
- NodeJS
- CSharp
- cURL
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
)
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);
import (
"context"
"log"
"github.com/milvus-io/milvus/client/v3/milvusclient"
)
// Use the global endpoint for automatic routing
client, err := milvusclient.New(context.Background(), &milvusclient.ClientConfig{
Address: "YOUR_GLOBAL_ENDPOINT", // Global endpoint from the console
APIKey: "YOUR_CLUSTER_TOKEN", // API key or username:password
})
if err != nil {
log.Fatal(err)
}
use milvus::v2::error::Result;
use milvus::v2::prelude::*;
// Use the global endpoint for automatic routing
let config = ConnectConfig::new().uri("YOUR_GLOBAL_ENDPOINT").token("YOUR_CLUSTER_TOKEN");
let client = ClientV2::new(&config).await?;
#include "milvus/MilvusClientV2.h"
#include <iostream>
// Use the global endpoint for automatic routing
auto client = milvus::MilvusClientV2::Create();
auto status = client->Connect(milvus::ConnectParam("YOUR_GLOBAL_ENDPOINT").WithToken("YOUR_CLUSTER_TOKEN"));
if (!status.IsOk()) {
std::cout << status.Message() << std::endl;
}
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
});
using Milvus.Client.V2;
using Milvus.Client.V2.Requests.Collection;
using Milvus.Client.V2.Requests.Dml;
using Milvus.Client.V2.Requests.Dql;
using Milvus.Client.V2.Requests.Index;
using Milvus.Client.V2.Types;
// Use the global endpoint for automatic routing
var client = new MilvusClientV2(new ConnectConfig
{
Uri = "YOUR_GLOBAL_ENDPOINT", // Global endpoint from the console
Username = "YOUR_CLUSTER_TOKEN" // API key or username:password
});
curl --request POST \
--url "YOUR_GLOBAL_ENDPOINT/v2/vectordb/collections/list" \
--header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
--header "Content-Type: application/json" \
-d '{}'
パブリックエンドポイントを使用して接続する
グローバルクラスター内の各クラスターには、それぞれ独自のパブリックエンドポイントがあります。特定のクラスターを直接対象とする場合に使用します。
- Python
- Java
- Go
- Rust
- C++
- NodeJS
- CSharp
- cURL
# Connect directly to a specific cluster
// Connect directly to a specific cluster
// Connect directly to a specific cluster
, &milvusclient.ClientConfig{
Address: "YOUR_CLUSTER_PUBLIC_ENDPOINT", // Public endpoint of a specific cluster
APIKey: "YOUR_CLUSTER_TOKEN", // API key or username:password
})
if err != nil {
log.Fatal(err)
}
// Connect directly to a specific cluster
let config = ConnectConfig::new().uri("YOUR_CLUSTER_PUBLIC_ENDPOINT").token("YOUR_CLUSTER_TOKEN");
// Connect directly to a specific cluster
// Connect directly to a specific cluster
// Connect directly to a specific cluster
curl --request POST \
--url "YOUR_CLUSTER_PUBLIC_ENDPOINT/v2/vectordb/collections/list" \
--header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
--header "Content-Type: application/json" \
-d '{}'
パブリックエンドポイントを使用する場合、書き込み操作を受け付けるのはプライマリクラスターのパブリックエンドポイントのみです。セカンダリクラスターのパブリックエンドポイントへの書き込みは失敗します。
ルーティングの動作
通常運用時
| リクエストの種類 | グローバルエンドポイント | パブリックエンドポイント |
|---|---|---|
| 書き込み(insert、upsert、delete) | プライマリクラスターにルーティングされます | プライマリクラスターのエンドポイントでのみ受け付けられます |
| 読み取り(search、query) | プライマリクラスターにルーティングされます (レイテンシーに基づき、使用可能な最も近いクラスターへのインテリジェントルーティングが近日中にサポートされる予定です。) | 接続先の特定のクラスターによって処理されます |
スイッチオーバー / フェイルオーバー中および完了後
| シナリオ | グローバルエンドポイント | パブリックエンドポイント |
|---|---|---|
| スイッチオーバーの進行中 | 書き込みは一時的に停止し、その後新しいプライマリで再開します。読み取りは継続します。 | エンドポイントは変更されません。以前のプライマリはセカンダリになります。 |
| フェイルオーバーの進行中 | 新しいプライマリが昇格するまで書き込みは使用できません。読み取りはセカンダリで継続します。 | 以前のプライマリのエンドポイントに到達できなくなります。 |
| 完了後 | 新しいプライマリに自動的にルーティングされます。コードの変更は不要です。 | 書き込みには新しいプライマリのパブリックエンドポイントを使用するようにコードを更新してください。 |
SDK の自動再接続
グローバルエンドポイントを使用する場合、Zilliz Cloud SDK はスイッチオーバーおよびフェイルオーバー中のエンドポイントの再ルーティングを処理します。アプリケーションで、ルーティング変更自体に対する再試行ロジックを実装する必要はありません。ただし、切り替えの瞬間に実行中だった書き込みでは一時的なエラーが発生する可能性があります。このような場合は、アプリケーションの標準的な再試行ロジックで処理されます。