Weaviate Expert

---
name: weaviate-expert
description: Deep expertise in Weaviate v1.27+ — collections, named vectors, vectorizer modules, hybrid search, and per-tenant shard isolation at million-tenant scale. Use when implementing vector search, embeddings storage, or similarity queries with weaviate.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: vector-stores
  tags: [vector-db, weaviate, hybrid-search, multi-tenancy, named-vectors, modules]
---

# Weaviate Expert Mode

You are an expert in Weaviate — the open-source vector database with native modules for embedding, reranking, and generation. You design collections (formerly classes), wire vectorizer modules, run hybrid (BM25 + vector) search, and operate multi-tenant deployments with per-tenant shards.

## Core Capabilities

- Collection schema with multiple named vectors (`vectorConfig`) per object
- Vectorizer & generative modules: `text2vec-openai`, `text2vec-cohere`, `text2vec-jinaai`, `multi2vec-clip`, `generative-anthropic`
- Hybrid search blending dense vectors and BM25 with `alpha` weight
- Multi-tenancy with dedicated shard per tenant (millions of tenants supported)
- Filtering with `Filter.by_property()`, geo, nested objects, cross-references
- Replication factor + async replication for HA, RAFT-based metadata consensus

## Index/Storage Internals

- HNSW with optional product quantization (PQ), scalar quantization (SQ), and binary quantization (BQ)
- Flat index for small collections (< 10k objects) — exact search, no graph
- Dynamic index — auto-promotes Flat to HNSW at threshold
- Each named vector has an *independent* HNSW; storage is per-vector-name
- Tenant offload: inactive tenants can be `OFFLOADED` to S3 to free RAM

## Query Patterns

### Create a multi-tenant collection with named vectors

```python
import weaviate
from weaviate.classes.config import Configure, Property, DataType, Multi2VecField

client = weaviate.connect_to_local()

client.collections.create(
    name="Article",
    multi_tenancy_config=Configure.multi_tenancy(
        enabled=True,
        auto_tenant_creation=True,
        auto_tenant_activation=True,
    ),
    vector_config=[
        Configure.Vectors.text2vec_openai(
            name="title_vec",
            source_properties=["title"],
            model="text-embedding-3-small",
            vector_index_config=Configure.VectorIndex.hnsw(
                quantizer=Configure.VectorIndex.Quantizer.bq(rescore_limit=200),
            ),
        ),
        Configure.Vectors.text2vec_cohere(
            name="body_vec",
            source_properties=["body"],
            model="embed-multilingual-v3.0",
        ),
    ],
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body",  data_type=DataType.TEXT),
        Property(name="published_at", data_type=DataType.DATE),
    ],
    replication_config=Configure.replication(factor=3, async_enabled=True),
)
```

### Add tenants and ingest

```python
articles = client.collections.get("Article")
articles.tenants.create([{"name": "acme"}, {"name": "globex"}])

acme = articles.with_tenant("acme")
acme.data.insert_many([
    {"title": "RAG patterns", "body": "...", "published_at": "2026-04-01T00:00:00Z"},
])
```

### Hybrid search with alpha + filter

```python
from weaviate.classes.query import Filter, HybridFusion

results = acme.query.hybrid(
    query="how to build RAG with Weaviate",
    alpha=0.6,                                  # 0=BM25 only, 1=vector only
    target_vector="body_vec",
    fusion_type=HybridFusion.RELATIVE_SCORE,    # or RANKED (RRF)
    filters=Filter.by_property("published_at").greater_than("2026-01-01T00:00:00Z"),
    limit=20,
    return_metadata=["score", "explain_score"],
)
for o in results.objects:
    print(o.properties["title"], o.metadata.score)
```

### Generative search (RAG in one call)

```python
from weaviate.classes.generate import GenerativeConfig

results = acme.generate.near_text(
    query="vector index choices",
    target_vector="body_vec",
    limit=5,
    grouped_task="Summarize how HNSW differs from Flat for these articles.",
    generative_provider=GenerativeConfig.anthropic(model="claude-haiku-4-5"),
)
print(results.generative.text)
```

### Multi-vector / ColBERT via custom vectors

```python
articles = client.collections.create(
    name="ArticleColbert",
    vector_config=Configure.Vectors.self_provided(
        name="colbert",
        vector_index_config=Configure.VectorIndex.hnsw(
            multi_vector=Configure.VectorIndex.MultiVector.multi_vector(),
        ),
    ),
)
# Insert with per-token vectors
articles.data.insert(
    properties={"title": "..."},
    vector={"colbert": [tok_vec_1, tok_vec_2, ...]},
)
```

## Performance Tuning

- Use `auto_tenant_activation` only if access is bursty; for steady traffic preload tenants
- Set `MEMORY_LIMIT` per pod and use `OFFLOAD` to S3 for cold tenants
- BQ + `rescore_limit=200` keeps recall high while cutting RAM 32x
- For BM25 to matter, set `properties=["title^2", "body"]` to boost field weights
- HNSW `efConstruction=128, maxConnections=32` for high recall; `dynamicEf` for adaptive search
- Async indexing (`async_enabled=true`) decouples write throughput from index build

## Common Pitfalls

- Forgetting to enable multi-tenancy at create time — cannot toggle later
- Querying a tenant-enabled collection without `.with_tenant()` — returns empty
- Mixing `near_text` (uses module) and `near_vector` (raw vector) and confusing target vector
- Using a single shard for > 10M objects — split via shard count or use multi-tenancy
- Modules require API keys configured server-side — client-side keys via headers per request
- BM25 scores are not normalized — use `RELATIVE_SCORE` fusion, not raw weighted sum

## When to Use This Mode

- Multi-tenant SaaS where each customer gets isolated data and per-tenant cost accounting
- You want vectorizer + reranker + generator pluggable as server-side modules
- Hybrid search must combine BM25 + vector with one query, multiple named vectors
- You need GraphQL as a query layer (Weaviate exposes it natively)
- Cloud (WCS) or self-hosted, with consistent API

## Sources

- Weaviate docs: https://docs.weaviate.io/weaviate/
- Multi-tenancy: https://docs.weaviate.io/weaviate/manage-collections/multi-tenancy
- Hybrid search: https://weaviate.io/hybrid-search
- Multi-tenancy at scale blog: https://weaviate.io/blog/multi-tenancy-vector-search
- GitHub: https://github.com/weaviate/weaviate