Skip to content

title: Weaviate description: Vector database with hybrid search — Weaviate for RAG: GraphQL API, hybrid search (BM25 + vector), multi-tenancy, modules, and production deployment. category: 09-RAG tags: [weaviate, vector-store, hybrid-search, graphql, rag] status: ready last_updated: 2026-09-06

Weaviate

Weaviate is a vector database built for hybrid search — combining BM25 keyword search with vector similarity in a single query. It offers a GraphQL API, multi-tenancy, built-in vectorization modules, and easy deployment. Use Weaviate when hybrid search (semantic + keyword) is a priority.

Table of Contents

Installation / Setup

pip install weaviate-client              # or: uv add weaviate-client
# cloud: sign up at https://weaviate.io/cloud/

Core Syntax

Client setup

import weaviate

# local (Docker)
client = weaviate.connect_to_local()

# cloud
client = weaviate.connect_to_weaviate_cloud(
    cluster_url="https://xyz.weaviate.network",
    auth_credentials=weaviate.auth.AuthApiKey(api_key="YOUR_API_KEY"),
)

Create collection

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

client.collections.create(
    name="Document",
    properties=[
        Property(name="text", data_type=DataType.TEXT),
        Property(name="source", data_type=DataType.TEXT),
        Property(name="year", data_type=DataType.INT),
    ],
    vectorizer_config=Configure.Vectorizer.text2vec_openai(),  # auto-vectorize
)

Add objects (auto-vectorized)

docs = client.collections.get("Document")

docs.data.insert({"text": "Python is great for ML", "source": "tutorial", "year": 2025})
docs.data.insert({"text": "JavaScript runs in browsers", "source": "web", "year": 2024})

# vector search
results = docs.query.near_text("data analysis", limit=5)

# BM25 keyword search
results = docs.query.bm25("machine learning", limit=5)

# hybrid search (default: combines both)
results = docs.query.hybrid("ML tools", limit=5)

LangChain + Weaviate

from langchain_community.vectorstores import Weaviate
from langchain_openai import OpenAIEmbeddings

vectorstore = Weaviate.from_documents(
    chunks, OpenAIEmbeddings(),
    weaviate_url="http://localhost:8080",
    index_name="Document",
)

# hybrid search
docs = vectorstore.similarity_search("query", k=5)

Common Operations

Hybrid search (Weaviate's strength)

# combine vector + BM25
results = docs.query.hybrid(
    query="machine learning",
    limit=5,
    alpha=0.75,         # 0=BM25, 1=vector, 0.75=default
)

# pure vector
results = docs.query.hybrid("query", alpha=1.0)

# pure BM25
results = docs.query.hybrid("query", alpha=0.0)

Metadata filtering

from weaviate.classes.query import Filter

# exact match
results = docs.query.near_text(
    "query",
    filters=Filter.by_property("source").equal("report"),
    limit=5,
)

# range
results = docs.query.near_text(
    "query",
    filters=Filter.by_property("year").greater_than(2024),
    limit=5,
)

# multiple filters
results = docs.query.near_text(
    "query",
    filters=(
        Filter.by_property("source").equal("report") &
        Filter.by_property("year").greater_than(2024)
    ),
    limit=5,
)

Collection management

# check if collection exists
client.collections.exists("Document")

# get collection stats
stats = docs.statistics.get()
print(stats)

# delete collection
client.collections.delete("Document")

Practical Examples

Example 1 — Weaviate hybrid RAG

import weaviate
from langchain_community.vectorstores import Weaviate
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough

client = weaviate.connect_to_local()
vectorstore = Weaviate(client, "Document", "text", OpenAIEmbeddings())
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

rag = (
    {"context": retriever | (lambda d: "\n\n".join(x.page_content for x in d)),
     "question": RunnablePassthrough()}
    | ChatPromptTemplate.from_template("Answer:\n{context}\n\nQ: {question}")
    | ChatOpenAI(model="gpt-4o")
    | StrOutputParser()
)

Common Patterns

# start with vector-heavy for broad queries
alpha = 0.75    # default: 75% vector, 25% BM25

# for exact-match queries, increase BM25
alpha = 0.3     # 30% vector, 70% BM25

# for semantic queries, increase vector
alpha = 0.9     # 90% vector, 10% BM25

Best Practices

  • Use Weaviate when hybrid search (BM25 + vector) is important.
  • Use alpha to tune the balance between semantic and keyword search.
  • Weaviate can auto-vectorize — no need to pre-compute embeddings.
  • Use metadata filtering for scoped search.
  • Weaviate Cloud is the easiest production deployment.

Common Mistakes

Mistake Fix
Ignoring hybrid search It's Weaviate's key advantage — use it
Not tuning alpha Adjust alpha based on query type
Using Weaviate for local dev Chroma or FAISS are simpler for local

Troubleshooting

Symptom Cause / Fix
Connection refused Weaviate server not running
Vectorization fails Check vectorizer module is enabled
Poor hybrid results Tune alpha parameter
Slow queries Add indexes for filtered properties

Official Documentation

Last Updated

2026-09-06 — Initial version.