Vector Weaviate

Weaviate is an open-source vector database that you can run locally, self-host on your own servers, or use as a managed cloud service. It stands out for built-in embedding generation and hybrid search that combines vectors with keyword matching. This topic walks you through your first Weaviate setup.

Core Concepts Before You Code

WEAVIATE STRUCTURE:
───────────────────────────────────────────────────
Weaviate Instance
  └── Collection (formerly "Class" — like a table)
        └── Objects (records with properties + a vector)

Example:
  Collection: Article
    Object: {title: "AI Basics", content: "...", vector: [0.2, 0.8, ...]}
    Object: {title: "Cooking Tips", content: "...", vector: [0.5, 0.1, ...]}

Step 1: Run Weaviate Locally with Docker

The fastest way to try Weaviate is through Docker. Create a file named docker-compose.yml:

version: '3.4'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.25.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai'
      OPENAI_APIKEY: 'your-openai-key'

docker compose up -d

Weaviate now runs at http://localhost:8080. Alternatively, sign up at Weaviate Cloud for a free managed sandbox without running Docker yourself.

Step 2: Install the Python Client

pip install weaviate-client

Step 3: Connect and Create a Collection

Weaviate can generate embeddings automatically using a connected module (like OpenAI), or you can supply your own pre-computed vectors. This example uses automatic embedding generation.

import weaviate
import weaviate.classes as wvc

client = weaviate.connect_to_local()

# Create a collection with automatic OpenAI vectorization
articles = client.collections.create(
    name="Article",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="category", data_type=wvc.config.DataType.TEXT),
    ]
)

print("Collection created")

Step 4: Insert Data

Weaviate automatically generates the vector embedding for each object you insert — you do not need to call an embedding model yourself.

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

data = [
    {"title": "Intro to Python", "content": "Python is a beginner-friendly programming language", "category": "tech"},
    {"title": "Healthy Breakfast", "content": "Oatmeal with fruit makes a nutritious morning meal", "category": "food"},
    {"title": "Machine Learning Basics", "content": "ML algorithms learn patterns from data", "category": "tech"},
]

with articles.batch.dynamic() as batch:
    for item in data:
        batch.add_object(properties=item)

print("Data inserted")

Step 5: Run a Vector Search

response = articles.query.near_text(
    query="programming languages for beginners",
    limit=2
)

for obj in response.objects:
    print(obj.properties["title"])
    print(obj.properties["content"])
    print("---")

Expected Output

Intro to Python
Python is a beginner-friendly programming language
---
Machine Learning Basics
ML algorithms learn patterns from data
---

Notice the search query never used the word "Python" yet returned the Python article first. Weaviate converted both the query and stored content into vectors, then matched by meaning.

Hybrid Search: Combining Vectors and Keywords

Hybrid search blends semantic similarity with traditional keyword matching. This catches cases where exact terminology matters alongside conceptual meaning — useful for product names, technical terms, or proper nouns.

response = articles.query.hybrid(
    query="Python programming",
    alpha=0.5,     # 0 = pure keyword, 1 = pure vector, 0.5 = balanced
    limit=3
)

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

Filtering Results by Property

Combine vector search with metadata filters to narrow results — for example, search within a single category.

from weaviate.classes.query import Filter

response = articles.query.near_text(
    query="learning new skills",
    filters=Filter.by_property("category").equal("tech"),
    limit=5
)

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

Weaviate vs. Bringing Your Own Embeddings

To bring your own vectors instead of auto-generation, set vectorizer_config=wvc.config.Configure.Vectorizer.none() when creating the collection, then pass a vector= parameter when inserting each object.

Closing the Connection

client.close()

Always close the client connection when your script finishes, especially in long-running applications, to free up server resources properly.