エイリアスの管理

Zilliz Cloud では、エイリアスはコレクションに付ける変更可能な副次的な名前です。エイリアスを使用すると抽象化のレイヤーが提供され、アプリケーションコードを変更せずにコレクションを動的に切り替えられます。これは、シームレスなデータ更新、A/B テスト、その他の運用タスクに特に役立つため、本番環境に適しています。

このページでは、コレクションのエイリアスを作成、一覧表示、再割り当て、削除する方法を説明します。

エイリアスを使用する理由

エイリアスを使用する主な利点は、クライアントアプリケーションを特定の物理的なコレクション名から切り離せることです。

prod_data というエイリアスでコレクションをクエリする稼働中のアプリケーションがあるとします。基になるデータを更新する必要がある場合でも、サービスを中断せずに更新を実行できます。ワークフローは次の通りです。

1. 新しいコレクションを作成する: 新しいコレクション（たとえば prod_data_v2）を作成します。

2. データを準備する: prod_data_v2 で新しいデータのインデックスを作成してロードします。

3. エイリアスを切り替える: 新しいコレクションがサービスを提供できる状態になったら、エイリアス prod_data を古いコレクションから prod_data_v2 にアトミックに再割り当てします。

アプリケーションは引き続きエイリアス prod_data にリクエストを送信し、ダウンタイムは発生しません。この仕組みによりシームレスな更新が可能になり、ベクトル検索サービスのブルーグリーンデプロイなどの運用が簡素化されます。

エイリアスの主な特性:

• 1 つのコレクションに複数のエイリアスを設定できます。

• エイリアスは一度に 1 つのコレクションのみを指すことができます。

• リクエストを処理するとき、Zilliz Cloud はまず指定された名前のコレクションが存在するかどうかを確認します。存在しない場合は、その名前がコレクションのエイリアスかどうかを確認します。

エイリアスを作成する

次のコードスニペットは、コレクションのエイリアスを作成する方法を示しています。

Python

python

from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

# 9. Manage aliases
# 9.1. Create aliases
client.create_alias(
    collection_name="my_collection_1",
    alias="bob"
)

client.create_alias(
    collection_name="my_collection_1",
    alias="alice"
)

Java

java

import io.milvus.v2.service.utility.request.CreateAliasReq;
import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;

String CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT";
String TOKEN = "YOUR_CLUSTER_TOKEN";

// 1. Connect to Milvus server
ConnectConfig connectConfig = ConnectConfig.builder()
        .uri(CLUSTER_ENDPOINT)
        .token(TOKEN)
        .build();

MilvusClientV2 client = new MilvusClientV2(connectConfig);

// 9. Manage aliases

// 9.1 Create alias
CreateAliasReq createAliasReq = CreateAliasReq.builder()
        .collectionName("my_collection_1")
        .alias("bob")
        .build();

client.createAlias(createAliasReq);

createAliasReq = CreateAliasReq.builder()
        .collectionName("my_collection_1")
        .alias("alice")
        .build();

client.createAlias(createAliasReq);

Go

go

import (
    "context"
    "fmt"

    milvusclient "github.com/milvus-io/milvus/client/v3/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

milvusAddr := "YOUR_CLUSTER_ENDPOINT"
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

err = client.CreateAlias(ctx, milvusclient.NewCreateAliasOption("my_collection_1", "bob"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

err = client.CreateAlias(ctx, milvusclient.NewCreateAliasOption("my_collection_1", "alice"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

Rust

rust

use milvus::v2::prelude::*;

let config = ConnectConfig::new()
    .uri("YOUR_CLUSTER_ENDPOINT")
    .token("YOUR_CLUSTER_TOKEN");
let client = ClientV2::new(&config).await?;

client
    .create_alias(
        CreateAliasRequest::builder()
            .collection_name("my_collection_1")
            .alias("bob")
            .build()?,
    )
    .await?;

client
    .create_alias(
        CreateAliasRequest::builder()
            .collection_name("my_collection_1")
            .alias("alice")
            .build()?,
    )
    .await?;

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"YOUR_CLUSTER_ENDPOINT", "YOUR_CLUSTER_TOKEN"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

status = client->CreateAlias(milvus::CreateAliasRequest()
                                .WithCollectionName("my_collection_1")
                                .WithAlias("bob"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

status = client->CreateAlias(milvus::CreateAliasRequest()
                                .WithCollectionName("my_collection_1")
                                .WithAlias("alice"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "YOUR_CLUSTER_ENDPOINT";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});
var res;

// 9. Manage aliases
// 9.1 Create aliases
res = await client.createAlias({
    collection_name: "my_collection_1",
    alias: "bob"
})

console.log(res.error_code)

// Output
// 
// Success
// 

res = await client.createAlias({
    collection_name: "my_collection_1",
    alias: "alice"
})

console.log(res.error_code)

// Output
// 
// Success
// 

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "bob",
    "collectionName": "my_collection_1"
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "alice",
    "collectionName": "my_collection_1"
}'

# {
#     "code": 0,
#     "data": {}
# }

エイリアスを一覧表示する

次のコードスニペットは、特定のコレクションに割り当てられたエイリアスを一覧表示する手順を示しています。

Python

python

# 9.2. List aliases
res = client.list_aliases(
    collection_name="my_collection_1"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "bob",
#         "alice"
#     ],
#     "collection_name": "my_collection_1",
#     "db_name": "default"
# }

Java

java

import io.milvus.v2.service.utility.request.ListAliasesReq;
import io.milvus.v2.service.utility.response.ListAliasResp;

// 9.2 List aliases
ListAliasesReq listAliasesReq = ListAliasesReq.builder()
    .collectionName("my_collection_1")
    .build();

ListAliasResp listAliasRes = client.listAliases(listAliasesReq);

System.out.println(listAliasRes.getAlias());

// Output:
// [bob, alice]

Go

go

import (
    "fmt"

    "github.com/milvus-io/milvus/client/v3/milvusclient"
)

aliases, err := client.ListAliases(ctx, milvusclient.NewListAliasesOption("my_collection_1"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(aliases)

Rust

rust

use milvus::v2::prelude::*;

let aliases = client
    .list_aliases(
        ListAliasesRequest::builder()
            .collection_name("my_collection_1")
            .build()?,
    )
    .await?;
println!("{:?}", aliases.aliases());

C++

c++

milvus::ListAliasesResponse response;
auto status = client->ListAliases(milvus::ListAliasesRequest()
                                    .WithCollectionName("my_collection_1"),
                                  response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
for (auto alias : response.Aliases()) {
    std::cout << "\t" << alias << std::endl;
}

NodeJS

javascript

// 9.2 List aliases
res = await client.listAliases({
    collection_name: "my_collection_1"
})

console.log(res.aliases)

// Output
// 
// [ 'bob', 'alice' ]
// 

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection_1"
}'

# {
#     "code": 0,
#     "data": [
#         "bob",
#         "alice"
#     ]
# }

エイリアスを詳細表示する

次のコードスニペットは、割り当て先のコレクション名を含め、特定のエイリアスの詳細を表示します。

Python

python

# 9.3. Describe aliases
res = client.describe_alias(
    alias="bob"
)

print(res)

# Output
#
# {
#     "alias": "bob",
#     "collection_name": "my_collection_1",
#     "db_name": "default"
# }

Java

java

import io.milvus.v2.service.utility.request.DescribeAliasReq;
import io.milvus.v2.service.utility.response.DescribeAliasResp;

// 9.3 Describe alias
DescribeAliasReq describeAliasReq = DescribeAliasReq.builder()
    .alias("bob")
    .build();

DescribeAliasResp describeAliasRes = client.describeAlias(describeAliasReq);

System.out.println(describeAliasRes);

// Output:
// DescribeAliasResp(databaseName=default, collectionName=my_collection_1, alias=bob)

Go

go

import (
    "fmt"

    "github.com/milvus-io/milvus/client/v3/milvusclient"
)

alias, err := client.DescribeAlias(ctx, milvusclient.NewDescribeAliasOption("bob"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(alias)

Rust

rust

use milvus::v2::prelude::*;

let alias = client
    .describe_alias(
        DescribeAliasRequest::builder()
            .alias("bob")
            .build()?,
    )
    .await?;
println!("{:?}", alias);

C++

c++

milvus::DescribeAliasResponse response;
auto status = client->DescribeAlias(milvus::DescribeAliasRequest().WithAlias("bob"),
                                    response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
std::cout << "Collection name: " << response.Desc().CollectionName() << std::endl;
std::cout << "Database name: " << response.Desc().DatabaseName() << std::endl;

NodeJS

javascript

// 9.3 Describe aliases
res = await client.describeAlias({
    collection_name: "my_collection_1",
    alias: "bob"
})

console.log(res)

// Output
// 
// {
//   status: {
//     extra_info: {},
//     error_code: 'Success',
//     reason: '',
//     code: 0,
//     retriable: false,
//     detail: ''
//   },
//   db_name: 'default',
//   alias: 'bob',
//   collection: 'my_collection_1'
// }
// 

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/describe" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "bob"
}'

# {
#     "code": 0,
#     "data": {
#         "aliasName": "bob",
#         "collectionName": "my_collection_1",
#         "dbName": "default"
#     }
# }

エイリアスを変更する

特定のコレクションにすでに割り当てられているエイリアスを、別のコレクションに再割り当てできます。

Python

python

# 9.4 Reassign aliases to other collections
client.alter_alias(
    collection_name="my_collection_2",
    alias="alice"
)

res = client.list_aliases(
    collection_name="my_collection_2"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "alice"
#     ],
#     "collection_name": "my_collection_2",
#     "db_name": "default"
# }

res = client.list_aliases(
    collection_name="my_collection_1"
)

print(res)

# Output
#
# {
#     "aliases": [
#         "bob"
#     ],
#     "collection_name": "my_collection_1",
#     "db_name": "default"
# }

Java

java

import io.milvus.v2.service.utility.request.AlterAliasReq;
import io.milvus.v2.service.utility.request.ListAliasesReq;
import io.milvus.v2.service.utility.response.ListAliasResp;

// 9.4 Reassign alias to other collections
AlterAliasReq alterAliasReq = AlterAliasReq.builder()
        .collectionName("my_collection_2")
        .alias("alice")
        .build();

client.alterAlias(alterAliasReq);

ListAliasesReq listAliasesReq = ListAliasesReq.builder()
        .collectionName("my_collection_2")
        .build();

ListAliasResp listAliasRes = client.listAliases(listAliasesReq);

System.out.println(listAliasRes.getAlias());

listAliasesReq = ListAliasesReq.builder()
        .collectionName("my_collection_1")
        .build();

listAliasRes = client.listAliases(listAliasesReq);

System.out.println(listAliasRes.getAlias());

// Output:
// [alice]
// [bob]

Go

go

import (
    "fmt"

    "github.com/milvus-io/milvus/client/v3/milvusclient"
)

err = client.AlterAlias(ctx, milvusclient.NewAlterAliasOption("alice", "my_collection_2"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

aliases, err := client.ListAliases(ctx, milvusclient.NewListAliasesOption("my_collection_2"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(aliases)

aliases, err = client.ListAliases(ctx, milvusclient.NewListAliasesOption("my_collection_1"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(aliases)

Rust

rust

use milvus::v2::prelude::*;

client
    .alter_alias(
        AlterAliasRequest::builder()
            .collection_name("my_collection_2")
            .alias("alice")
            .build()?,
    )
    .await?;

let mut aliases = client
    .list_aliases(
        ListAliasesRequest::builder()
            .collection_name("my_collection_2")
            .build()?,
    )
    .await?;
println!("{:?}", aliases.aliases());

aliases = client
    .list_aliases(
        ListAliasesRequest::builder()
            .collection_name("my_collection_1")
            .build()?,
    )
    .await?;
println!("{:?}", aliases.aliases());

C++

c++

auto status = client->AlterAlias(milvus::AlterAliasRequest()
                                    .WithAlias("alice")
                                    .WithCollectionName("my_collection_2"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::ListAliasesResponse response;
status = client->ListAliases(milvus::ListAliasesRequest()
                                .WithCollectionName("my_collection_2"),
                             response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
std::cout << "aliases of my_collection_2" << std::endl;
for (auto alias : response.Aliases()) {
    std::cout << "\t" << alias << std::endl;
}

status = client->ListAliases(milvus::ListAliasesRequest()
                                .WithCollectionName("my_collection_1"),
                             response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}
std::cout << "aliases of my_collection_1" << std::endl;
for (auto alias : response.Aliases()) {
    std::cout << "\t" << alias << std::endl;
}

NodeJS

javascript

// 9.4 Reassign aliases to other collections
res = await client.alterAlias({
    collection_name: "my_collection_2",
    alias: "alice"
})

console.log(res.error_code)

// Output
// 
// Success
// 

res = await client.listAliases({
    collection_name: "my_collection_2"
})

console.log(res.aliases)

// Output
// 
// [ 'alice' ]
// 

res = await client.listAliases({
    collection_name: "my_collection_1"
})

console.log(res.aliases)

// Output
// 
// [ 'bob' ]
// 

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/alter" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "alice",
    "collectionName": "my_collection_2"
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection_2"
}'

# {
#     "code": 0,
#     "data": [
#         "alice"
#     ]
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection_1"
}'

# {
#     "code": 0,
#     "data": [
#         "bob"
#     ]
# }

エイリアスを削除する

次のコードスニペットは、エイリアスを削除する手順を示しています。

Python

python

# 9.5 Drop aliases
client.drop_alias(
    alias="bob"
)

client.drop_alias(
    alias="alice"
)

Java

java

import io.milvus.v2.service.utility.request.DropAliasReq;

// 9.5 Drop alias
DropAliasReq dropAliasReq = DropAliasReq.builder()
    .alias("bob")
    .build();

client.dropAlias(dropAliasReq);

dropAliasReq = DropAliasReq.builder()
    .alias("alice")
    .build();

client.dropAlias(dropAliasReq);

Go

go

import (
    "fmt"

    "github.com/milvus-io/milvus/client/v3/milvusclient"
)

err = client.DropAlias(ctx, milvusclient.NewDropAliasOption("bob"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

err = client.DropAlias(ctx, milvusclient.NewDropAliasOption("alice"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

Rust

rust

use milvus::v2::prelude::*;

client
    .drop_alias(
        DropAliasRequest::builder()
            .alias("bob")
            .build()?,
    )
    .await?;

client
    .drop_alias(
        DropAliasRequest::builder()
            .alias("alice")
            .build()?,
    )
    .await?;

C++

c++

auto status = client->DropAlias(milvus::DropAliasRequest().WithAlias("bob"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

status = client->DropAlias(milvus::DropAliasRequest().WithAlias("alice"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

// 9.5 Drop aliases
res = await client.dropAlias({
    alias: "bob"
})

console.log(res.error_code)

// Output
// 
// Success
// 

res = await client.dropAlias({
    alias: "alice"
})

console.log(res.error_code)

// Output
// 
// Success
// 

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/drop" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "bob"
}'

# {
#     "code": 0,
#     "data": {}
# }

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/aliases/drop" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "alice"
}'

# {
#     "code": 0,
#     "data": {}
# }