Collection aliases

Technical preview

Collection aliases were added in v1.32 as a technical preview.

This means that the feature is still under development and may change in future releases, including potential breaking changes. We do not recommend using this feature in production environments at this time.

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

Create an alias

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

Python Client v4

# 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="ArticlesProd", target_collection="Articles")

  API docs

JS/TS Client v3

// 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: "ArticlesProd", 
    collection: "Articles"
})

console.log('Created alias "ArticlesProd"')

  API docs

Java

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

  API docs

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)

  API docs

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 be used instead of collection names in most operations (except when deleting collections)

List all aliases

Retrieve all aliases in your Weaviate instance.

Python Client v4

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

# Filter to show only aliases from this example
for alias_name, alias_info in all_aliases.items():
    if alias_info.collection in ["Articles", "ArticlesV2"]:
        print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")

  API docs

JS/TS Client v3

// Get all aliases in the instance
const allAliases = await client.alias.listAll()

// Filter to show only aliases from this example
for (const [aliasName, aliasInfo] of Object.entries(allAliases)) {
    if (["Articles", "ArticlesV2"].includes(aliasInfo.collection)) {
        console.log(`Alias: ${aliasInfo.alias} -> Collection: ${aliasInfo.collection}`);
    }
}

  API docs

Java

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

// Filter to show only aliases from this example
for (Map.Entry<String, Alias> entry : allAliases.entrySet()) {
  Alias aliasInfo = entry.getValue();
  if (aliasInfo.getClassName().equals("Articles") ||
      aliasInfo.getClassName().equals("ArticlesV2")) {
    System.out.println("Alias: " + aliasInfo.getAlias() +
        " -> Collection: " + aliasInfo.getClassName());
  }
}

  API docs

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

  API docs

List aliases for a specific collection

Get all aliases that point to a specific collection.

Python Client v4

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

  API docs

JS/TS Client v3

// Get all aliases pointing to a specific collection
const collectionAliases = await client.alias.listAll({ collection: "Articles"})

for (const [aliasName, aliasInfo] of Object.entries(collectionAliases)) {
    console.log(`Alias pointing to Articles: ${aliasInfo.alias}`);
}

  API docs

Java

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

  API docs

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

  API docs

Get alias details

Retrieve information about a specific alias.

Python Client v4

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

if alias_info:
    print(f"Alias: {alias_info.alias}")
    print(f"Target collection: {alias_info.collection}")

  API docs

JS/TS Client v3

// Get information about a specific alias
const aliasInfo = await client.alias.get("ArticlesProd")

if (aliasInfo) {
    console.log(`Alias: ${aliasInfo.alias}`);
    console.log(`Target collection: ${aliasInfo.collection}`);
}

  API docs

Java

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

  API docs

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

  API docs

Update an alias

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

Python Client v4

# 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="ArticlesProd", new_target_collection="ArticlesV2"
)

if success:
    print("Alias updated successfully")

  API docs

JS/TS Client v3

// 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: "ArticlesProd", 
    newTargetCollection: "ArticlesV2"
})

console.log("Alias updated successfully")

  API docs

Java

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

  API docs

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

  API docs

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 Starter guide: Managing collections

Delete an alias

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

Python Client v4

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

  API docs

JS/TS Client v3

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

  API docs

Java

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

  API docs

Go

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

  API docs

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 most operations (except when deleting collections):

Python Client v4

# 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),
    ],
)
# Create an alias for easier access
client.alias.create(alias_name="MyArticles", target_collection="Articles")

# Use the alias just like a collection name
articles = client.collections.get("MyArticles")

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

# Add a new property using the alias
articles.config.add_property(
    wvc.config.Property(name="author", data_type=wvc.config.DataType.TEXT)
)

  API docs

JS/TS Client v3

// 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: "MyArticles", 
    collection: "Articles"
})

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

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

// Add a new property using the alias
await articles.config.addProperty(
    { name: "author", dataType: weaviate.configure.dataType.TEXT }
)

  API docs

Java

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

// Add a new property using the alias
Result<Boolean> addPropertyResult = client.schema()
    .propertyCreator()
    .withClassName("MyArticles") // Using alias
    .withProperty(Property.builder()
        .name("author")
        .dataType(Arrays.asList(DataType.TEXT))
        .build())
    .run();

  API docs

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

// Add a new property using the alias
property := &models.Property{
  Name:     "author",
  DataType: schema.DataTypeText.PropString(),
}
err = client.Schema().PropertyCreator().
  WithClassName("MyArticles").
  WithProperty(property).
  Do(ctx)

  API docs

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.