Weaviate Vector Database — Getting Started Guide for 2025

Introduction

Why This Matters

Weaviate is the leading self-hostable vector database for teams that need enterprise-grade features: native hybrid search (BM25 + vector), multi-tenancy, schema-based data modeling, and production scalability without vendor lock-in. Unlike fully managed options like Pinecone, Weaviate gives you full control over your data and infrastructure.

Released in 2019 and consistently in the top two vector databases by adoption, Weaviate offers something unique: it is both a vector database and a production database. You define schemas with typed properties, run rich filtered queries, and get semantic search — all in one system. The Weaviate Cloud Service (WCS) provides a managed option for teams that want Weaviate's features without running their own cluster.

In 2024 and 2025, Weaviate added Generative Search (built-in RAG), multi-vector support, and significantly improved its Python client (v4) with a cleaner, more Pythonic API.

Installation and Setup

Local with Docker (recommended for development):

docker run -d \
  -p 8080:8080 \
  -p 50051:50051 \
  -e OPENAI_APIKEY=your-key \
  cr.weaviate.io/semitechnologies/weaviate:latest

Python client:

pip install weaviate-client

Connect to local or Weaviate Cloud:

import weaviate
from weaviate.auth import AuthApiKey
 
# Local Docker
client = weaviate.connect_to_local()
 
# Weaviate Cloud Service
client = weaviate.connect_to_weaviate_cloud(
    cluster_url="https://your-cluster.weaviate.network",
    auth_credentials=AuthApiKey("your-wcs-api-key"),
    headers={"X-OpenAI-Api-Key": "your-openai-key"}
)
 
print(client.is_ready())  # True

Defining Collections (Schemas)

Weaviate uses typed schemas — a key differentiator from schemaless vector databases:

from weaviate.classes.config import Configure, Property, DataType, Tokenization
 
client.collections.create(
    name="CompanyDocument",
    # Automatically vectorize text properties using OpenAI
    vectorizer_config=Configure.Vectorizer.text2vec_openai(
        model="text-embedding-3-small"
    ),
    # Built-in generative module for RAG
    generative_config=Configure.Generative.openai(model="gpt-4o"),
    properties=[
        Property(name="content", data_type=DataType.TEXT, tokenization=Tokenization.WORD),
        Property(name="source", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
        Property(name="section", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
        Property(name="year", data_type=DataType.INT),
        Property(name="is_current", data_type=DataType.BOOL),
    ]
)

Inserting Data

collection = client.collections.get("CompanyDocument")
 
# Insert single object
collection.data.insert({
    "content": "Returns are accepted within 30 days of purchase.",
    "source": "handbook",
    "section": "returns",
    "year": 2025,
    "is_current": True,
})
 
# Batch insert (efficient for large datasets)
with collection.batch.dynamic() as batch:
    documents = [
        {"content": "Enterprise SLA is 99.9% uptime.", "source": "contracts", "section": "sla", "year": 2025, "is_current": True},
        {"content": "API rate limit is 1000 req/min on Pro.", "source": "api-docs", "section": "limits", "year": 2024, "is_current": False},
        {"content": "Free plan allows 100 API calls per day.", "source": "api-docs", "section": "limits", "year": 2025, "is_current": True},
    ]
    for doc in documents:
        batch.add_object(doc)
 
print(f"Inserted {collection.aggregate.over_all().total_count} objects")

Semantic Search (Vector Query)

from weaviate.classes.query import MetadataQuery
 
collection = client.collections.get("CompanyDocument")
 
# Pure semantic search
results = collection.query.near_text(
    query="return policy refund",
    limit=3,
    return_metadata=MetadataQuery(distance=True, score=True),
    return_properties=["content", "source", "section"]
)
 
for obj in results.objects:
    print(f"Distance: {obj.metadata.distance:.4f}")
    print(f"Content: {obj.properties['content']}")
    print(f"Source: {obj.properties['source']}")
    print()

Hybrid Search (BM25 + Vector)

Weaviate's hybrid search is a core differentiator — it combines BM25 keyword scoring with semantic vector search:

from weaviate.classes.query import MetadataQuery
 
results = collection.query.hybrid(
    query="API rate limit exceeded error",
    alpha=0.75,      # 0.0 = pure BM25, 1.0 = pure vector, 0.75 = mostly semantic
    limit=5,
    return_metadata=MetadataQuery(score=True),
    return_properties=["content", "source", "section"]
)
 
for obj in results.objects:
    print(f"Hybrid score: {obj.metadata.score:.4f} | {obj.properties['content'][:100]}")

Hybrid search consistently outperforms pure vector search on technical and domain-specific content where exact keyword matching matters.

Filtered Queries

from weaviate.classes.query import Filter
 
# Filter by exact value
results = collection.query.near_text(
    query="SLA guarantee",
    filters=Filter.by_property("source").equal("contracts"),
    limit=3
)
 
# Compound filter
results = collection.query.hybrid(
    query="API documentation",
    filters=(
        Filter.by_property("source").equal("api-docs") &
        Filter.by_property("is_current").equal(True) &
        Filter.by_property("year").greater_than(2023)
    ),
    limit=5
)

Generative Search (Built-in RAG)

Weaviate's generative module enables RAG in a single query — no separate LLM call required:

collection = client.collections.get("CompanyDocument")
 
# Single prompt: generate answer from each retrieved object
results = collection.generate.near_text(
    query="refund policy",
    limit=3,
    single_prompt="Summarize this policy in one sentence: {content}"
)
 
for obj in results.objects:
    print(f"Generated: {obj.generated}")
 
# Grouped task: generate one answer from all retrieved objects
results = collection.generate.near_text(
    query="API usage limits",
    limit=5,
    grouped_task="Based on these documents, summarize all API rate limits in a clear table."
)
 
print(results.generated)

Multi-Tenancy

Weaviate's native multi-tenancy isolates data per tenant with minimal overhead:

from weaviate.classes.config import Configure
from weaviate.classes.tenants import Tenant
 
# Enable multi-tenancy on collection
client.collections.create(
    name="TenantDocument",
    multi_tenancy_config=Configure.multi_tenancy(enabled=True),
    vectorizer_config=Configure.Vectorizer.text2vec_openai()
)
 
collection = client.collections.get("TenantDocument")
 
# Add tenants
collection.tenants.create([
    Tenant(name="acme-corp"),
    Tenant(name="globex-inc"),
])
 
# Insert data for a specific tenant
collection.with_tenant("acme-corp").data.insert({
    "content": "ACME internal policy document."
})
 
# Query scoped to tenant
results = collection.with_tenant("acme-corp").query.near_text(
    query="internal policy",
    limit=3
)

Common Mistakes / Pitfalls

Forgetting to close the client — always call client.close() or use a context manager (with weaviate.connect_to_local() as client:)
Not setting alpha correctly in hybrid search — alpha=0 is pure BM25 (not useful for semantic tasks), alpha=0.75 is a good default
Defining a vectorizer on a property you do not want embedded — set skip=True on metadata-only properties
Using v3 client syntax with the v4 library — the v4 Python client (2024+) has a completely different API
Not enabling multi-tenancy at collection creation — you cannot add it later without recreating the collection

Best Practices

Use batch.dynamic() for inserts over 100 objects — it automatically adjusts batch size for optimal throughput
Set alpha=0.7 to 0.8 as default for hybrid search on document Q&A workloads
Use generative search for simple RAG pipelines — it reduces code complexity and one round-trip vs. a separate LLM call
Store source and section metadata on every object — enables filtered retrieval and citation generation
Use Weaviate Cloud Service for production if you cannot operate Docker infrastructure

Key Takeaways

Weaviate is a production-grade, self-hostable vector database with native hybrid search (BM25 + vector) and typed schemas
The v4 Python client (2024+) provides a clean, Pythonic API — client.collections.get(), collection.query.near_text(), etc.
Hybrid search with alpha=0.75 combines 75% semantic and 25% keyword scoring — outperforms pure vector search on domain content
Built-in generative search enables single-query RAG — retrieve and generate in one Weaviate API call
Multi-tenancy is a native feature — each tenant's data is isolated and can be activated/deactivated independently
Weaviate Cloud Service (WCS) provides a managed version for teams that want enterprise features without infrastructure management
Typed schema properties with tokenization control (WORD, FIELD) determine which properties participate in BM25 and vectorization
Best suited for enterprise deployments needing hybrid search, multi-tenancy, and data sovereignty requirements

Introduction#

Why This Matters#

Installation and Setup#

Defining Collections (Schemas)#

Inserting Data#

Semantic Search (Vector Query)#

Hybrid Search (BM25 + Vector)#

Filtered Queries#

Generative Search (Built-in RAG)#

Multi-Tenancy#

Common Mistakes / Pitfalls#

Best Practices#

Key Takeaways#

Related reading