Collection aliases

Added in v1.32

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.

Collection alias usage

Weaviate automatically routes alias requests to the target collection for object-related operations. You can use aliases wherever collection names are required for:

• Managing objects: Create, batch import, read, update and delete objects through collection aliases.
• Querying objects: Fetch objects and perform searches (vector, keyword, hybrid, image, generative/RAG) and aggregations through aliases.

Create an alias

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

// 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"')

// Create a collection first
WeaviateClass articlesClass = WeaviateClass.builder()
    .className("Articles")
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build(),
        Property.builder()
            .name("content")
            .dataType(Arrays.asList(DataType.TEXT))
            .build()))
    .build();

Result<Boolean> createResult = client.schema().classCreator()
    .withClass(articlesClass)
    .run();

// Create an alias pointing to the collection
Result<Boolean> aliasResult = client.alias().creator()
    .withClassName("Articles")
    .withAlias("ArticlesProd")
    .run();

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

note

• An alias name must be unique and cannot match any existing collection or alias name
• Multiple aliases can point to the same collection
• Aliases can only be used instead of collection names in object-related operations (managing objects and querying)

List all aliases

Retrieve all aliases in your Weaviate instance.

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Get all aliases in the instance
Result<Map<String, Alias>> allAliasesResult = client.alias().allGetter().run();
Map<String, Alias> allAliases = allAliasesResult.getResult();

for (Map.Entry<String, Alias> entry : allAliases.entrySet()) {
  Alias aliasInfo = entry.getValue();
  System.out.println("Alias: " + aliasInfo.getAlias() +
      " -> Collection: " + aliasInfo.getClassName());
}

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

List aliases for a specific collection

Get all aliases that point to a specific collection.

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Get all aliases pointing to a specific collection
Result<Map<String, Alias>> collectionAliasesResult = client.alias()
    .allGetter()
    .withClassName("Articles")
    .run();
Map<String, Alias> collectionAliases = collectionAliasesResult.getResult();

for (Map.Entry<String, Alias> entry : collectionAliases.entrySet()) {
  Alias aliasInfo = entry.getValue();
  System.out.println("Alias pointing to Articles: " + aliasInfo.getAlias());
}

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

Get alias details

Retrieve information about a specific alias.

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Get information about a specific alias
Result<Alias> aliasInfoResult = client.alias()
    .getter()
    .withAlias("ArticlesProd")
    .run();

if (aliasInfoResult.getResult() != null) {
  Alias aliasInfo = aliasInfoResult.getResult();
  System.out.println("Alias: " + aliasInfo.getAlias());
  System.out.println("Target collection: " + aliasInfo.getClassName());
}

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

Update an alias

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Create a new collection for migration
WeaviateClass articlesV2Class = WeaviateClass.builder()
    .className("ArticlesV2")
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build(),
        Property.builder()
            .name("content")
            .dataType(Arrays.asList(DataType.TEXT))
            .build(),
        Property.builder()
            .name("author")
            .dataType(Arrays.asList(DataType.TEXT))
            .build() // New field
    ))
    .build();

client.schema().classCreator()
    .withClass(articlesV2Class)
    .run();

// Update the alias to point to the new collection
Result<Boolean> updateResult = client.alias()
    .updater()
    .withAlias("ArticlesProd")
    .withNewClassName("ArticlesV2")
    .run();

if (updateResult.getResult()) {
  System.out.println("Alias updated successfully");
}

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

Use case: Zero-downtime migration

Updating an alias is particularly useful for migrations:

1. Create a new collection with updated collection definition
2. Import data into the new collection
3. Update the alias to point to the new collection
4. Continue to use the alias - all queries to it are now directed to the new collection

For a code example on how to perform migrations, visit the Tutorial: Migrating collections with aliases

Delete an alias

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

# Delete an alias (the underlying collection remains)
client.alias.delete(alias_name="ArticlesAlias")

// Delete an alias (the underlying collection remains)
await client.alias.delete("ArticlesAlias")

// Delete an alias (the underlying collection remains)
Result<Boolean> deleteResult = client.alias()
    .deleter()
    .withAlias("ArticlesProd")
    .run();

// Delete an alias (the underlying collection remains)
err = client.Alias().AliasDeleter().WithAliasName("ArticlesProd").Do(ctx)

note

• Deleting a collection does not automatically delete aliases pointing to it

Using aliases in operations

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

# 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),
    ],
)
# Use the alias just like a collection name
articles = client.collections.use("ArticlesAlias")

# Insert data using the alias
articles.data.insert(
    {
        "title": "Using Aliases in Weaviate",
        "content": "Aliases make collection management easier...",
    }
)

# Query using the alias
results = articles.query.fetch_objects(limit=5)

for obj in results.objects:
    print(f"Found: {obj.properties['title']}")

// 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 },
    ],
})
// Create an alias for easier access
await client.alias.create({
    alias: "ArticlesAlias",
    collection: "Articles"
})

// Use the alias just like a collection name
const articles = client.collections.use("ArticlesAlias")

// Insert data using the alias
await articles.data.insert({
    "title": "Using Aliases in Weaviate",
    "content": "Aliases make collection management easier...",
})

// Query using the alias
const results = await articles.query.fetchObjects({ limit: 5 })

for (const obj of results.objects) {
    console.log(`Found: ${obj.properties['title']}`);
}

// Ensure the Articles collection exists
WeaviateClass articlesClass = WeaviateClass.builder()
    .className("Articles")
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build(),
        Property.builder()
            .name("content")
            .dataType(Arrays.asList(DataType.TEXT))
            .build()))
    .build();

client.schema().classCreator()
    .withClass(articlesClass)
    .run();

// Create an alias for easier access
client.alias().creator()
    .withClassName("Articles")
    .withAlias("MyArticles")
    .run();

// Use the alias just like a collection name
// Insert data using the alias
WeaviateObject article = WeaviateObject.builder()
    .className("MyArticles") // Using alias instead of actual class name
    .properties(new HashMap<String, Object>() {
      {
        put("title", "Using Aliases in Weaviate");
        put("content", "Aliases make collection management easier...");
      }
    })
    .build();

Result<ObjectGetResponse[]> insertResult = client.batch()
    .objectsBatcher()
    .withObject(article)
    .run();

// Query using the alias
Result<GraphQLResponse> queryResult = client.graphQL()
    .get()
    .withClassName("MyArticles") // Using alias
    .withFields(Field.builder().name("title").build())
    .withLimit(5)
    .run();

if (queryResult.getResult() != null) {
  Map<String, Object> data = (Map<String, Object>) queryResult.getResult().getData();
  Map<String, Object> get = (Map<String, Object>) data.get("Get");
  List<Map<String, Object>> myArticles = (List<Map<String, Object>>) get.get("MyArticles");

  for (Map<String, Object> obj : myArticles) {
    System.out.println("Found: " + obj.get("title"));
  }
}

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

Further resources

• Manage collections: Basic operations
• References: Collection definition

• API References: REST: Aliases

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.