Skip to main content
Weaviate Docs (migrated from docs.weaviate.io) Docs

Search documentation

Type to search this documentation.

On this pageOverview

Collection aliases

Collection aliases allow you to create alternative names for your collections. This is useful for migrating between collections without downtime, A/B testing, or providing more convenient names for collections. An alias acts as a reference to a collection - when you query and manage objects using an alias name, Weaviate automatically routes the request to the target collection.

To create an alias, specify the alias name and the target collection it should point to.

Python
# Create a collection first
client.collections.create(
    name="Articles",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ],
)

# Create an alias pointing to the collection
client.alias.create(alias_name="ArticlesAlias", target_collection="Articles")
JavaScript/TypeScript
// Create a collection first
await client.collections.create({
    name: "Articles",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
    ],
})

console.log('Created collection "Articles"')
// Create an alias pointing to the collection
await client.alias.create({
    alias: "ArticlesAlias",
    collection: "Articles"
})

console.log('Created alias "ArticlesAlias"')
Go
// Create a collection first
err := client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "Articles",
  Vectorizer: "none",
  Properties: []*models.Property{
    {Name: "title", DataType: schema.DataTypeText.PropString()},
    {Name: "content", DataType: schema.DataTypeText.PropString()},
  },
}).Do(ctx)

require.NoError(t, err)

// Create an alias pointing to the collection
err = client.Alias().AliasCreator().WithAlias(&alias.Alias{
  Alias: "ArticlesProd",
  Class: "Articles",
}).Do(ctx)
Java
// Create a collection first
client.collections.create("Articles", col -> col.vectorConfig(VectorConfig.selfProvided())
    .properties(Property.text("title"), Property.text("content")));

// Create an alias pointing to the collection
client.alias.create("Articles", "ArticlesAlias");
C#
// Create a collection first
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = Articles,
        VectorConfig = Configure.Vector("default", v => v.SelfProvided()),
        Properties = [Property.Text("title"), Property.Text("content")],
    }
);

// Create an alias pointing to the collection
await client.Alias.Create(ArticlesAlias, Articles);

Retrieve all aliases in your Weaviate instance.

Python
# Get all aliases in the instance
all_aliases = client.alias.list_all()

for alias_name, alias_info in all_aliases.items():
    print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")
JavaScript/TypeScript
// Get all aliases in the instance
const allAliases = await client.alias.listAll()

if (allAliases) {
    for (const [_, aliasInfo] of Object.entries(allAliases)) {
        console.log(`Alias: ${aliasInfo.alias} -> Collection: ${aliasInfo.collection}`);
    }
}
Go
// Get all aliases in the instance
allAliases, err := client.Alias().Getter().Do(ctx)

require.NoError(t, err)

// Filter to show only aliases from this example
for _, aliasInfo := range allAliases {
  if aliasInfo.Class == "Articles" || aliasInfo.Class == "ArticlesV2" {
    fmt.Printf("Alias: %s -> Collection: %s\n", aliasInfo.Alias, aliasInfo.Class)
  }
}
Java
// Get all aliases in the instance
List<Alias> allAliases = client.alias.list();

for (Alias aliasInfo : allAliases) {
  System.out.printf("Alias: %s -> Collection: %s\n", aliasInfo.alias(), aliasInfo.collection());
}
C#
// Get all aliases in the instance
var allAliases = await client.Alias.List();

foreach (var entry in allAliases)
{
    Console.WriteLine($"Alias: {entry.Name} -> Collection: {entry.TargetCollection}");
}

Get all aliases that point to a specific collection.

Python
# Get all aliases pointing to a specific collection
collection_aliases = client.alias.list_all(collection="Articles")

for alias_name, alias_info in collection_aliases.items():
    print(f"Alias pointing to Articles: {alias_info.alias}")
JavaScript/TypeScript
// Get all aliases pointing to a specific collection
const collectionAliases = await client.alias.listAll({ collection: "Articles" })

if (collectionAliases) {
    for (const [_, aliasInfo] of Object.entries(collectionAliases)) {
        console.log(`Alias pointing to Articles: ${aliasInfo.alias}`);
    }
}
Go
// Get all aliases pointing to a specific collection
collectionAliases, err := client.Alias().Getter().WithClassName("Articles").Do(ctx)

require.NoError(t, err)

for _, aliasInfo := range collectionAliases {
  fmt.Printf("Alias pointing to Articles: %s\n", aliasInfo.Alias)
}
Java
// Get all aliases pointing to a specific collection
List<Alias> collectionAliases = client.alias.list(a -> a.collection("Articles"));

for (Alias aliasInfo : collectionAliases) {
  System.out.printf("Alias pointing to Articles: %s\n", aliasInfo.alias());
}
C#
// Get all aliases pointing to a specific collection
var collectionAliases = await client.Alias.List(Articles);

foreach (var entry in collectionAliases)
{
    Console.WriteLine($"Alias pointing to Articles: {entry.Name}");
}

Retrieve information about a specific alias.

Python
# Get information about a specific alias
alias_info = client.alias.get(alias_name="ArticlesAlias")

if alias_info:
    print(f"Alias: {alias_info.alias}")
    print(f"Target collection: {alias_info.collection}")
JavaScript/TypeScript
// Get information about a specific alias
const aliasInfo = await client.alias.get("ArticlesAlias")

if (aliasInfo) {
    console.log(`Alias: ${aliasInfo.alias}`);
    console.log(`Target collection: ${aliasInfo.collection}`);
}
Go
// Get information about a specific alias
aliasInfo, err := client.Alias().AliasGetter().WithAliasName("ArticlesProd").Do(ctx)

require.NoError(t, err)

if aliasInfo != nil {
  fmt.Printf("Alias: %s\n", aliasInfo.Alias)
  fmt.Printf("Target collection: %s\n", aliasInfo.Class)
}
Java
// Get information about a specific alias
Optional<Alias> aliasInfoOpt = client.alias.get("ArticlesAlias");

aliasInfoOpt.ifPresent(aliasInfo -> {
  System.out.printf("Alias: %s\n", aliasInfo.alias());
  System.out.printf("Target collection: %s\n", aliasInfo.collection());
});
C#
// Get information about a specific alias
var aliasInfo = await client.Alias.Get(aliasName: ArticlesAlias);

if (aliasInfo != null)
{
    Console.WriteLine($"Alias: {aliasInfo.Name}");
    Console.WriteLine($"Target collection: {aliasInfo.TargetCollection}");
}

Change the target collection that an alias points to. This operation is atomic and provides instant switching between collections.

Python
# Create a new collection for migration
client.collections.create(
    name="ArticlesV2",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(
            name="author", data_type=wvc.config.DataType.TEXT
        ),  # New field
    ],
)

# Update the alias to point to the new collection
success = client.alias.update(
    alias_name="ArticlesAlias", new_target_collection="ArticlesV2"
)

if success:
    print("Alias updated successfully")
JavaScript/TypeScript
// Create a new collection for migration
await client.collections.create({
    name: "ArticlesV2",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
        { name: "author", dataType: weaviate.configure.dataType.TEXT },  // New field
    ],
})

// Update the alias to point to the new collection
await client.alias.update({
    alias: "ArticlesAlias",
    newTargetCollection: "ArticlesV2"
})

console.log("Alias updated successfully")
Go
// Create a new collection for migration
err := client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "ArticlesV2",
  Vectorizer: "none",
  Properties: []*models.Property{
    {Name: "title", DataType: schema.DataTypeText.PropString()},
    {Name: "content", DataType: schema.DataTypeText.PropString()},
    {Name: "author", DataType: schema.DataTypeText.PropString()}, // New field
  },
}).Do(ctx)

require.NoError(t, err)

// Update the alias to point to the new collection
err = client.Alias().AliasUpdater().WithAlias(&alias.Alias{
  Alias: "ArticlesProd",
  Class: "ArticlesV2",
}).Do(ctx)

if err == nil {
  fmt.Println("Alias updated successfully")
}
Java
// Create a new collection for migration
client.collections.create("ArticlesV2", col -> col.vectorConfig(VectorConfig.selfProvided())
    .properties(Property.text("title"), Property.text("content"), Property.text("author") // New field
    ));

// Update the alias to point to the new collection
client.alias.update("ArticlesAlias", "ArticlesV2");
C#
// Create a new collection for migration
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = ArticlesV2,
        VectorConfig = Configure.Vector("default", v => v.Text2VecTransformers()),
        Properties =
        [
            Property.Text("title"),
            Property.Text("content"),
            Property.Text("author"), // New field
        ],
    }
);

// Update the alias to point to the new collection
bool success =
    (await client.Alias.Update(aliasName: ArticlesAlias, targetCollection: ArticlesV2))
    != null;

if (success)
{
    Console.WriteLine("Alias updated successfully");
}

Remove an alias. This only deletes the alias pointer, not the underlying collection.

Python
# Delete an alias (the underlying collection remains)
client.alias.delete(alias_name="ArticlesAlias")
JavaScript/TypeScript
// Delete an alias (the underlying collection remains)
await client.alias.delete("ArticlesAlias")
Go
// Delete an alias (the underlying collection remains)
err = client.Alias().AliasDeleter().WithAliasName("ArticlesProd").Do(ctx)
Java
// Delete an alias (the underlying collection remains)
client.alias.delete("ArticlesAlias");
C#
// Delete an alias (the underlying collection remains)
await client.Alias.Delete(aliasName: ArticlesAlias);

Once created, aliases can be used instead of collection names in all object-related operations, like data import and querying.

Python
# Ensure the Articles collection exists (it might have been deleted in previous examples)

client.collections.create(
    name="Articles",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ],
)
JavaScript/TypeScript
// Ensure the Articles collection exists (it might have been deleted in previous examples)

await client.collections.create({
    name: "Articles",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
    ],
})
Go
// Create an alias for easier access
err := client.Alias().AliasCreator().WithAlias(&alias.Alias{
  Alias: "MyArticles",
  Class: "Articles",
}).Do(ctx)

require.NoError(t, err)

// Use the alias just like a collection name

// Insert data using the alias
w, err := client.Data().Creator().
  WithClassName("MyArticles").
  WithProperties(map[string]interface{}{
    "title":   "Using Aliases in Weaviate",
    "content": "Aliases make collection management easier...",
  }).Do(ctx)

require.NoError(t, err)

// Query using the alias
result, err := client.Data().ObjectsGetter().
  WithClassName("MyArticles").
  WithLimit(5).
  Do(ctx)

require.NoError(t, err)

for _, obj := range result {
  if title, ok := obj.Properties.(map[string]interface{})["title"]; ok {
    fmt.Printf("Found: %v\n", title)
  }
}
Java
// Use the alias just like a collection name
CollectionHandle<Map<String, Object>> articles = client.collections.use("ArticlesAlias");

// Insert data using the alias
articles.data.insert(Map.of("title", "Using Aliases in Weaviate", "content",
    "Aliases make collection management easier..."));

// Query using the alias
var results = articles.query.fetchObjects(q -> q.limit(5));

for (var obj : results.objects()) {
  System.out.printf("Found: %s\n", obj.properties().get("title"));
}
C#
// Ensure the Articles collection exists (it might have been deleted in previous examples)
// Note: In C# we check existence first to avoid errors if it already exists
if (!await client.Collections.Exists(Articles))
{
    await client.Collections.Create(
        new CollectionCreateParams
        {
            Name = Articles,
            VectorConfig = Configure.Vector("default", v => v.SelfProvided()),
            Properties = [Property.Text("title"), Property.Text("content")],
        }
    );
}

Have a question or feedback? Here's how to reach us.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu