Weaviate Tutorial: Build Semantic Search in Minutes

If you are building an AI application that needs to understand what users mean rather than just matching their exact words, you need a vector database. This Weaviate tutorial shows you how to set it up, create a collection, import data, and run your first semantic search. Weaviate stands out because it can auto-vectorize your data at import time and run hybrid search combining keywords and vectors in one API call. 

TL;DR Summary

• Weaviate is a free, open-source vector database that does semantic search, hybrid search, and RAG out of the box.
• Setup uses Docker Compose and the Python client in under 10 minutes.
• Weaviate can auto-vectorize your data at import time using built-in integrations with OpenAI, Cohere, and local models.
• Hybrid search in Weaviate combines BM25 keyword matching and vector similarity in a single API call, no extra tooling needed.
• Used by teams building RAG pipelines, recommendation engines, and AI-powered search products.

What is Weaviate?

Weaviate is an open-source vector database that stores both your data objects and their vector embeddings together. When you search, it finds results that are semantically similar to your query even when exact words do not appear in the results. It supports auto-vectorization at import time with built-in integrations for OpenAI, Cohere, and local models, plus hybrid search out of the box with no extra tooling.

Weaviate is one of the core components in modern AI engineering stacks alongside LLMs and orchestration frameworks like LangChain. HCL  GUVI’s AI Software Development Course is IITM Pravartak certified and covers the hands-on AI engineering skills that make working with tools like Weaviate practical and production-ready.

Weaviate Tutorial: Installation with Docker

To set up Weaviate, you can use Docker Compose or install it manually. Docker Compose is the recommended method, as it simplifies the installation process.

For a minimal local setup without a vectorizer module, save this as docker-compose.yml:

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.38.0
    ports:
      - 8080:8080
      - 50051:50051
    environment:
      QUERY_DEFAULTS_LIMIT: 20
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: "./data"

Start it with docker compose up -d. Weaviate runs at http://localhost:8080.

Connecting with the Python Client

Install the Python client:

pip install weaviate-client

Connect to your local instance:

Python

import weaviate

client = weaviate.connect_to_local()
print(client.is_ready())

If you see True, you are connected and ready to go.

Creating a Collection

A collection in Weaviate is like a table, but designed for vector data. Each collection has a schema that defines the properties of your objects.

Python

from weaviate.classes.config import Configure

client.collections.create(
    name="Article",
    vector_config=Configure.Vectors.self_provided()
)

Using self_provided means you will supply your own vectors at import time. If you want Weaviate to auto-vectorize using OpenAI or Cohere, replace this with the appropriate Configure.Vectors.text2vec_openai() integration.

Importing Objects

Add objects to your Weaviate collection using batch import for efficiency:

Python

articles = client.collections.get("Article")

with articles.batch.dynamic() as batch:
    batch.add_object(
        properties={"title": "Semantic search explained", "body": "Vector databases find meaning..."},
        vector=[0.1, 0.3, 0.7, 0.9]
    )
    batch.add_object(
        properties={"title": "Building RAG pipelines", "body": "Retrieval augmented generation..."},
        vector=[0.2, 0.5, 0.6, 0.8]
    )

In production, your vectors would come from an embedding model like text-embedding-3-small from OpenAI rather than hardcoded values.

Running a Semantic Search

Python

results = articles.query.near_vector(
    near_vector=[0.1, 0.3, 0.7, 0.9],
    limit=2
)

for obj in results.objects:
    print(obj.properties["title"])

Weaviate returns the closest matches by cosine similarity. In a real app, your query vector comes from running the user’s search phrase through the same embedding model you used at import time.

Hybrid Search in Weaviate

A super cool feature of Weaviate is its built-in support for hybrid search. This means it can do both BM25 keyword searches and vector similarity searches at the same time. You do not need extra tools for this.

Python

results = articles.query.hybrid(
    query="vector search for AI apps",
    alpha=0.5,
    limit=3
)

The alpha parameter controls the blend: 0 is pure keyword, 1 is pure vector, and 0.5 blends both equally. This single parameter is what makes Weaviate’s hybrid search so practical for real-world applications where users mix specific terms and natural language in the same query.

Where Weaviate Fits in Your AI Stack

Common Mistakes to Avoid

• Using self_provided vectors but forgetting to supply them at import. If your collection is configured for self-provided vectors and you add an object without a vector, Weaviate stores the object but it becomes invisible to vector search. Always confirm every object has a vector attached.
• Mismatching vector dimensions across objects. Every vector in a collection must have the same number of dimensions as the first object imported. A dimension mismatch causes a silent rejection of the object without breaking the batch job. Check your embedding model output size before starting a large import.
• Not closing the client connection. Always use client.close() or a context manager after your operations. Leaving connections open causes resource leaks in long-running applications.

Conclusion

This Weaviate tutorial covered the full beginner path: installing with Docker, connecting the Python client, creating a collection, importing objects with vectors, running semantic search, and using built-in hybrid search. Weaviate’s combination of auto-vectorization, hybrid search in one API call, and strong scaling makes it one of the most practical vector databases for developers building AI features in 2026.

FAQs

1. What is Weaviate?

Weaviate is a free, open-source vector database that stores objects with their vector embeddings and retrieves semantically similar results using vector or hybrid search.

2. Is Weaviate free?

Yes. Open-source under BSD 3-Clause. Weaviate Cloud also has a managed free tier for small projects.

3. What is hybrid search in Weaviate?

Hybrid search combines BM25 keyword matching and vector similarity in one API call. The alpha parameter controls the blend from 0 (pure keyword) to 1 (pure vector).

4. Does Weaviate auto-vectorize my data?

Yes, if you configure a vectorizer at collection creation. Supported integrations include OpenAI, Cohere, HuggingFace, Google, and Ollama for local models.

5. How does Weaviate compare to Qdrant? 

Weaviate includes built-in vectorizer integrations and auto-vectorization at import. Qdrant is a pure vector engine where you always supply your own vectors.