Zero-downtime collection migration with aliases

In this tutorial, we will explore how to use collection aliases in Weaviate to perform zero-downtime migrations. Collection aliases are alternative names for Weaviate collections that allow you to reference a collection by multiple names. This powerful feature enables you to migrate to new collection schemas, update configurations, or reorganize your data without any service interruption.

Prerequisites

Before starting this tutorial, ensure you have the following:

• An instance of Weaviate (e.g. on Weaviate Cloud, or locally), version v1.32 or newer.
• Your preferred Weaviate client library installed.
• Basic familiarity with Weaviate collections and data import.

See the Quickstart guide

For information on how to set up Weaviate and install the client library, see the cloud or local Quickstart guide.

Introduction

Traditional collection migrations require significant downtime. The typical workflow involves:

1. Creating a new collection
2. Stopping your application
3. Migrating data
4. Updating all collection references in your code
5. Restarting your application

This process causes service interruption and requires code changes. With aliases, you can eliminate both issues.

What are collection aliases?

A collection alias is a pointer to an underlying collection. When you query using an alias, Weaviate automatically routes the request to the target collection. Think of it like a symbolic link in a file system or a DNS alias for a website.

Collection aliases are ideal for schema migrations (updating properties or vectorization settings), A/B testing, and disaster recovery. They add minimal routing overhead and enable instant switching between collection versions without code changes.

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.

How aliases enable zero-downtime migration

Aliases allow you to keep your application code unchanged as it references the stable alias name. You can switch between collections instantly and roll back quickly if needed.

The migration process becomes:

1. Create a new collection with updated schema
2. Migrate data (while the old collection serves traffic)
3. Update the alias to point to the new collection (instant switch)
4. Delete the old collection after verification

Tutorial: Migrating a products collection

Let's walk through a complete migration scenario where we need to add a new field to an existing collection of products.

Step 1: Connect to Weaviate

First, connect to your Weaviate instance using your preferred client library.

Python

# Connect to local Weaviate instance
client = weaviate.connect_to_local()

  API docs

JS/TS

// Connect to local Weaviate instance
const client: WeaviateClient = await weaviate.connectToLocal()

  API docs

Java

// Connect to local Weaviate instance
String scheme = "http";
String host = "localhost";
String port = "8080";

Config config = new Config(scheme, host + ":" + port);
client = new WeaviateClient(config);

  API docs

Go

// Connect to local Weaviate instance
config := weaviate.Config{
Scheme: "http",
Host:   "localhost:8080",
}
client, err := weaviate.NewClient(config)
require.NoError(t, err)

  API docs

Step 2: Create the original collection

Let's create our initial products collection and populate it with data.

Python

# Create original collection with data
client.collections.create(
    name="Products_v1", vector_config=wvc.config.Configure.Vectors.self_provided()
)

products_v1 = client.collections.use("Products_v1")
products_v1.data.insert_many(
    [{"name": "Product A", "price": 100}, {"name": "Product B", "price": 200}]
)

  API docs

JS/TS

// Create original collection with data
await client.collections.create({
    name: "Products_v1",
    vectorizers: weaviate.configure.vectors.selfProvided()
})

const products_v1 = client.collections.use("Products_v1")

await products_v1.data.insertMany([
    { "name": "Product A", "price": 100 },
    { "name": "Product B", "price": 200 }
])

  API docs

Java

// Create original collection with data
WeaviateClass productsV1 = WeaviateClass.builder()
    .className("Products_v1")
    .build();

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

// Insert data into v1
List<WeaviateObject> products = Arrays.asList(
    WeaviateObject.builder()
        .className("Products_v1")
        .properties(new HashMap<String, Object>() {
          {
            put("name", "Product A");
            put("price", 100);
          }
        })
        .build(),
    WeaviateObject.builder()
        .className("Products_v1")
        .properties(new HashMap<String, Object>() {
          {
            put("name", "Product B");
            put("price", 200);
          }
        })
        .build());

client.batch().objectsBatcher()
    .withObjects(products.toArray(new WeaviateObject[0]))
    .run();

  API docs

Go

// Create original collection with data
err := client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "Products_v1",
  Vectorizer: "none",
}).Do(ctx)

require.NoError(t, err)

// Insert data into Products_v1
objects := []*models.Object{
  {
  	Class: "Products_v1",
  	Properties: map[string]interface{}{
  		"name":  "Product A",
  		"price": 100,
  	},
  },
  {
  	Class: "Products_v1",
  	Properties: map[string]interface{}{
  		"name":  "Product B",
  		"price": 200,
  	},
  },
}

_, err = client.Batch().ObjectsBatcher().
  WithObjects(objects...).
  Do(ctx)

require.NoError(t, err)

  API docs

Step 3: Create an alias for production access

Now create an alias that your application will use. This decouples your application code from the specific collection version.

Python

# Create alias pointing to current collection
client.alias.create(alias_name="ProductsAlias", target_collection="Products_v1")

  API docs

JS/TS

// Create alias pointing to current collection
await client.alias.create({
    alias: "ProductsAlias",
    collection: "Products_v1"
})

  API docs

Java

// Create alias pointing to current collection
client.alias().creator()
    .withClassName("Products_v1")
    .withAlias("Products")
    .run();

  API docs

Go

// Create alias pointing to current collection
err = client.Alias().AliasCreator().WithAlias(&alias.Alias{
  Alias: "Products",
  Class: "Products_v1",
}).Do(ctx)

require.NoError(t, err)

  API docs

Step 4: Use the alias in your application

Your application code should reference the alias, not the underlying collection. This ensures it continues working regardless of which collection version is active.

Python

# Your application always uses the alias name "Products"
products = client.collections.use("ProductsAlias")

# Insert data through the alias
products.data.insert({"name": "Product C", "price": 300})

# Query through the alias
results = products.query.fetch_objects(limit=5)
for obj in results.objects:
    print(f"Product: {obj.properties['name']}, Price: ${obj.properties['price']}")

  API docs

JS/TS

// Your application always uses the alias name "Products"
const prods = client.collections.use("ProductsAlias");

// Insert data through the alias
await prods.data.insert({ name: "Product C", price: 300 });

// Query through the alias
const res = await prods.query.fetchObjects({ limit: 5 });
for (const obj of res.objects) {
    console.log(`Product: ${obj.properties.name}, Price: $${obj.properties.price}`);
}

  API docs

Java

// Your application always uses the alias name "Products"
// Insert data through the alias
Result<WeaviateObject> insertResult = client.data().creator()
    .withClassName("Products")
    .withProperties(new HashMap<String, Object>() {{
        put("name", "Product C");
        put("price", 300);
    }})
    .run();

// Query through the alias
Result<List<WeaviateObject>> queryResult = client.data().objectsGetter()
    .withClassName("Products")
    .withLimit(5)
    .run();
List<WeaviateObject> results = queryResult.getResult();
for (WeaviateObject obj : results) {
    Map<String, Object> props = obj.getProperties();
    System.out.println("Product: " + props.get("name") + ", Price: $" + props.get("price"));
}

  API docs

Go

// Your application always uses the alias name "Products"
// Insert data through the alias
_, err = client.Data().Creator().WithClassName("Products").WithProperties(map[string]interface{}{
  "name":  "Product C",
  "price": 300,
}).Do(ctx)
require.NoError(t, err)

// Query through the alias
resp, err := client.Data().ObjectsGetter().WithClassName("Products").WithLimit(5).Do(ctx)
require.NoError(t, err)
for _, obj := range resp {
  props := obj.Properties.(map[string]interface{})
  t.Logf("Product: %v, Price: $%v", props["name"], props["price"])
}

  API docs

The key point is that your application code doesn't need to know whether it's accessing Products_v1 or Products_v2 - it just uses the stable alias name.

Step 5: Create the new collection with updated schema

Now let's create a new version of the collection with an additional field (e.g., adding a category property).

Python

# Create new collection with updated schema
client.collections.create(
    name="Products_v2",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
        wvc.config.Property(
            name="category", data_type=wvc.config.DataType.TEXT
        ),  # New field
    ],
)

  API docs

JS/TS

// Create new collection with updated schema
await client.collections.create({
    name: "Products_v2",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "name", dataType: weaviate.configure.dataType.TEXT },
        { name: "price", dataType: weaviate.configure.dataType.NUMBER },
        { name: "category", dataType: weaviate.configure.dataType.TEXT },  // New field
    ],
})

  API docs

Java

// Create new collection with updated schema
WeaviateClass productsV2 = WeaviateClass.builder()
    .className("Products_v2")
    .properties(Arrays.asList(
        Property.builder()
            .name("name")
            .dataType(Arrays.asList(DataType.TEXT))
            .build(),
        Property.builder()
            .name("price")
            .dataType(Arrays.asList(DataType.NUMBER))
            .build(),
        Property.builder()
            .name("category")
            .dataType(Arrays.asList(DataType.TEXT))
            .build() // New field
    ))
    .build();

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

  API docs

Go

// Create new collection with updated schema
err = client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "Products_v2",
  Vectorizer: "none",
  Properties: []*models.Property{
  	{Name: "name", DataType: schema.DataTypeText.PropString()},
  	{Name: "price", DataType: schema.DataTypeNumber.PropString()},
  	{Name: "category", DataType: schema.DataTypeText.PropString()}, // New field
  },
}).Do(ctx)

require.NoError(t, err)

  API docs

Step 6: Migrate data to the new collection

Copy data from the old collection to the new one, adding default values for new fields or transforming data as needed.

Python

# Migrate data to new collection
products_v2 = client.collections.use("Products_v2")
old_data = products_v1.query.fetch_objects().objects

for obj in old_data:
    products_v2.data.insert(
        {
            "name": obj.properties["name"],
            "price": obj.properties["price"],
            "category": "General",  # Default value for new field
        }
    )

  API docs

JS/TS

// Migrate data to new collection
const products_v2 = client.collections.use("Products_v2")
const oldData = (await products_v1.query.fetchObjects()).objects

for (const obj of oldData) {
    await products_v2.data.insert({
        "name": obj.properties["name"],
        "price": obj.properties["price"],
        "category": "General",  // Default value for new field
    })
}

  API docs

Java

// Migrate data to new collection
Result<GraphQLResponse> oldDataResult = client.graphQL()
    .get()
    .withClassName("Products_v1")
    .withFields(
        Field.builder().name("name").build(),
        Field.builder().name("price").build(),
        Field.builder().name("_additional").fields(
            Field.builder().name("id").build()).build())
    .run();

if (oldDataResult.getResult() != null) {
  Map<String, Object> data = (Map<String, Object>) oldDataResult.getResult().getData();
  Map<String, Object> get = (Map<String, Object>) data.get("Get");
  List<Map<String, Object>> oldProducts = (List<Map<String, Object>>) get.get("Products_v1");

  List<WeaviateObject> newProducts = new java.util.ArrayList<>();
  for (Map<String, Object> obj : oldProducts) {
    WeaviateObject newProduct = WeaviateObject.builder()
        .className("Products_v2")
        .properties(new HashMap<String, Object>() {
          {
            put("name", obj.get("name"));
            put("price", obj.get("price"));
            put("category", "General"); // Default value for new field
          }
        })
        .build();
    newProducts.add(newProduct);
  }

  client.batch().objectsBatcher()
      .withObjects(newProducts.toArray(new WeaviateObject[0]))
      .run();
}

  API docs

Go

// Migrate data to new collection
oldData, err := client.Data().ObjectsGetter().
  WithClassName("Products_v1").
  Do(ctx)

require.NoError(t, err)

for _, obj := range oldData {
  props := obj.Properties.(map[string]interface{})
  _, err = client.Data().Creator().
  	WithClassName("Products_v2").
  	WithProperties(map[string]interface{}{
  		"name":     props["name"],
  		"price":    props["price"],
  		"category": "General", // Default value for new field
  	}).Do(ctx)

  require.NoError(t, err)
}

  API docs

Step 7: Update the alias (instant switch)

This is the magic moment - update the alias to point to the new collection. This switch is instantaneous, and all queries using the ProductsAlias alias now access the new collection.

Python

# Switch alias to new collection (instant switch!)
client.alias.update(alias_name="ProductsAlias", new_target_collection="Products_v2")

# All queries using "Products" alias now use the new collection
products = client.collections.use("ProductsAlias")
result = products.query.fetch_objects(limit=1)
print(result.objects[0].properties)  # Will include the new "category" field

  API docs

JS/TS

// Switch alias to new collection (instant switch!)
await client.alias.update({
    alias: "ProductsAlias",
    newTargetCollection: "Products_v2"
})

// All queries using "ProductsAlias" alias now use the new collection
const products = client.collections.use("ProductsAlias")
const result = await products.query.fetchObjects({ limit: 1 })
console.log(result.objects[0].properties)  // Will include the new "category" field

  API docs

Java

// Switch alias to new collection (instant switch!)
client.alias().updater()
    .withAlias("Products")
    .withNewClassName("Products_v2")
    .run();

// All queries using "Products" alias now use the new collection
Result<GraphQLResponse> result = client.graphQL()
    .get()
    .withClassName("Products") // Using alias
    .withFields(
        Field.builder().name("name").build(),
        Field.builder().name("price").build(),
        Field.builder().name("category").build())
    .withLimit(1)
    .run();

if (result.getResult() != null) {
  Map<String, Object> data = (Map<String, Object>) result.getResult().getData();
  Map<String, Object> get = (Map<String, Object>) data.get("Get");
  List<Map<String, Object>> products_data = (List<Map<String, Object>>) get.get("Products");
  System.out.println(products_data.get(0)); // Will include the new "category" field
}

  API docs

Go

// Switch alias to new collection (instant switch!)
err = client.Alias().AliasUpdater().WithAlias(&alias.Alias{
  Alias: "Products",
  Class: "Products_v2",
}).Do(ctx)

require.NoError(t, err)

// All queries using "Products" alias now use the new collection
result, err := client.Data().ObjectsGetter().
  WithClassName("Products").
  WithLimit(1).
  Do(ctx)

require.NoError(t, err)

if len(result) > 0 {
  fmt.Printf("%v\n", result[0].Properties) // Will include the new "category" field
}

  API docs

Step 8: Verify and clean up

After verifying that everything works correctly with the new collection, you can safely delete the old one.

Python

# Clean up old collection after verification
client.collections.delete("Products_v1")

  API docs

JS/TS

// Clean up old collection after verification
await client.collections.delete("Products_v1")

  API docs

Java

// Clean up old collection after verification
client.schema().classDeleter()
    .withClassName("Products_v1")
    .run();

  API docs

Go

// Clean up old collection after verification
err = client.Schema().ClassDeleter().WithClassName("Products_v1").Do(ctx)

  API docs

Summary

This tutorial demonstrated how to use collection aliases in Weaviate for zero-downtime migrations. Key takeaways:

• Aliases are pointers to collections that enable instant switching between versions
• Zero downtime is achieved by preparing the new collection while the old one serves traffic
• Application code remains unchanged when using aliases instead of direct collection names
• Rollback is simple - just point the alias back to the previous collection

Collection aliases are essential for production Weaviate deployments where uptime is critical. They enable confident migrations, A/B testing, and flexible deployment strategies without service interruption.

Further resources

• How-to: Collection aliases

• Reference: REST - Schema

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.