グローバルクラスターへの接続

プランでの提供状況

この機能は、Business Critical（SaaS）および BYOC デプロイでのみ利用できます。

リージョンでの提供状況

この機能は、サポートされているすべての AWS リージョンで利用できます。また、リクエストに応じて Google Cloud の us-central1 および us-east4 リージョンでも利用できます。この機能は Microsoft Azure では利用できません。

グローバルクラスターが稼働したら、エンドポイントと認証トークンを使用して接続します。このページでは、2 種類のエンドポイント、それぞれの使用場面、およびスイッチオーバーとフェイルオーバー時のルーティング動作について説明します。

エンドポイントの種類を選択する

グローバルクラスターには、2 つの接続方法があります。

• グローバルエンドポイント経由

• グローバルクラスター内のプライマリまたはセカンダリクラスターのパブリックまたはプライベートエンドポイント経由

次の表では、2 つの接続エンドポイントを比較します。

	グローバルエンドポイント	プライマリまたはセカンダリクラスターのエンドポイント
書き込みのルーティング	プライマリクラスターに自動的にルーティングされます	プライマリのパブリックエンドポイントのみが書き込みを受け付けます
読み取りのルーティング	プライマリクラスターにルーティングされます （レイテンシに基づいて利用可能な最も近いクラスターへのインテリジェントルーティングが近日中にサポートされる予定です。）	読み取りは、接続先の特定のクラスターに送信されます
スイッチオーバー / フェイルオーバー	自動的に再ルーティングされます。コードの変更は不要です	新しいプライマリを指すように接続を更新する必要があります
Private Link	サポートされていません（パブリックインターネットが必要です）	サポートされています。
最適な用途	自動フェイルオーバーとレイテンシに基づくルーティングを必要とする本番アプリケーション	特定のクラスターへの直接アクセス（環境のレプリケーション、テスト、デバッグなど）

Notes

本番ワークロードには、グローバルエンドポイントの使用を推奨します。これにより、スイッチオーバーまたはフェイルオーバー時に、アプリケーションコードでエンドポイントの変更を処理する必要がなくなります。

エンドポイントとトークンを取得する

1

グローバルクラスターまたはターゲットクラスターに移動します。

• グローバルエンドポイントの場合：Global クラスター ページに移動します。

• パブリックエンドポイントの場合：特定のプライマリまたはセカンダリクラスターのクラスター Details ページに移動します。

2

Connect カードで、Global Endpoint または Public Endpoint をコピーします。

3

認証トークンを準備します。これは API キー または クラスター認証情報（username:password）のいずれかです。

グローバルエンドポイントを使用して接続する

グローバルエンドポイントは、グローバルクラスター内の現在のプライマリクラスターに常にリクエストをルーティングする単一の URL です。

スイッチオーバーまたはフェイルオーバーが発生すると、Zilliz Cloud はグローバルエンドポイントを自動的に更新して新しいプライマリクラスターを指すようにします。これにより、クラスター URI を手動で変更することなく、アプリケーションは同じエンドポイントを引き続き使用できます。

Zilliz Cloud は、SDK と RESTful API の両方を通じてグローバルエンドポイントへの接続をサポートしています。本番アプリケーションでは、SDK クライアントの使用を推奨します。

RESTful API 接続ではなく SDK 接続が推奨されるのはなぜですか？

SDK クライアントは、エンドポイントの一覧、プライマリとセカンダリの役割、クラスターのヘルスを含むグローバルクラスターのトポロジーを取得できます。この情報により、SDK クライアントはプライマリクラスターが変更されたときに迅速に対応できます。SDK クライアントは将来、read/write splitting もサポートする予定であり、書き込みリクエストはプライマリクラスターにルーティングされ、対象となる読み取りリクエストはグローバルクラスターのトポロジーに基づいてルーティングされます。

ただし、RESTful API 接続はグローバルクラスターのトポロジー情報を保持しません。そのため、RESTful API 接続では、スイッチオーバーまたはフェイルオーバー後に新しいプライマリクラスターへ切り替えるまでに時間がかかる場合があります。同じ理由により、RESTful API 接続は read/write splitting をサポートできません。

次の表では、SDK 接続と RESTful API 接続を比較します。

項目	SDK 接続	RESTful API 接続
最適な用途	役割の変更時における迅速な復旧と、将来の read/write splitting を必要とする本番アプリケーション。	軽量なスクリプト、シンプルな REST 統合、および 1 回限りの管理操作。
トポロジー認識	エンドポイントの一覧、プライマリとセカンダリの役割、クラスターのヘルスを含むグローバルクラスターのトポロジーを取得します。	グローバルクラスターのトポロジー情報を保持しません。
プライマリ変更時の処理	スイッチオーバーまたはフェイルオーバー後にプライマリクラスターが変更されると、通常は数秒以内に、より迅速に対応できます。	クライアントがトポロジー情報を保持しないため、新しいプライマリへの切り替えに通常は数分かかる場合があります。
Read/write splitting	近日中にサポートされる予定です。	サポートされていません。

SDK のバージョンを確認する

作業を開始する前に、SDK をインストールしていること、および SDK が最小バージョン要件を満たしていることを確認してください。

SDK	最小バージョン
Python	2.6.9
Java	2.6.14

接続ガイド

Python

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

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);

Go

go

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)
}

Rust

rust

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?;

C++

c++

#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;
}

NodeJS

javascript

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
});

CSharp

csharp

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

bash

curl --request POST \
  --url "YOUR_GLOBAL_ENDPOINT/v2/vectordb/collections/list" \
  --header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
  --header "Content-Type: application/json" \
  -d '{}'

パブリックエンドポイントを使用して接続する

グローバルクラスター内の各クラスターには、それぞれ専用のパブリックエンドポイントがあります。特定のクラスターを直接対象とする必要がある場合に使用します。

Python

python

# Connect directly to a specific cluster

Java

java

// Connect directly to a specific cluster

Go

go

// 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)
}

Rust

rust

// Connect directly to a specific cluster
let config = ConnectConfig::new().uri("YOUR_CLUSTER_PUBLIC_ENDPOINT").token("YOUR_CLUSTER_TOKEN");

C++

c++

// Connect directly to a specific cluster

NodeJS

javascript

// Connect directly to a specific cluster

CSharp

csharp

// Connect directly to a specific cluster

cURL

bash

curl --request POST \
  --url "YOUR_CLUSTER_PUBLIC_ENDPOINT/v2/vectordb/collections/list" \
  --header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
  --header "Content-Type: application/json" \
  -d '{}'

Notes

パブリックエンドポイントを使用する場合、書き込み操作を受け付けるのはプライマリクラスターのパブリックエンドポイントのみです。セカンダリクラスターのパブリックエンドポイントへの書き込みは失敗します。

ルーティングの動作

通常運用時

リクエストの種類	グローバルエンドポイント	パブリックエンドポイント
書き込み（insert、upsert、delete）	プライマリクラスターにルーティングされます	プライマリクラスターのエンドポイントでのみ受け付けられます
読み取り（search、query）	プライマリクラスターにルーティングされます （レイテンシに基づいて利用可能な最も近いクラスターへのインテリジェントルーティングが近日中にサポートされる予定です。）	接続先の特定のクラスターによって処理されます

スイッチオーバーまたはフェイルオーバー中および完了後

シナリオ	グローバルエンドポイント	パブリックエンドポイント
スイッチオーバー中	書き込みは一時的に停止し、その後新しいプライマリで再開します。読み取りは継続されます。	エンドポイントは変更されません。以前のプライマリはセカンダリになります。
フェイルオーバー中	新しいプライマリが昇格されるまで書き込みは利用できません。読み取りはセカンダリで継続されます。	以前のプライマリのエンドポイントに到達できなくなります。
完了後	新しいプライマリへ自動的にルーティングされます。コードの変更は不要です。	書き込みには新しいプライマリのパブリックエンドポイントを使用するよう、コードを更新してください。

SDK による自動再接続

グローバルエンドポイントを使用する場合、スイッチオーバーおよびフェイルオーバー時のエンドポイントの再ルーティングは Zilliz Cloud SDK が処理します。アプリケーションでルーティング変更自体の再試行ロジックを実装する必要はありません。ただし、スイッチの時点で処理中の書き込みは一時的なエラーを受け取る場合があります。アプリケーションの標準の再試行ロジックでこれらのケースが処理されます。