Manage Aliases

In Zilliz Cloud, an alias is a secondary, mutable name for a collection. Using aliases provides a layer of abstraction that allows you to dynamically switch between collections without modifying your application code. This is particularly useful in production environments for seamless data updates, A/B testing, and other operational tasks.

This page demonstrates how to create, list, reassign, and drop collection aliases.

Why Use an Alias?

The primary benefit of using an alias is to decouple your client application from a specific, physical collection name.

Imagine you have a live application that queries a collection through an alias named prod_data. When you need to update the underlying data, you can perform the update without any service interruption. The workflow would be:

1. Create a New Collection: Create a new collection, for instance, prod_data_v2.
2. Prepare Data: Index and load the new data in prod_data_v2.
3. Switch the Alias: Once the new collection is ready for service, atomically reassign the alias prod_data from the old collection to prod_data_v2.

Your application continues to send requests to the alias prod_data, experiencing zero downtime. This mechanism enables seamless updates and simplifies operations like blue-green deployments for your vector search service.

Key Properties of Aliases:

• A collection can have multiple aliases.
• An alias can only point to one collection at a time.
• When processing a request, Zilliz Cloud first checks if a collection with the provided name exists. If not, it then checks if the name is an alias for a collection.

Create Alias

The following code snippet demonstrates how to create an alias for a collection.

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 Zilliz Cloud
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"

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

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

milvusAddr := "YOUR_CLUSTER_ENDPOINT"
token := "YOUR_CLUSTER_TOKEN"

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
    APIKey:  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 client = ClientV2::new(
    &ConnectConfig::new()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .token("YOUR_CLUSTER_TOKEN"),
)
.await?;

// 9.1 Create aliases
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 } from "@zilliz/milvus2-sdk-node";

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

// 9.1 Create aliases
let 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
//

CSharp

csharp

using Milvus.Client.V2;
using Milvus.Client.V2.Requests.Utility;
using Milvus.Client.V2.Types;

const string CLUSTER_ENDPOINT = "YOUR_CLUSTER_ENDPOINT";

using var client = new MilvusClientV2(new ConnectConfig
{
    Uri = CLUSTER_ENDPOINT,
    ApiKey = "YOUR_CLUSTER_TOKEN"
});
await client.ConnectAsync();

// 9.1 Create aliases
await client.CreateAliasAsync(new CreateAliasReq
{
    CollectionName = "my_collection_1",
    Alias = "bob"
});

await client.CreateAliasAsync(new CreateAliasReq
{
    CollectionName = "my_collection_1",
    Alias = "alice"
});

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": {}
# }

List Aliases

The following code snippet demonstrates the procedure to list the aliases allocated to a specific collection.

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

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::*;

// 9.2 List aliases
let res = client
    .list_aliases(
        ListAliasesRequest::builder()
            .collection_name("my_collection_1")
            .build()?,
    )
    .await?;

println!("{:?}", res.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 (const auto& alias : response.Aliases()) {
    std::cout << alias << std::endl;
}

NodeJS

javascript

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

console.log(listRes.aliases)

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

CSharp

csharp

using Milvus.Client.V2.Requests.Utility;
using Milvus.Client.V2.Responses.Utility;

// 9.2 List aliases
var listRes = await client.ListAliasesAsync(new ListAliasesReq
{
    CollectionName = "my_collection_1"
});
Console.WriteLine(string.Join(", ", listRes.Aliases));

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"
#     ]
# }

Describe Alias

The following code snippet describes a specific alias in detail, including the name of the collection to which it has been allocated.

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(collectionName=my_collection_1, alias=bob)

Go

go

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::*;

// 9.3 Describe alias
let res = client
    .describe_alias(
        DescribeAliasRequest::builder().alias("bob").build()?,
    )
    .await?;

println!("{:?}", res);

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 << response.Desc().CollectionName() << std::endl;

NodeJS

javascript

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

console.log(describeRes)

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

CSharp

csharp

using Milvus.Client.V2.Requests.Utility;
using Milvus.Client.V2.Responses.Utility;

// 9.3 Describe alias
var describeRes = await client.DescribeAliasAsync(new DescribeAliasReq
{
    Alias = "bob"
});
Console.WriteLine(describeRes.CollectionName);

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

Alter Alias

You can reallocate the alias already allocated to a specific collection to another.

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;

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

// Output:
// [alice]

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

listAliasRes = client.listAliases(listAliasesReq);

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

// Output:
// [bob]

Go

go

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::*;

// 9.4 Reassign an alias to another collection
client
    .alter_alias(
        AlterAliasRequest::builder()
            .collection_name("my_collection_2")
            .alias("alice")
            .build()?,
    )
    .await?;

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

C++

c++

auto status = client->AlterAlias(milvus::AlterAliasRequest()
                                     .WithCollectionName("my_collection_2")
                                     .WithAlias("alice"));
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;
}
for (const auto& alias : response.Aliases()) {
    std::cout << alias << std::endl;
}

NodeJS

javascript

// 9.4 Reassign aliases to other collections
let 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' ]
//

CSharp

csharp

using Milvus.Client.V2.Requests.Utility;
using Milvus.Client.V2.Types;

// 9.4 Reassign the alias to another collection
await client.AlterAliasAsync(new AlterAliasReq
{
    CollectionName = "my_collection_2",
    Alias = "alice"
});

var listRes = await client.ListAliasesAsync(new ListAliasesReq
{
    CollectionName = "my_collection_2"
});
Console.WriteLine(string.Join(", ", listRes.Aliases));

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/describe" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "aliasName": "alice"
}'

# {
#     "code": 0,
#     "data": {
#         "aliasName": "alice",
#         "collectionName": "my_collection_2",
#         "dbName": "default"
#     }
# }

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

Drop Alias

The following code snippet demonstrates the procedure to drop an alias.

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

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::*;

// 9.5 Drop aliases
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
let 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
//

CSharp

csharp

using Milvus.Client.V2.Requests.Utility;
using Milvus.Client.V2.Types;

// 9.5 Drop aliases
await client.DropAliasAsync(new DropAliasReq { Alias = "bob" });
await client.DropAliasAsync(new DropAliasReq { Alias = "alice" });

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": {}
# }