Weaviate

Weaviate's object-centric model

Most vector databases store vectors and then attach metadata as a side-car. Weaviate flips this: the primary unit is a typed object with properties — the vector is derived from the object's content automatically if you configure a vectoriser module. This means you can insert raw text and Weaviate handles embedding on ingestion, without your application managing the embed API call.

The tradeoff: auto-vectorisation couples your data pipeline to Weaviate's model integrations. For maximum control over embeddings (custom models, batch optimisation), providing your own vectors is usually better.

Quick start with embedded Weaviate

pip install weaviate-client

import weaviate
import weaviate.classes as wvc

# Embedded Weaviate (in-process, good for dev/testing)
with weaviate.connect_to_embedded() as client:
    print(client.is_ready())   # True

# Weaviate Cloud or local Docker
client = weaviate.connect_to_wcs(
    cluster_url="https://your-cluster.weaviate.network",
    auth_credentials=weaviate.auth.AuthApiKey("your-api-key")
)

# Local Docker: docker run -p 8080:8080 semitechnologies/weaviate:latest
client = weaviate.connect_to_local()

Schema and collections

import weaviate
import weaviate.classes as wvc
from weaviate.classes.config import Property, DataType, Configure

client = weaviate.connect_to_local()

# Create a collection with explicit schema + bring-your-own vectors
client.collections.create(
    name="Article",
    properties=[
        Property(name="title",   data_type=DataType.TEXT),
        Property(name="content", data_type=DataType.TEXT),
        Property(name="source",  data_type=DataType.TEXT),
    ],
    vectorizer_config=Configure.Vectorizer.none()   # we'll provide vectors ourselves
)

collection = client.collections.get("Article")
print(collection.config.get())

Inserting and searching objects

from openai import OpenAI
import weaviate, weaviate.classes as wvc

client = weaviate.connect_to_local()
oai = OpenAI()
collection = client.collections.get("Article")

def embed(text):
    return oai.embeddings.create(input=[text], model="text-embedding-3-small").data[0].embedding

# Insert with explicit vector
docs = [
    {"title": "Return Policy", "content": "Refunds accepted within 30 days.", "source": "faq"},
    {"title": "Shipping Info", "content": "Free shipping on orders over $50.", "source": "faq"},
]
with collection.batch.dynamic() as batch:
    for doc in docs:
        batch.add_object(
            properties={"title": doc["title"], "content": doc["content"], "source": doc["source"]},
            vector=embed(doc["content"])
        )

# Vector search
query_vector = embed("What is the refund policy?")
results = collection.query.near_vector(
    near_vector=query_vector,
    limit=3,
    return_metadata=wvc.query.MetadataQuery(score=True)
)
for obj in results.objects:
    print(f"Score {obj.metadata.score:.3f}: {obj.properties['content']}")

Hybrid search

from weaviate.classes.query import HybridFusion

results = collection.query.hybrid(
    query="return policy refund",      # used for BM25 keyword search
    vector=embed("return policy"),     # used for vector search
    alpha=0.5,                         # 0=keyword only, 1=vector only, 0.5=balanced
    fusion_type=HybridFusion.RELATIVE_SCORE,
    limit=5,
    return_metadata=wvc.query.MetadataQuery(score=True)
)
for obj in results.objects:
    print(f"Score {obj.metadata.score:.3f}: {obj.properties['content']}")

alpha=0.5 gives equal weight to BM25 and vector scores. Increase alpha for semantic-heavy queries, decrease it for keyword-heavy queries. RELATIVE_SCORE fusion normalises both score distributions before combining — usually better than RANKED fusion for production.

Multi-tenancy

from weaviate.classes.config import Configure

# Enable multi-tenancy on collection creation
client.collections.create(
    name="UserDocs",
    multi_tenancy_config=Configure.multi_tenancy(enabled=True),
    vectorizer_config=Configure.Vectorizer.none()
)

collection = client.collections.get("UserDocs")

# Create tenants
collection.tenants.create([
    wvc.tenants.Tenant(name="tenant-alice"),
    wvc.tenants.Tenant(name="tenant-bob"),
])

# Insert into a specific tenant
tenant_collection = collection.with_tenant("tenant-alice")
tenant_collection.data.insert(
    properties={"content": "Alice's private document."},
    vector=embed("Alice's private document.")
)

# Query — only returns Alice's data
results = tenant_collection.query.near_vector(vector=embed("private"), limit=5)

Gotchas

Collection name capitalisation. Weaviate requires collection names to start with an uppercase letter. article will fail; Article works.

Schema migrations are destructive. Changing a property's data type requires deleting and recreating the collection. Plan your schema before ingesting large datasets.

Batch error handling. The batch.dynamic() context manager silently swallows individual item errors. After ingestion, check collection.batch.failed_objects to detect partial failures.

gRPC for bulk ingestion. The v4 client uses gRPC for batch operations by default — much faster than REST for large ingestion jobs. Make sure port 50051 is open if running a self-hosted Weaviate.