From aca8b4f9ea24ef0fd843f955466ab9115e4d3e12 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 09:29:05 +0200
Subject: [PATCH 01/11] Add new tutorial
---
.../_includes/vectorizer-migration.py | 547 ++++++++++++++++++
.../tutorials/vectorizer-migration.mdx | 342 +++++++++++
sidebars.js | 1 +
3 files changed, 890 insertions(+)
create mode 100644 docs/weaviate/tutorials/_includes/vectorizer-migration.py
create mode 100644 docs/weaviate/tutorials/vectorizer-migration.mdx
diff --git a/docs/weaviate/tutorials/_includes/vectorizer-migration.py b/docs/weaviate/tutorials/_includes/vectorizer-migration.py
new file mode 100644
index 000000000..559a38867
--- /dev/null
+++ b/docs/weaviate/tutorials/_includes/vectorizer-migration.py
@@ -0,0 +1,547 @@
+import os
+import weaviate
+import weaviate.classes as wvc
+from weaviate.auth import Auth
+from weaviate.classes.config import Configure
+import time
+from typing import List, Dict, Any
+from datasets import load_dataset
+
+# START ImportEcommerceData
+from datasets import load_dataset
+
+
+def load_ecommerce_data():
+ """
+ Load the Weaviate ECommerce dataset from Hugging Face.
+ This dataset contains clothing items with pre-computed vectors.
+ """
+ # Load the dataset from Hugging Face
+ dataset = load_dataset(
+ "weaviate/agents", "query-agent-ecommerce", split="train", streaming=True
+ )
+
+ # Convert to list for easier handling
+ # Note: Limited to 100 items for demo purposes
+ # In production, process the full dataset or use batching
+ ecommerce_data = []
+ for i, item in enumerate(dataset):
+ if i >= 100: # Limit for demo - remove this for full dataset
+ break
+ ecommerce_data.append(
+ {"properties": item["properties"], "vector": item["vector"]}
+ )
+
+ return ecommerce_data
+
+
+# Load the data once for use in examples
+ecommerce_data = load_ecommerce_data()
+print(f"Loaded {len(ecommerce_data)} items from ECommerce dataset")
+# END ImportEcommerceData
+
+# ============================================
+# SHARED SETUP: STEPS 1-4
+# ============================================
+
+# START Method1Connect
+# Connect to Weaviate Cloud
+import os
+import weaviate
+from weaviate.auth import Auth
+
+# Best practice: store your credentials in environment variables
+weaviate_url = os.environ["WEAVIATE_URL"]
+weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
+
+client = weaviate.connect_to_weaviate_cloud(
+ cluster_url=weaviate_url,
+ auth_credentials=Auth.api_key(weaviate_api_key),
+)
+
+print(client.is_ready()) # Should print: `True`
+# END Method1Connect
+
+# START Method1CreateCollection
+# Create collection with original vector configuration
+client.collections.delete("ECommerceProducts") # Clean up if exists
+
+products = client.collections.create(
+ name="ECommerceProducts",
+ vector_config=[
+ Configure.Vectors.self_provided(
+ name="original_vector", # Name for existing vectors
+ vector_dimensions=768, # Dimension of the HuggingFace embeddings
+ )
+ ],
+ properties=[
+ wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
+ wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ ],
+)
+# END Method1CreateCollection
+
+# START Method1ImportData
+# Import data with existing vectors
+products = client.collections.use("ECommerceProducts")
+
+with products.batch.fixed_size(batch_size=200) as batch:
+ for item in ecommerce_data:
+ batch.add_object(
+ properties=item["properties"],
+ vector={"original_vector": item["vector"]}, # Use existing vectors
+ )
+
+failed_objects = products.batch.failed_objects
+if failed_objects:
+ print(f"Number of failed imports: {len(failed_objects)}")
+else:
+ print(f"Successfully imported {len(ecommerce_data)} products with original vectors")
+# END Method1ImportData
+
+# START Method1QueryOriginal
+# Query using original vectors
+products = client.collections.use("ECommerceProducts")
+
+# Use a vector from one of our items as a query vector
+# In production, this would be from your query encoder
+query_text = "comfortable athletic wear"
+# For demo: use the first item's vector as a query vector
+query_vector = ecommerce_data[0]["vector"]
+
+results = products.query.near_vector(
+ near_vector=query_vector,
+ target_vector="original_vector", # Specify which vector to search
+ limit=3,
+ return_properties=["name", "description", "price", "category"],
+)
+
+print("Search results with original vectors:")
+for obj in results.objects:
+ print(
+ f"- {obj.properties['name']} ({obj.properties['category']}): ${obj.properties['price']}"
+ )
+# END Method1QueryOriginal
+
+# ============================================
+# METHOD 1: NAMED VECTORS MIGRATION
+# ============================================
+
+# START Method1AddNewVector
+# Add a new named vector with Weaviate Embeddings
+from weaviate.classes.config import Reconfigure
+
+# Add new vector configuration to existing collection
+products.config.add_vector(
+ vector_config=Configure.Vectors.text2vec_weaviate( # Add new Weaviate Embeddings vector
+ name="weaviate_vector",
+ dimensions=768, # Weaviate Embeddings dimension
+ source_properties=["name", "description"], # Properties to vectorize
+ model_name="snowflake-arctic-embed-xs", # Or another Weaviate model
+ ),
+)
+
+print("Added new Weaviate Embeddings vector to collection")
+# END Method1AddNewVector
+
+# START Method1TriggerVectorization
+# Update all objects to trigger vectorization with new vectorizer
+products = client.collections.use("ECommerceProducts")
+
+# Fetch all objects
+all_objects = products.query.fetch_objects(limit=10000).objects
+
+# Update each object to trigger vectorization
+# We're not changing any properties, just triggering the update
+update_count = 0
+for obj in all_objects:
+ # Update with a minimal property change to trigger vectorization
+ products.data.update(
+ uuid=obj.uuid,
+ properties={
+ "name": obj.properties["name"], # Same value
+ },
+ )
+ update_count += 1
+
+ # Optional: Add delay to avoid rate limiting
+ if update_count % 100 == 0:
+ print(f"Updated {update_count} objects...")
+ time.sleep(0.1)
+
+print(f"Triggered vectorization for {update_count} objects")
+# END Method1TriggerVectorization
+
+# START Method1QueryNewVector
+# Query using the new Weaviate Embeddings vector
+products = client.collections.use("ECommerceProducts")
+
+# Now we can use text search with the new vector
+results = products.query.near_text(
+ query="comfortable athletic wear",
+ target_vector="weaviate_vector", # Use the new vector
+ limit=3,
+ return_properties=["name", "description", "price", "category"],
+)
+
+print("\nSearch results with Weaviate Embeddings:")
+for obj in results.objects:
+ print(
+ f"- {obj.properties['name']} ({obj.properties['category']}): ${obj.properties['price']}"
+ )
+
+# You can still query with the original vector
+# Use the first item's vector as query
+query_vector = ecommerce_data[0]["vector"]
+results_original = products.query.near_vector(
+ near_vector=query_vector,
+ target_vector="original_vector",
+ limit=3,
+ return_properties=["name", "category"],
+)
+
+print("\nComparison - Original vectors still work:")
+for obj in results_original.objects:
+ print(f"- {obj.properties['name']} ({obj.properties['category']})")
+# END Method1QueryNewVector
+
+# ============================================
+# METHOD 2: COLLECTION ALIASES MIGRATION
+# ============================================
+
+# For Method 2, we start with the same collection from Steps 1-4
+# but rename it to v1 for clarity
+
+# START Method2CreateOriginal
+# Rename/recreate as v1 for clarity in the alias method
+client.collections.delete("ECommerce_v1") # Clean up if exists
+
+products_v1 = client.collections.create(
+ name="ECommerce_v1",
+ vectorizer_config=Configure.Vectorizer.none(
+ vector_dimensions=768 # HuggingFace embedding dimensions
+ ),
+ properties=[
+ wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
+ wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ ],
+)
+
+# Import data with existing vectors
+products_v1 = client.collections.use("ECommerce_v1")
+
+with products_v1.batch.fixed_size(batch_size=200) as batch:
+ for item in ecommerce_data:
+ batch.add_object(
+ properties=item["properties"], vector=item["vector"] # Use existing vectors
+ )
+
+failed_objects = products_v1.batch.failed_objects
+if failed_objects:
+ print(f"Number of failed imports: {len(failed_objects)}")
+else:
+ print(f"Imported {len(ecommerce_data)} products to ECommerce_v1")
+# END Method2CreateOriginal
+
+# START Method2CreateAlias
+# Create an alias pointing to the current production collection
+client.alias.create(alias_name="ECommerceProduction", target_collection="ECommerce_v1")
+
+print("Created alias 'ECommerceProduction' -> 'ECommerce_v1'")
+# END Method2CreateAlias
+
+# START Method2QueryAlias
+# Your application always uses the alias name
+products = client.collections.use("ECommerceProduction")
+
+# Query using the alias (currently points to ECommerce_v1)
+# Use a vector from our dataset as query
+query_vector = ecommerce_data[0]["vector"]
+
+results = products.query.near_vector(
+ near_vector=query_vector, limit=3, return_properties=["name", "price", "category"]
+)
+
+print("Query results via alias:")
+for obj in results.objects:
+ print(
+ f"- {obj.properties['name']} ({obj.properties['category']}): ${obj.properties['price']}"
+ )
+# END Method2QueryAlias
+
+# START Method2CreateNew
+# Create new collection with Weaviate Embeddings vectorizer
+client.collections.delete("ECommerce_v2") # Clean up if exists
+
+products_v2 = client.collections.create(
+ name="ECommerce_v2",
+ vector_config=Configure.Vectors.text2vec_weaviate(
+ dimensions=768, # Weaviate Embeddings dimension
+ source_properties=["name", "description"], # Properties to vectorize
+ model_name="snowflake-arctic-embed-xs", # Or another Weaviate model
+ ),
+ properties=[
+ wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
+ wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
+ wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ ],
+)
+
+print("Created ECommerce_v2 with Weaviate Embeddings")
+# END Method2CreateNew
+
+# START Method2MigrateData
+# Migrate data to new collection (vectors will be auto-generated)
+products_v1 = client.collections.use("ECommerce_v1")
+products_v2 = client.collections.use("ECommerce_v2")
+
+# Fetch all data from v1
+all_products = products_v1.query.fetch_objects(limit=10000).objects
+
+# Import to v2 (without vectors - they'll be auto-generated)
+with products_v2.batch.fixed_size(batch_size=200) as batch:
+ for obj in all_products:
+ batch.add_object(
+ properties=obj.properties
+ # No vector provided - Weaviate Embeddings will generate it
+ )
+
+failed_objects = products_v2.batch.failed_objects
+if failed_objects:
+ print(f"Number of failed migrations: {len(failed_objects)}")
+else:
+ print(f"Migrated {len(all_products)} products to ECommerce_v2")
+# END Method2MigrateData
+
+# START Method2SwitchAlias
+# Switch the alias to the new collection (instant switch!)
+client.alias.update(
+ alias_name="ECommerceProduction", new_target_collection="ECommerce_v2"
+)
+
+print("Switched alias 'ECommerceProduction' -> 'ECommerce_v2'")
+
+# Now queries using the alias automatically use the new collection
+products = client.collections.use("ECommerceProduction")
+
+# Can now use text search (wasn't possible with self-provided vectors)
+results = products.query.near_text(
+ query="comfortable athletic wear",
+ limit=3,
+ return_properties=["name", "price", "category"],
+)
+
+print("\nQuery results after switch (now using Weaviate Embeddings):")
+for obj in results.objects:
+ print(
+ f"- {obj.properties['name']} ({obj.properties['category']}): ${obj.properties['price']}"
+ )
+# END Method2SwitchAlias
+
+# START Method2Cleanup
+# After verification, delete the old collection
+# Always verify everything works before cleanup!
+
+# Optional: Keep old collection for a rollback period
+print("Keeping ECommerce_v1 for 7 days as rollback option...")
+
+# When ready to clean up:
+# client.collections.delete("ECommerce_v1")
+# print("Deleted old collection ECommerce_v1")
+# END Method2Cleanup
+
+# ============================================
+# PRODUCTION EXAMPLE
+# ============================================
+
+
+# START ProductionExample
+class VectorizerMigration:
+ """Production-ready vectorizer migration with monitoring and rollback"""
+
+ def __init__(self, client: weaviate.Client):
+ self.client = client
+
+ def migrate_with_validation(
+ self,
+ source_collection: str,
+ target_collection: str,
+ alias_name: str,
+ test_queries: List[str],
+ rollback_threshold: float = 0.8,
+ ):
+ """
+ Migrate with quality validation and automatic rollback
+
+ Args:
+ source_collection: Original collection name
+ target_collection: New collection name
+ alias_name: Production alias name
+ test_queries: Queries to test quality
+ rollback_threshold: Min quality score to proceed
+ """
+ print(f"Starting migration from {source_collection} to {target_collection}")
+
+ # Step 1: Create new collection with new vectorizer
+ self._create_new_collection(target_collection)
+
+ # Step 2: Migrate data
+ migrated_count = self._migrate_data(source_collection, target_collection)
+ print(f"Migrated {migrated_count} objects")
+
+ # Step 3: Validate quality
+ quality_score = self._validate_quality(
+ source_collection, target_collection, test_queries
+ )
+ print(f"Quality score: {quality_score:.2%}")
+
+ # Step 4: Decision point
+ if quality_score >= rollback_threshold:
+ # Switch alias to new collection
+ self.client.alias.update(
+ alias_name=alias_name, new_target_collection=target_collection
+ )
+ print(f"✅ Migration successful! Alias now points to {target_collection}")
+ return True
+ else:
+ # Quality too low, don't switch
+ print(f"❌ Quality below threshold. Keeping {source_collection}")
+ # Optionally delete the new collection
+ self.client.collections.delete(target_collection)
+ return False
+
+ def _create_new_collection(self, collection_name: str):
+ """Create collection with Weaviate Embeddings"""
+ self.client.collections.create(
+ name=collection_name,
+ vector_config=Configure.Vectors.text2vec_weaviate(
+ dimensions=768,
+ source_properties=["name", "description"],
+ model_name="snowflake-arctic-embed-xs",
+ ),
+ properties=[
+ wvc.config.Property(
+ name="collection", data_type=wvc.config.DataType.TEXT
+ ),
+ wvc.config.Property(
+ name="category", data_type=wvc.config.DataType.TEXT
+ ),
+ wvc.config.Property(
+ name="tags", data_type=wvc.config.DataType.TEXT_ARRAY
+ ),
+ wvc.config.Property(
+ name="subcategory", data_type=wvc.config.DataType.TEXT
+ ),
+ wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(
+ name="description", data_type=wvc.config.DataType.TEXT
+ ),
+ wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
+ wvc.config.Property(
+ name="product_id", data_type=wvc.config.DataType.UUID
+ ),
+ wvc.config.Property(
+ name="colors", data_type=wvc.config.DataType.TEXT_ARRAY
+ ),
+ wvc.config.Property(
+ name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY
+ ),
+ wvc.config.Property(
+ name="image_url", data_type=wvc.config.DataType.TEXT
+ ),
+ wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ ],
+ )
+
+ def _migrate_data(self, source: str, target: str) -> int:
+ """Copy data from source to target collection"""
+ source_col = self.client.collections.use(source)
+ target_col = self.client.collections.use(target)
+
+ all_objects = source_col.query.fetch_objects(limit=10000).objects
+
+ with target_col.batch.fixed_size(batch_size=200) as batch:
+ for obj in all_objects:
+ batch.add_object(properties=obj.properties)
+
+ return len(all_objects)
+
+ def _validate_quality(
+ self, source: str, target: str, test_queries: List[str]
+ ) -> float:
+ """Compare search quality between collections"""
+ source_col = self.client.collections.use(source)
+ target_col = self.client.collections.use(target)
+
+ overlap_scores = []
+
+ for query in test_queries:
+ # Get results from both collections
+ # For source, we need to convert text to vector first
+ # (in production, you'd use your existing encoder)
+ # For demo, we'll skip this comparison
+
+ target_results = target_col.query.near_text(query=query, limit=10).objects
+
+ # Simple validation: check if we get results
+ if len(target_results) > 0:
+ overlap_scores.append(1.0)
+ else:
+ overlap_scores.append(0.0)
+
+ return sum(overlap_scores) / len(overlap_scores) if overlap_scores else 0.0
+
+
+# Usage example
+migration = VectorizerMigration(client)
+
+success = migration.migrate_with_validation(
+ source_collection="ECommerce_v1",
+ target_collection="ECommerce_v3",
+ alias_name="ECommerceProduction",
+ test_queries=[
+ "denim jeans",
+ "comfortable athletic wear",
+ "business casual outfit",
+ "summer dress",
+ ],
+ rollback_threshold=0.7,
+)
+
+if success:
+ print("Migration completed successfully!")
+else:
+ print("Migration rolled back due to quality issues")
+# END ProductionExample
+
+# Cleanup
+client.close()
diff --git a/docs/weaviate/tutorials/vectorizer-migration.mdx b/docs/weaviate/tutorials/vectorizer-migration.mdx
new file mode 100644
index 000000000..f392451b4
--- /dev/null
+++ b/docs/weaviate/tutorials/vectorizer-migration.mdx
@@ -0,0 +1,342 @@
+---
+title: Migrating between vectorizers
+description: Learn two approaches to migrate from one vectorizer to another in Weaviate without service interruption
+sidebar_position: 4
+image: og/docs/tutorials.jpg
+# tags: ['migration', 'vectorizers', 'embeddings', 'named-vectors', 'aliases']
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
+import PyCode from "!!raw-loader!/docs/weaviate/tutorials/_includes/vectorizer-migration.py";
+
+# Migrating vectorizers in Weaviate
+
+In this tutorial, we'll explore two powerful approaches to migrate from one vectorizer (embedding model) to another in Weaviate without service interruption. Whether you're upgrading to a better model, reducing costs, or switching providers, these methods ensure smooth transitions.
+
+## prerequisites
+
+Before starting this tutorial, ensure you have:
+
+- A Weaviate Cloud instance (version `v1.32` or newer)
+- Python 3.8+ installed
+- Required Python packages installed:
+ ```bash
+ pip install weaviate-client datasets
+ ```
+- Environment variables set for your Weaviate credentials:
+ ```bash
+ export WEAVIATE_URL="your-weaviate-cloud-url"
+ export WEAVIATE_API_KEY="your-api-key"
+ ```
+- Basic familiarity with Weaviate collections and vector search
+
+:::tip Get Started with Weaviate Cloud
+Sign up for a free Weaviate Cloud sandbox at [console.weaviate.cloud](https://console.weaviate.cloud)
+:::
+
+## introduction
+
+When working with vector databases in production, you may need to change your embedding model for various reasons:
+
+- **Performance improvements**: Newer models often provide better search accuracy
+- **Cost optimization**: Different models have different pricing structures
+- **Provider changes**: Switching between OpenAI, Cohere, Weaviate Embeddings, etc.
+- **Model deprecation**: When a model you're using is being retired
+
+This tutorial demonstrates two approaches:
+
+### method 1: named vectors (in-place migration)
+
+Named vectors allow multiple vector representations within the same collection. This method is ideal when you want to:
+
+- Test new models alongside existing ones
+- Gradually transition between models
+- Keep all data in one collection
+
+### method 2: collection aliases (blue-green deployment)
+
+Collection aliases enable instant switching between collections. This method is perfect when you want to:
+
+- Completely replace the vectorizer
+- Ensure rollback capability
+- Minimize risk during migration
+
+## setup: ecommerce dataset
+
+We'll use the Weaviate ECommerce dataset from Hugging Face, which contains clothing items with pre-computed embeddings. This dataset represents a real-world scenario where you have existing vector embeddings that need migration.
+
+First, install the required dependencies:
+
+```bash
+pip install weaviate-client datasets
+```
+
+The dataset includes:
+
+- Product information (name, description, category, price, brand, etc.)
+- Pre-computed 768-dimensional vectors
+- Over 1000 clothing items with detailed metadata
+
+
+
+## step 1: connect to weaviate cloud
+
+First, establish a connection to your Weaviate Cloud instance:
+
+
+
+## step 2: create a collection
+
+Create a collection that accepts self-provided vectors (your existing embeddings from the HuggingFace dataset):
+
+
+
+## step 3: import data
+
+Import your ecommerce data along with the pre-computed vectors:
+
+
+
+## step 4: query with original vectors
+
+Verify that searches work with your original vectors:
+
+
+
+## method 1: add new vector
+
+Named vectors allow you to have multiple vector representations in the same collection. This enables gradual migration and A/B testing of different models.
+
+### step 5: add new vector with Weaviate Embeddings
+
+Add a second named vector using Weaviate's built-in embeddings model:
+
+
+
+### step 6: trigger vectorization
+
+Update all objects to generate embeddings with the new vectorizer. We use a minimal update that doesn't change properties:
+
+
+
+### step 7: query with new vector
+
+Now you can query using either vector:
+
+
+
+### advantages of named vectors method
+
+- **Gradual migration**: Test new embeddings without affecting existing functionality
+- **A/B testing**: Compare search quality between models
+- **Single collection**: All data remains in one place
+- **Flexible queries**: Choose which vector to use at query time
+
+## method 2: collection aliases migration
+
+Collection aliases provide a blue-green deployment approach, allowing instant switching between collections with different vectorizers.
+
+### step 5: create collection alias and query using alias
+
+Create an alias that your application will use:
+
+
+
+Your application should always use the alias:
+
+
+
+### step 6: create new collection with Weaviate Embeddings
+
+Create a new collection using the Weaviate Embeddings vectorizer:
+
+
+
+### step 7: migrate data to new collection
+
+Copy data to the new collection (vectors will be auto-generated):
+
+
+
+### step 8: switch the alias and query using alias
+
+Update the alias to point to the new collection (instant switch):
+
+
+
+After verification, remove the old collection:
+
+
+
+### advantages of collection aliases method
+
+- **Instant switching**: Zero-downtime migration
+- **Easy rollback**: Switch back to old collection if issues arise
+- **Clean separation**: Old and new data are completely isolated
+- **No code changes**: Application continues using the same alias
+
+## choosing the right method and performance considerations
+
+### use named vectors when:
+
+- You want to **test multiple models** simultaneously
+- You need **gradual migration** with side-by-side comparison
+- You prefer keeping **all data in one collection**
+- You want to **experiment** with different search strategies
+- **Storage**: Each additional vector increases storage requirements
+- **Query performance**: Minimal overhead when selecting specific vectors
+- **Migration time**: Depends on update speed for triggering vectorization
+
+### use collection aliases when:
+
+- You need **instant, atomic switches** between models
+- You want **guaranteed rollback** capability
+- You prefer **complete isolation** between old and new setups
+- You're doing a **one-time migration** to a new model
+- **Storage**: Temporary duplication during migration
+- **Query performance**: No overhead - aliases are simple pointers
+- **Migration time**: Depends on data copy speed
+
+## best practices
+
+1. **Test thoroughly**: Always test the new vectorizer with a subset of data first
+2. **Monitor quality**: Compare search results between old and new models
+3. **Plan for rollback**: Keep the old setup available until you're confident
+4. **Consider costs**: Different vectorizers have different pricing models
+5. **Document changes**: Track which model versions you're using
+
+## complete example: production migration
+
+Here's a complete example showing a production-ready migration workflow:
+
+
+
+## troubleshooting
+
+### common issues and solutions
+
+**Issue**: Vectorization fails for some objects
+**Solution**: Check for empty or invalid text fields, ensure the vectorizer supports your data format
+
+**Issue**: Search quality degrades after migration
+**Solution**: Compare embedding dimensions, consider fine-tuning or trying different models
+
+**Issue**: Migration is too slow
+**Solution**: Use batch operations, parallelize updates, consider off-peak migration
+
+## summary
+
+This tutorial demonstrated two powerful approaches for migrating vectorizers in Weaviate:
+
+- **Named Vectors**: Best for gradual migration and testing multiple models
+- **Collection Aliases**: Best for instant switching and blue-green deployments
+
+Both methods ensure zero downtime and provide rollback capabilities, making them suitable for production environments.
+
+## running the code
+
+To run this tutorial:
+
+1. Set up your environment variables:
+
+ ```bash
+ export WEAVIATE_URL="your-weaviate-cloud-url"
+ export WEAVIATE_API_KEY="your-api-key"
+ ```
+
+2. Install dependencies:
+
+ ```bash
+ pip install weaviate-client datasets
+ ```
+
+3. Run either migration method from the Python scripts provided
+
+The code will automatically load the ECommerce dataset from Hugging Face and demonstrate both migration approaches.
+
+## further resources
+
+- [Collection Aliases Reference](../manage-collections/collection-aliases.mdx)
+
+## questions and feedback
+
+import DocsFeedback from "/_includes/docs-feedback.mdx";
+
+
diff --git a/sidebars.js b/sidebars.js
index da496f500..e7b27f7e3 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -525,6 +525,7 @@ const sidebars = {
},
items: [
"weaviate/tutorials/multi-vector-embeddings",
+ "weaviate/tutorials/vectorizer-migration",
//"weaviate/tutorials/import",
"weaviate/tutorials/cross-references",
//"weaviate/tutorials/vector-provision-options",
From 2ef1984cacfe836460907fd43ef0093698d856b9 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 09:40:43 +0200
Subject: [PATCH 02/11] Update tutorial
---
.../tutorials/vectorizer-migration.mdx | 164 +++++-------------
1 file changed, 45 insertions(+), 119 deletions(-)
diff --git a/docs/weaviate/tutorials/vectorizer-migration.mdx b/docs/weaviate/tutorials/vectorizer-migration.mdx
index f392451b4..4a7d622ae 100644
--- a/docs/weaviate/tutorials/vectorizer-migration.mdx
+++ b/docs/weaviate/tutorials/vectorizer-migration.mdx
@@ -15,7 +15,7 @@ import PyCode from "!!raw-loader!/docs/weaviate/tutorials/_includes/vectorizer-m
In this tutorial, we'll explore two powerful approaches to migrate from one vectorizer (embedding model) to another in Weaviate without service interruption. Whether you're upgrading to a better model, reducing costs, or switching providers, these methods ensure smooth transitions.
-## prerequisites
+## Prerequisites
Before starting this tutorial, ensure you have:
@@ -33,10 +33,12 @@ Before starting this tutorial, ensure you have:
- Basic familiarity with Weaviate collections and vector search
:::tip Get Started with Weaviate Cloud
+
Sign up for a free Weaviate Cloud sandbox at [console.weaviate.cloud](https://console.weaviate.cloud)
+
:::
-## introduction
+## Introduction
When working with vector databases in production, you may need to change your embedding model for various reasons:
@@ -47,46 +49,12 @@ When working with vector databases in production, you may need to change your em
This tutorial demonstrates two approaches:
-### method 1: named vectors (in-place migration)
-
-Named vectors allow multiple vector representations within the same collection. This method is ideal when you want to:
-
-- Test new models alongside existing ones
-- Gradually transition between models
-- Keep all data in one collection
-
-### method 2: collection aliases (blue-green deployment)
-
-Collection aliases enable instant switching between collections. This method is perfect when you want to:
-
-- Completely replace the vectorizer
-- Ensure rollback capability
-- Minimize risk during migration
-
-## setup: ecommerce dataset
-
-We'll use the Weaviate ECommerce dataset from Hugging Face, which contains clothing items with pre-computed embeddings. This dataset represents a real-world scenario where you have existing vector embeddings that need migration.
-
-First, install the required dependencies:
-
-```bash
-pip install weaviate-client datasets
-```
-
-The dataset includes:
-
-- Product information (name, description, category, price, brand, etc.)
-- Pre-computed 768-dimensional vectors
-- Over 1000 clothing items with detailed metadata
-
-
+- **Adding new vectors**
+ This method allows multiple vectors per data object within a single collection. It's ideal for testing new models alongside existing ones and keeping all the data in one collection.
+- **Collection aliases**
+ This approach uses aliases to instantly switch between separate collections. It's perfect for a complete model replacement, minimizing risk and providing an immediate rollback option.
-## step 1: connect to weaviate cloud
+## Step 1: Connect to Weaviate Cloud
First, establish a connection to your Weaviate Cloud instance:
@@ -97,7 +65,7 @@ First, establish a connection to your Weaviate Cloud instance:
language="py"
/>
-## step 2: create a collection
+## Step 2: Create a collection
Create a collection that accepts self-provided vectors (your existing embeddings from the HuggingFace dataset):
@@ -108,9 +76,23 @@ Create a collection that accepts self-provided vectors (your existing embeddings
language="py"
/>
-## step 3: import data
+## Step 3: Import data
-Import your ecommerce data along with the pre-computed vectors:
+We'll use the Weaviate ECommerce dataset from Hugging Face, which contains clothing items with pre-computed embeddings. This dataset represents a real-world scenario where you have existing vector embeddings that need migration.
+
+The dataset includes:
+
+- Product information (name, description, category, price, brand, etc.)
+- Pre-computed 768-dimensional vectors
+
+
+
+Import your e-commerce data along with the pre-computed vectors:
-## step 4: query with original vectors
+## Step 4: Query with original vectors
Verify that searches work with your original vectors:
@@ -130,11 +112,11 @@ Verify that searches work with your original vectors:
language="py"
/>
-## method 1: add new vector
+## Method 1: Add new vector
Named vectors allow you to have multiple vector representations in the same collection. This enables gradual migration and A/B testing of different models.
-### step 5: add new vector with Weaviate Embeddings
+### Step 5: Add new vector with Weaviate Embeddings
Add a second named vector using Weaviate's built-in embeddings model:
@@ -145,7 +127,7 @@ Add a second named vector using Weaviate's built-in embeddings model:
language="py"
/>
-### step 6: trigger vectorization
+### Step 6: Trigger vectorization
Update all objects to generate embeddings with the new vectorizer. We use a minimal update that doesn't change properties:
@@ -156,7 +138,7 @@ Update all objects to generate embeddings with the new vectorizer. We use a mini
language="py"
/>
-### step 7: query with new vector
+### Step 7: Query with new vector
Now you can query using either vector:
@@ -167,18 +149,11 @@ Now you can query using either vector:
language="py"
/>
-### advantages of named vectors method
-
-- **Gradual migration**: Test new embeddings without affecting existing functionality
-- **A/B testing**: Compare search quality between models
-- **Single collection**: All data remains in one place
-- **Flexible queries**: Choose which vector to use at query time
-
-## method 2: collection aliases migration
+## Method 2: Collection aliases migration
Collection aliases provide a blue-green deployment approach, allowing instant switching between collections with different vectorizers.
-### step 5: create collection alias and query using alias
+### Step 5: Create collection alias and query using alias
Create an alias that your application will use:
@@ -198,7 +173,7 @@ Your application should always use the alias:
language="py"
/>
-### step 6: create new collection with Weaviate Embeddings
+### Step 6: Create new collection with Weaviate Embeddings
Create a new collection using the Weaviate Embeddings vectorizer:
@@ -209,7 +184,7 @@ Create a new collection using the Weaviate Embeddings vectorizer:
language="py"
/>
-### step 7: migrate data to new collection
+### Step 7: Migrate data to new collection
Copy data to the new collection (vectors will be auto-generated):
@@ -220,7 +195,7 @@ Copy data to the new collection (vectors will be auto-generated):
language="py"
/>
-### step 8: switch the alias and query using alias
+### Step 8: Switch the alias and query using alias
Update the alias to point to the new collection (instant switch):
@@ -240,36 +215,21 @@ After verification, remove the old collection:
language="py"
/>
-### advantages of collection aliases method
-
-- **Instant switching**: Zero-downtime migration
-- **Easy rollback**: Switch back to old collection if issues arise
-- **Clean separation**: Old and new data are completely isolated
-- **No code changes**: Application continues using the same alias
-
-## choosing the right method and performance considerations
+## Choosing the right method
-### use named vectors when:
+Use **new vectors** when:
- You want to **test multiple models** simultaneously
-- You need **gradual migration** with side-by-side comparison
- You prefer keeping **all data in one collection**
- You want to **experiment** with different search strategies
-- **Storage**: Each additional vector increases storage requirements
-- **Query performance**: Minimal overhead when selecting specific vectors
-- **Migration time**: Depends on update speed for triggering vectorization
-### use collection aliases when:
+Use **collection aliases** when:
-- You need **instant, atomic switches** between models
-- You want **guaranteed rollback** capability
+- You want **rollback** capability
- You prefer **complete isolation** between old and new setups
- You're doing a **one-time migration** to a new model
-- **Storage**: Temporary duplication during migration
-- **Query performance**: No overhead - aliases are simple pointers
-- **Migration time**: Depends on data copy speed
-## best practices
+## Best practices
1. **Test thoroughly**: Always test the new vectorizer with a subset of data first
2. **Monitor quality**: Compare search results between old and new models
@@ -277,7 +237,7 @@ After verification, remove the old collection:
4. **Consider costs**: Different vectorizers have different pricing models
5. **Document changes**: Track which model versions you're using
-## complete example: production migration
+## Production migration example
Here's a complete example showing a production-ready migration workflow:
@@ -288,20 +248,7 @@ Here's a complete example showing a production-ready migration workflow:
language="py"
/>
-## troubleshooting
-
-### common issues and solutions
-
-**Issue**: Vectorization fails for some objects
-**Solution**: Check for empty or invalid text fields, ensure the vectorizer supports your data format
-
-**Issue**: Search quality degrades after migration
-**Solution**: Compare embedding dimensions, consider fine-tuning or trying different models
-
-**Issue**: Migration is too slow
-**Solution**: Use batch operations, parallelize updates, consider off-peak migration
-
-## summary
+## Summary
This tutorial demonstrated two powerful approaches for migrating vectorizers in Weaviate:
@@ -310,32 +257,11 @@ This tutorial demonstrated two powerful approaches for migrating vectorizers in
Both methods ensure zero downtime and provide rollback capabilities, making them suitable for production environments.
-## running the code
-
-To run this tutorial:
-
-1. Set up your environment variables:
-
- ```bash
- export WEAVIATE_URL="your-weaviate-cloud-url"
- export WEAVIATE_API_KEY="your-api-key"
- ```
-
-2. Install dependencies:
-
- ```bash
- pip install weaviate-client datasets
- ```
-
-3. Run either migration method from the Python scripts provided
-
-The code will automatically load the ECommerce dataset from Hugging Face and demonstrate both migration approaches.
-
-## further resources
+## Further resources
- [Collection Aliases Reference](../manage-collections/collection-aliases.mdx)
-## questions and feedback
+## Questions and feedback
import DocsFeedback from "/_includes/docs-feedback.mdx";
From a4573448300b89940f76f7836e0f0386b6350b00 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 24 Sep 2025 11:13:34 +0200
Subject: [PATCH 03/11] Update tutorial
---
.../_includes/vectorizer-migration.py | 321 +++---------------
.../tutorials/vectorizer-migration.mdx | 48 +--
2 files changed, 62 insertions(+), 307 deletions(-)
diff --git a/docs/weaviate/tutorials/_includes/vectorizer-migration.py b/docs/weaviate/tutorials/_includes/vectorizer-migration.py
index 559a38867..93262e81d 100644
--- a/docs/weaviate/tutorials/_includes/vectorizer-migration.py
+++ b/docs/weaviate/tutorials/_includes/vectorizer-migration.py
@@ -1,12 +1,3 @@
-import os
-import weaviate
-import weaviate.classes as wvc
-from weaviate.auth import Auth
-from weaviate.classes.config import Configure
-import time
-from typing import List, Dict, Any
-from datasets import load_dataset
-
# START ImportEcommerceData
from datasets import load_dataset
@@ -62,31 +53,32 @@ def load_ecommerce_data():
print(client.is_ready()) # Should print: `True`
# END Method1Connect
-# START Method1CreateCollection
-# Create collection with original vector configuration
client.collections.delete("ECommerceProducts") # Clean up if exists
+# START Method1CreateCollection
+from weaviate.classes.config import Configure, DataType, Property
+
+# Create collection with original vector configuration
products = client.collections.create(
name="ECommerceProducts",
vector_config=[
Configure.Vectors.self_provided(
name="original_vector", # Name for existing vectors
- vector_dimensions=768, # Dimension of the HuggingFace embeddings
)
],
properties=[
- wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
- wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ Property(name="collection", data_type=DataType.TEXT),
+ Property(name="category", data_type=DataType.TEXT),
+ Property(name="tags", data_type=DataType.TEXT_ARRAY),
+ Property(name="subcategory", data_type=DataType.TEXT),
+ Property(name="name", data_type=DataType.TEXT),
+ Property(name="description", data_type=DataType.TEXT),
+ Property(name="brand", data_type=DataType.TEXT),
+ Property(name="product_id", data_type=DataType.UUID),
+ Property(name="colors", data_type=DataType.TEXT_ARRAY),
+ Property(name="reviews", data_type=DataType.TEXT_ARRAY),
+ Property(name="image_url", data_type=DataType.TEXT),
+ Property(name="price", data_type=DataType.NUMBER),
],
)
# END Method1CreateCollection
@@ -139,15 +131,13 @@ def load_ecommerce_data():
# START Method1AddNewVector
# Add a new named vector with Weaviate Embeddings
-from weaviate.classes.config import Reconfigure
+from weaviate.classes.config import Configure
# Add new vector configuration to existing collection
products.config.add_vector(
vector_config=Configure.Vectors.text2vec_weaviate( # Add new Weaviate Embeddings vector
- name="weaviate_vector",
- dimensions=768, # Weaviate Embeddings dimension
+ name="new_vector",
source_properties=["name", "description"], # Properties to vectorize
- model_name="snowflake-arctic-embed-xs", # Or another Weaviate model
),
)
@@ -174,11 +164,6 @@ def load_ecommerce_data():
)
update_count += 1
- # Optional: Add delay to avoid rate limiting
- if update_count % 100 == 0:
- print(f"Updated {update_count} objects...")
- time.sleep(0.1)
-
print(f"Triggered vectorization for {update_count} objects")
# END Method1TriggerVectorization
@@ -189,7 +174,7 @@ def load_ecommerce_data():
# Now we can use text search with the new vector
results = products.query.near_text(
query="comfortable athletic wear",
- target_vector="weaviate_vector", # Use the new vector
+ target_vector="new_vector", # Use the new vector
limit=3,
return_properties=["name", "description", "price", "category"],
)
@@ -220,99 +205,60 @@ def load_ecommerce_data():
# ============================================
# For Method 2, we start with the same collection from Steps 1-4
-# but rename it to v1 for clarity
-
-# START Method2CreateOriginal
-# Rename/recreate as v1 for clarity in the alias method
-client.collections.delete("ECommerce_v1") # Clean up if exists
-
-products_v1 = client.collections.create(
- name="ECommerce_v1",
- vectorizer_config=Configure.Vectorizer.none(
- vector_dimensions=768 # HuggingFace embedding dimensions
- ),
- properties=[
- wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
- wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
- ],
-)
-
-# Import data with existing vectors
-products_v1 = client.collections.use("ECommerce_v1")
-
-with products_v1.batch.fixed_size(batch_size=200) as batch:
- for item in ecommerce_data:
- batch.add_object(
- properties=item["properties"], vector=item["vector"] # Use existing vectors
- )
-
-failed_objects = products_v1.batch.failed_objects
-if failed_objects:
- print(f"Number of failed imports: {len(failed_objects)}")
-else:
- print(f"Imported {len(ecommerce_data)} products to ECommerce_v1")
-# END Method2CreateOriginal
+client.alias.delete(alias_name="ECommerceProduction") # Clean up if exists
# START Method2CreateAlias
# Create an alias pointing to the current production collection
-client.alias.create(alias_name="ECommerceProduction", target_collection="ECommerce_v1")
-
-print("Created alias 'ECommerceProduction' -> 'ECommerce_v1'")
+client.alias.create(
+ alias_name="ECommerceProduction", target_collection="ECommerceProducts"
+)
# END Method2CreateAlias
# START Method2QueryAlias
# Your application always uses the alias name
products = client.collections.use("ECommerceProduction")
-# Query using the alias (currently points to ECommerce_v1)
+# Query using the alias (currently points to ECommerceProducts)
# Use a vector from our dataset as query
query_vector = ecommerce_data[0]["vector"]
results = products.query.near_vector(
- near_vector=query_vector, limit=3, return_properties=["name", "price", "category"]
+ near_vector=query_vector,
+ target_vector=["original_vector"],
+ limit=3,
+ return_properties=["name", "price"],
)
print("Query results via alias:")
for obj in results.objects:
- print(
- f"- {obj.properties['name']} ({obj.properties['category']}): ${obj.properties['price']}"
- )
+ print(f"{obj.properties['name']}: ${obj.properties['price']}")
# END Method2QueryAlias
# START Method2CreateNew
+from weaviate.classes.config import Configure, DataType, Property
+
# Create new collection with Weaviate Embeddings vectorizer
client.collections.delete("ECommerce_v2") # Clean up if exists
products_v2 = client.collections.create(
name="ECommerce_v2",
vector_config=Configure.Vectors.text2vec_weaviate(
- dimensions=768, # Weaviate Embeddings dimension
+ name="new_vector",
source_properties=["name", "description"], # Properties to vectorize
- model_name="snowflake-arctic-embed-xs", # Or another Weaviate model
),
properties=[
- wvc.config.Property(name="collection", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="tags", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="subcategory", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="description", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="product_id", data_type=wvc.config.DataType.UUID),
- wvc.config.Property(name="colors", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY),
- wvc.config.Property(name="image_url", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
+ Property(name="collection", data_type=DataType.TEXT),
+ Property(name="category", data_type=DataType.TEXT),
+ Property(name="tags", data_type=DataType.TEXT_ARRAY),
+ Property(name="subcategory", data_type=DataType.TEXT),
+ Property(name="name", data_type=DataType.TEXT),
+ Property(name="description", data_type=DataType.TEXT),
+ Property(name="brand", data_type=DataType.TEXT),
+ Property(name="product_id", data_type=DataType.UUID),
+ Property(name="colors", data_type=DataType.TEXT_ARRAY),
+ Property(name="reviews", data_type=DataType.TEXT_ARRAY),
+ Property(name="image_url", data_type=DataType.TEXT),
+ Property(name="price", data_type=DataType.NUMBER),
],
)
@@ -321,7 +267,7 @@ def load_ecommerce_data():
# START Method2MigrateData
# Migrate data to new collection (vectors will be auto-generated)
-products_v1 = client.collections.use("ECommerce_v1")
+products_v1 = client.collections.use("ECommerceProducts")
products_v2 = client.collections.use("ECommerce_v2")
# Fetch all data from v1
@@ -356,6 +302,7 @@ def load_ecommerce_data():
# Can now use text search (wasn't possible with self-provided vectors)
results = products.query.near_text(
query="comfortable athletic wear",
+ target_vector="new_vector",
limit=3,
return_properties=["name", "price", "category"],
)
@@ -367,181 +314,5 @@ def load_ecommerce_data():
)
# END Method2SwitchAlias
-# START Method2Cleanup
-# After verification, delete the old collection
-# Always verify everything works before cleanup!
-
-# Optional: Keep old collection for a rollback period
-print("Keeping ECommerce_v1 for 7 days as rollback option...")
-
-# When ready to clean up:
-# client.collections.delete("ECommerce_v1")
-# print("Deleted old collection ECommerce_v1")
-# END Method2Cleanup
-
-# ============================================
-# PRODUCTION EXAMPLE
-# ============================================
-
-
-# START ProductionExample
-class VectorizerMigration:
- """Production-ready vectorizer migration with monitoring and rollback"""
-
- def __init__(self, client: weaviate.Client):
- self.client = client
-
- def migrate_with_validation(
- self,
- source_collection: str,
- target_collection: str,
- alias_name: str,
- test_queries: List[str],
- rollback_threshold: float = 0.8,
- ):
- """
- Migrate with quality validation and automatic rollback
-
- Args:
- source_collection: Original collection name
- target_collection: New collection name
- alias_name: Production alias name
- test_queries: Queries to test quality
- rollback_threshold: Min quality score to proceed
- """
- print(f"Starting migration from {source_collection} to {target_collection}")
-
- # Step 1: Create new collection with new vectorizer
- self._create_new_collection(target_collection)
-
- # Step 2: Migrate data
- migrated_count = self._migrate_data(source_collection, target_collection)
- print(f"Migrated {migrated_count} objects")
-
- # Step 3: Validate quality
- quality_score = self._validate_quality(
- source_collection, target_collection, test_queries
- )
- print(f"Quality score: {quality_score:.2%}")
-
- # Step 4: Decision point
- if quality_score >= rollback_threshold:
- # Switch alias to new collection
- self.client.alias.update(
- alias_name=alias_name, new_target_collection=target_collection
- )
- print(f"✅ Migration successful! Alias now points to {target_collection}")
- return True
- else:
- # Quality too low, don't switch
- print(f"❌ Quality below threshold. Keeping {source_collection}")
- # Optionally delete the new collection
- self.client.collections.delete(target_collection)
- return False
-
- def _create_new_collection(self, collection_name: str):
- """Create collection with Weaviate Embeddings"""
- self.client.collections.create(
- name=collection_name,
- vector_config=Configure.Vectors.text2vec_weaviate(
- dimensions=768,
- source_properties=["name", "description"],
- model_name="snowflake-arctic-embed-xs",
- ),
- properties=[
- wvc.config.Property(
- name="collection", data_type=wvc.config.DataType.TEXT
- ),
- wvc.config.Property(
- name="category", data_type=wvc.config.DataType.TEXT
- ),
- wvc.config.Property(
- name="tags", data_type=wvc.config.DataType.TEXT_ARRAY
- ),
- wvc.config.Property(
- name="subcategory", data_type=wvc.config.DataType.TEXT
- ),
- wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(
- name="description", data_type=wvc.config.DataType.TEXT
- ),
- wvc.config.Property(name="brand", data_type=wvc.config.DataType.TEXT),
- wvc.config.Property(
- name="product_id", data_type=wvc.config.DataType.UUID
- ),
- wvc.config.Property(
- name="colors", data_type=wvc.config.DataType.TEXT_ARRAY
- ),
- wvc.config.Property(
- name="reviews", data_type=wvc.config.DataType.TEXT_ARRAY
- ),
- wvc.config.Property(
- name="image_url", data_type=wvc.config.DataType.TEXT
- ),
- wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
- ],
- )
-
- def _migrate_data(self, source: str, target: str) -> int:
- """Copy data from source to target collection"""
- source_col = self.client.collections.use(source)
- target_col = self.client.collections.use(target)
-
- all_objects = source_col.query.fetch_objects(limit=10000).objects
-
- with target_col.batch.fixed_size(batch_size=200) as batch:
- for obj in all_objects:
- batch.add_object(properties=obj.properties)
-
- return len(all_objects)
-
- def _validate_quality(
- self, source: str, target: str, test_queries: List[str]
- ) -> float:
- """Compare search quality between collections"""
- source_col = self.client.collections.use(source)
- target_col = self.client.collections.use(target)
-
- overlap_scores = []
-
- for query in test_queries:
- # Get results from both collections
- # For source, we need to convert text to vector first
- # (in production, you'd use your existing encoder)
- # For demo, we'll skip this comparison
-
- target_results = target_col.query.near_text(query=query, limit=10).objects
-
- # Simple validation: check if we get results
- if len(target_results) > 0:
- overlap_scores.append(1.0)
- else:
- overlap_scores.append(0.0)
-
- return sum(overlap_scores) / len(overlap_scores) if overlap_scores else 0.0
-
-
-# Usage example
-migration = VectorizerMigration(client)
-
-success = migration.migrate_with_validation(
- source_collection="ECommerce_v1",
- target_collection="ECommerce_v3",
- alias_name="ECommerceProduction",
- test_queries=[
- "denim jeans",
- "comfortable athletic wear",
- "business casual outfit",
- "summer dress",
- ],
- rollback_threshold=0.7,
-)
-
-if success:
- print("Migration completed successfully!")
-else:
- print("Migration rolled back due to quality issues")
-# END ProductionExample
-
# Cleanup
client.close()
diff --git a/docs/weaviate/tutorials/vectorizer-migration.mdx b/docs/weaviate/tutorials/vectorizer-migration.mdx
index 4a7d622ae..a6fc6fece 100644
--- a/docs/weaviate/tutorials/vectorizer-migration.mdx
+++ b/docs/weaviate/tutorials/vectorizer-migration.mdx
@@ -1,5 +1,5 @@
---
-title: Migrating between vectorizers
+title: Switching vectorizers
description: Learn two approaches to migrate from one vectorizer to another in Weaviate without service interruption
sidebar_position: 4
image: og/docs/tutorials.jpg
@@ -11,28 +11,28 @@ import TabItem from "@theme/TabItem";
import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
import PyCode from "!!raw-loader!/docs/weaviate/tutorials/_includes/vectorizer-migration.py";
-# Migrating vectorizers in Weaviate
+# Switching vectorizers in Weaviate
-In this tutorial, we'll explore two powerful approaches to migrate from one vectorizer (embedding model) to another in Weaviate without service interruption. Whether you're upgrading to a better model, reducing costs, or switching providers, these methods ensure smooth transitions.
+This tutorial demonstrates two methods for migrating a Weaviate collection to a new vectorizer (embedding model) with minimal disruption to ongoing services. These techniques are helpful for scenarios such as model upgrades, provider changes, or performance optimization.
## Prerequisites
Before starting this tutorial, ensure you have:
-- A Weaviate Cloud instance (version `v1.32` or newer)
+- A [Weaviate Cloud](https://console.weaviate.cloud) instance (version `v1.32` or newer)
- Python 3.8+ installed
- Required Python packages installed:
```bash
pip install weaviate-client datasets
```
-- Environment variables set for your Weaviate credentials:
+- Environment variables set for your Weaviate Cloud credentials:
```bash
export WEAVIATE_URL="your-weaviate-cloud-url"
export WEAVIATE_API_KEY="your-api-key"
```
- Basic familiarity with Weaviate collections and vector search
-:::tip Get Started with Weaviate Cloud
+:::tip Get started with Weaviate Cloud
Sign up for a free Weaviate Cloud sandbox at [console.weaviate.cloud](https://console.weaviate.cloud)
@@ -40,14 +40,9 @@ Sign up for a free Weaviate Cloud sandbox at [console.weaviate.cloud](https://co
## Introduction
-When working with vector databases in production, you may need to change your embedding model for various reasons:
+In a production environment, you might need to change your embedding model for several reasons. You may want to adopt a newer model for **performance improvements** like better search accuracy, or switch models due to the **deprecation** of your current model.
-- **Performance improvements**: Newer models often provide better search accuracy
-- **Cost optimization**: Different models have different pricing structures
-- **Provider changes**: Switching between OpenAI, Cohere, Weaviate Embeddings, etc.
-- **Model deprecation**: When a model you're using is being retired
-
-This tutorial demonstrates two approaches:
+This tutorial demonstrates two approaches for switching vectorizers:
- **Adding new vectors**
This method allows multiple vectors per data object within a single collection. It's ideal for testing new models alongside existing ones and keeping all the data in one collection.
@@ -67,7 +62,7 @@ First, establish a connection to your Weaviate Cloud instance:
## Step 2: Create a collection
-Create a collection that accepts self-provided vectors (your existing embeddings from the HuggingFace dataset):
+Create a collection that accepts self-provided vectors. We will use the existing embeddings from the [HuggingFace e-commerce dataset](https://huggingface.co/datasets/weaviate/agents/viewer/query-agent-ecommerce):
-## Method 1: Add new vector
+## Method A: Add new vector
-Named vectors allow you to have multiple vector representations in the same collection. This enables gradual migration and A/B testing of different models.
+Named vectors allow you to have multiple vector representations in the same collection. Once a new vector is created and all the objects in the database are vectorized, you can use the new vector instead of the original one.
### Step 5: Add new vector with Weaviate Embeddings
-Add a second named vector using Weaviate's built-in embeddings model:
+Add a new vector using Weaviate's built-in embedding service [Weaviate Embeddings](/cloud/embeddings):
-## Method 2: Collection aliases migration
+## Method B: Collection aliases migration
-Collection aliases provide a blue-green deployment approach, allowing instant switching between collections with different vectorizers.
+Collection aliases allow instant switching between collections with different vectorizers.
### Step 5: Create collection alias and query using alias
@@ -197,7 +192,7 @@ Copy data to the new collection (vectors will be auto-generated):
### Step 8: Switch the alias and query using alias
-Update the alias to point to the new collection (instant switch):
+Update the alias to point to the new collection:
-
## Summary
This tutorial demonstrated two powerful approaches for migrating vectorizers in Weaviate:
From 858094a4cbc15e9a4ca24a4e0ada68083c4052fe Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 7 Oct 2025 13:05:30 +0200
Subject: [PATCH 04/11] Update docs
---
_includes/embedding-model-providers.mdx | 23 +++++++++
docs/cloud/quickstart.mdx | 10 ----
docs/weaviate/quickstart/index.md | 40 ++-------------
docs/weaviate/quickstart/local.md | 29 ++---------
.../tutorials/_includes/add_new_vector.png | Bin 0 -> 354223 bytes
.../switch-vectorizer-collection-alias.png | Bin 0 -> 483878 bytes
.../_includes/vectorizer-migration.py | 5 ++
.../tutorials/vectorizer-migration.mdx | 47 ++++++++++++++----
8 files changed, 71 insertions(+), 83 deletions(-)
create mode 100644 _includes/embedding-model-providers.mdx
create mode 100644 docs/weaviate/tutorials/_includes/add_new_vector.png
create mode 100644 docs/weaviate/tutorials/_includes/switch-vectorizer-collection-alias.png
diff --git a/_includes/embedding-model-providers.mdx b/_includes/embedding-model-providers.mdx
new file mode 100644
index 000000000..0bb4bbf24
--- /dev/null
+++ b/_includes/embedding-model-providers.mdx
@@ -0,0 +1,23 @@
+If you prefer a different model provider integration, or prefer to import your own vectors, see one of the following guides:
+
+import CardsSection from "/src/components/CardsSection";
+import styles from "/src/components/CardsSection/styles.module.scss";
+
+export const specificGuidesData = [
+ {
+ title: "Prefer a different model provider?",
+ description:
+ "See the embedding model providers page for information on other available vectorizers, such as AWS, Cohere, Google, and many more.",
+ link: "/weaviate/model-providers",
+ icon: "fas fa-puzzle-piece", // Icon representing data management
+ },
+ {
+ title: "You have precomputed embeddings?",
+ description:
+ "If you prefer to add custom vectors yourself along with the object data, see the Bring Your Own Vectors starter guide.",
+ link: "/weaviate/starter-guides/custom-vectors",
+ icon: "fas fa-project-diagram", // Icon representing vector relationships/structure
+ },
+];
+
+
diff --git a/docs/cloud/quickstart.mdx b/docs/cloud/quickstart.mdx
index 934a1bafe..91fe665d4 100644
--- a/docs/cloud/quickstart.mdx
+++ b/docs/cloud/quickstart.mdx
@@ -214,16 +214,6 @@ import CreateCollection from '/_includes/code/quickstart/quickstart.create_colle
Run this code to create the collection to which you can add data.
-:::info What models are being used?
-
-You can optionally specify the model in the collection definition. As we did not specify models in the collection definition above, these integrations will use the Weaviate-defined default models.
-
-
-
-See the [model providers integration](/weaviate/model-providers/index.md) section for more information.
-
-:::
-
### 2.2 Load the data
We can now add data to our collection.
diff --git a/docs/weaviate/quickstart/index.md b/docs/weaviate/quickstart/index.md
index 1fec0001f..d63897a63 100644
--- a/docs/weaviate/quickstart/index.md
+++ b/docs/weaviate/quickstart/index.md
@@ -137,7 +137,7 @@ You can retrieve them both from the [WCD console](https://console.weaviate.cloud
:::note
-New clusters with Weaviate version `v1.30` (or later) have [RBAC (Role-Based Access Control)](/weaviate/configuration/rbac/index.mdx) enabled by default. These clusters don't come with API keys, you will need to create an API key yourself and assign it a role (`admin`, `viewer` or a custom role).
+New clusters with Weaviate version `v1.30` (or later) have [RBAC (Role-Based Access Control)](/weaviate/configuration/rbac/index.mdx) enabled by default. These clusters don't come with API keys, you will need to create an API key yourself and assign it a role (`admin`, `viewer` or a custom role).
:::
@@ -200,43 +200,11 @@ import CreateCollection from '/\_includes/code/quickstart/quickstart.create_coll
Run this code to create the collection to which you can add data.
-:::info What models are being used?
-
-You can optionally specify the model in the collection definition. As we did not specify models in the collection definition above, these integrations will use the Weaviate-defined default models.
-
-
-See the [model providers integration](../model-providers/index.md) section for more information.
-
-:::
+import ModelProvider from '/\_includes/embedding-model-providers.mdx'
Do you prefer a different setup?
-
-Weaviate is very flexible. If you prefer a different model provider integration, or prefer to import your own vectors, see one of the following guides:
-
-
-
-
-
-
Prefer a different model provider?
-
-
- See this section for information on how to user another provider, such as AWS, Cohere, Google, and many more.
-
-
-
-
-
-
-
Want to specify object vectors?
-
-
- If you prefer to add vectors yourself along with the object data, see Starter Guide: Bring Your Own Vectors.
-
-
-
-
-
+
### 2.2 Add objects
@@ -405,7 +373,7 @@ flowchart LR
style sg3 fill:#ffffff,stroke:#130C49,stroke-width:2px,color:#130C49
```
-The following example combines the same search (for `biology`) with a prompt to generate a tweet.
+The following example combines the same search (for `biology`) with a prompt to generate a tweet.
import QueryRAG from '/\_includes/code/quickstart/quickstart.query.rag.mdx'
diff --git a/docs/weaviate/quickstart/local.md b/docs/weaviate/quickstart/local.md
index 6ed3e07ac..1610c366c 100644
--- a/docs/weaviate/quickstart/local.md
+++ b/docs/weaviate/quickstart/local.md
@@ -169,34 +169,11 @@ import CreateCollection from '/_includes/code/quickstart/local.quickstart.create
Run this code to create the collection to which you can add data.
+import ModelProvider from '/\_includes/embedding-model-providers.mdx'
+
Do you prefer a different setup?
-
-Weaviate is very flexible. If you prefer a different model provider integration, or prefer to import your own vectors, see one of the following guides:
-
-
-
-
-
-
Prefer a different model provider?
-
-
- See this section for information on how to user another provider, such as AWS, Cohere, Google, and many more.
-
-
-
-
-
-
-
Want to specify object vectors?
-
-
- If you prefer to add vectors yourself along with the object data, see Starter Guide: Bring Your Own Vectors.
-