Weaviate: a Go vector database that keeps objects and vectors in one query path

What Weaviate stores that a plain vector index does not

A vector index answers one question well: which vectors are closest to this one. Most applications immediately ask a second question that the index cannot answer, such as which of those close vectors belong to a tenant, were created after a date, or carry a specific status. The usual workaround is to over-fetch from the vector index and discard the rows that fail the filter in application code. That works until the filter is selective, at which point most of the fetched candidates get thrown away and the result set comes back short.

Weaviate's premise is that the object and its vector belong in the same store, so a query can combine similarity with structured filtering in one call. The README describes it as an "open-source, cloud-native vector database that stores both objects and vectors", and lists RAG, reranking, hybrid search and image search as part of the same query interface. The intended audience is teams building retrieval for AI applications: RAG systems, semantic and image search, recommendation engines, chatbots, content classification. If your retrieval step already lives inside a Postgres query with pgvector, Weaviate is asking you to add a second stateful service. That trade is the whole decision.

How Weaviate handles vectors, shards and the Go runtime

The repository is a Go module rooted at github.com/weaviate/weaviate, and the server binary is built from ./cmd/weaviate, as the Dockerfile shows in its build stage. The same Dockerfile sets CGO_ENABLED=1 by default and links with -extldflags '-static', so the shipped server is a cgo-enabled static binary, not a pure-Go one. That matters if you plan to cross-compile or run on a base image without glibc.

Two storage decisions are visible in the layout. First, vectors are not the only thing indexed: the go.mod pulls in github.com/bits-and-blooms/bloom for filter structures and github.com/go-ego/gse for text segmentation, which is what BM25 keyword search needs for languages that do not split on spaces. Second, the vector index is HNSW, listed in the repository topics alongside approximate-nearest-neighbor-search. HNSW is a graph index, so memory scales with the number of vectors plus the graph edges, and deletion is not free the way it is in a flat index.

On the API side there are three surfaces: REST, gRPC and GraphQL. The client libraries (Python, JavaScript/TypeScript, Java, Go, C#/.NET) sit on top of those, and there are community-maintained clients as well. The docker-compose.yml at the repository root carries a blunt warning that it is for contributors and should not be used directly with docker compose up; end users are pointed at the installation docs instead. That is worth reading before copying any compose file out of the repo.

Installing Weaviate locally with Docker and running a first query

The README gives a Docker Compose setup that starts Weaviate together with a local embedding model, so no external API key is needed. The example uses the Model2Vec vectorizer and pins the image to 1.36.0. Ports 8080 and 50051 are exposed, the latter for gRPC.

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.36.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      ENABLE_MODULES: text2vec-model2vec
      MODEL2VEC_INFERENCE_API: http://text2vec-model2vec:8080

  text2vec-model2vec:
    image: cr.weaviate.io/semitechnologies/model2vec-inference:minishlab-potion-base-32M

Start both services with the command the README gives, then install the Python client.

docker compose up -d
pip install -U weaviate-client

The client connects to the local instance, creates a collection with one text property, and attaches the same vectorizer module so embeddings are generated during import rather than supplied by hand.

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

client = weaviate.connect_to_local()
client.collections.create(
    name="Article",
    properties=[Property(name="content", data_type=DataType.TEXT)],
    vector_config=Configure.Vectors.text2vec_model2vec(),
)

Insert a few objects and query them by meaning. The README's example inserts three short strings and runs near_text with limit=1, then prints results.objects[0]. If the container is up and the module container is reachable, that print returns one object; if the inference container failed to start, the insert fails because the vectorizer cannot be called.

articles = client.collections.get("Article")
articles.data.insert_many([
    {"content": "Vector databases enable semantic search"},
    {"content": "Machine learning models generate embeddings"},
])
results = articles.query.near_text(query="Search objects by meaning", limit=1)
print(results.objects[0])
client.close()

To supply your own embeddings instead, the README shows swapping the vector_config line for Configure.Vectors.self_provided(), which skips the module entirely. That is the option to take if you already generate vectors in your application and do not want a second inference container running.

Where Weaviate is the wrong tool

The module system is the first constraint. Vectorization happens inside Weaviate, which means the embedding model runs as another container or as a call to an external provider such as OpenAI, Cohere or HuggingFace. In the README's compose file that is a second service, text2vec-model2vec, with its own image and its own failure mode. If that container is down or slow, imports fail or stall, and the database's availability is now coupled to a model server. Teams that treat embedding generation as an application concern, with their own batching, caching and retry logic, will find this arrangement gets in the way.

Resource shape is the second constraint. HNSW keeps a graph in memory, and the server is a cgo-linked Go binary. The README describes the architecture as "built in Go for speed and reliability" and points at ANN benchmarks rather than stating a memory budget. There is no guidance in the README on how much RAM a given vector count and dimensionality requires, so sizing has to come from the deployment docs or from your own load test. For a few thousand vectors this is a heavy dependency to add; a flat index in the application process would be simpler and faster to iterate on.

Filter performance is the third. The v1.38.15 release notes list "Contains filter performance Improvements", which is a reasonable signal that filter-heavy workloads have not always been fast. If your queries lean on string containment filters rather than vector similarity, test that path specifically instead of assuming the vector benchmark generalizes to it.

Finally, the licence field on the repository is NOASSERTION, and the repository carries both a LICENSE and a LICENSE-BSD file. The root LICENSE file is the one that governs the server; the README does not summarize the terms, so read it directly rather than assuming an OSI licence from the topics list.

Weaviate compared with pgvector

The closest alternative for many teams is not another dedicated vector database but pgvector inside Postgres they already run. The difference is architectural rather than a matter of speed claims. pgvector adds a vector column type and distance operators to an existing relational engine, so your objects, your filters and your vectors sit in one transaction, one backup, one connection pool, one set of credentials. If your data already lives in Postgres, there is no second system to operate and no synchronization problem between the relational row and the vector.

Weaviate inverts that. It is a purpose-built database with its own storage, its own HTTP and gRPC servers, its own client libraries, and a module system for vectorization and generation. You get multi-tenancy, replication and RBAC authorization as built-in features, and a query interface that spans vector search, BM25 and reranking. You also get a second stateful service to run, monitor and upgrade, plus the question of how it stays consistent with your system of record.

The honest dividing line is whether retrieval is a feature of your application or the core of it. If you are adding semantic search to an existing product backed by Postgres, pgvector keeps the operational surface small. If retrieval is the product, or if you need hybrid BM25 plus vector search plus reranking behind one API, a dedicated engine earns its keep. Pick based on how many services you want to operate, not on a benchmark chart.

Upgrade cadence, release branches and what it costs to stay current

The release history shows three maintained lines at once. On consecutive days the project published v1.39.5, v1.38.15 and v1.37.17, all three carrying the same fix to the weaviate_module_error_total metric labels. That is a backport pattern: a patch lands on the current minor and is carried back to older minors. It is good for teams that cannot move minors quickly, and it also means three branches receive fixes, so the project is maintaining more surface than a single-line release model.

For an operator, the practical cost is that you should not pin to an old minor and forget it. The v1.38.15 notes also carry contains filter performance improvements, which is the kind of change you would want without waiting for a major upgrade. The last push to the default branch was on 2026-09-15, the same day as the v1.39.5 release, so the repository is being worked on continuously.

On licensing, the repository declares NOASSERTION and ships both LICENSE and LICENSE-BSD. That combination usually means the server and some bundled components are under different terms, and the README does not explain which is which. Check the LICENSE file and the terms of any module image you pull, particularly the inference containers, before you build a product on top. This is not legal advice; it is a pointer to the file you need to read.

Editorial conclusion

Adopt Weaviate if you need vector similarity and structured filtering in the same query, and you are willing to run a separate database service alongside your application. Do not adopt it if you only need a small in-process index for a few thousand vectors, or if you cannot operate a stateful Go service with its own ports and module containers. Before committing, verify two things against your own data: whether the vectorizer module you plan to use is the one you actually want, and whether your filter-heavy queries still return in acceptable time, since the release notes for v1.38.15 list contains filter performance improvements, which implies that path has been a moving target.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. weaviate/weaviate on GitHub