# Vearch: A Distributed Vector Database With a Raft-Replicated Storage Tier

> Vearch splits vector search across a Master, a Router and Raft-replicated PartitionServers, with a faiss-based engine called Gamma underneath. Here is what the repository documents, where the docs go quiet, and who should pick it over a single-node index.

**vearch/vearch** — Distributed vector search for AI-native applications

- Repository: https://github.com/vearch/vearch
- Website: https://vearch.github.io
- Stars: 2,330 · Forks: 365
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/vearch-vearch

## What problem Vearch solves, and for whom

Vearch describes itself as a cloud-native distributed vector database for similarity search of embedding vectors in AI applications. That sentence covers two separate jobs. The first is retrieval: given a query vector, return the nearest stored vectors. The second is filtering: restrict that search by scalar fields attached to the same documents. The README lists both under a single feature, hybrid search, meaning vector search and scalar filtering run together rather than as two round trips stitched together in application code.

The audience follows from the component list. This is not a library you import and forget. It is a cluster with a Master for schema management and cluster metadata, a Router exposing RESTful endpoints for upsert, delete, search and query, and PartitionServer nodes that hold document partitions with Raft-based replication. If your team already runs stateful services and has opinions about replication and failover, the shape will be familiar. If you are a single developer prototyping a RAG pipeline on a laptop, the shape is heavier than you need. The README also points at integration paths for Langchain, LlamaIndex, Langchaingo and LangChain4j, which suggests the intended entry point for many users is as a vector store behind a framework rather than as a direct HTTP client.

## Master, Router, PartitionServer: how a query actually flows

The README names three components and one engine, and the split is worth reading carefully because it determines what you operate and what you scale.

Master handles schema management, cluster-level metadata and resource coordination. That means the definition of a space (the schema your vectors and scalar fields live in) is a cluster-level object, not something a client declares on each request.

Router provides the RESTful API: upsert, delete, search and query. It also does request routing and result merging. The merging detail matters. A search that spans partitions returns one merged result set to the caller, so the client does not fan out and re-rank itself.

PartitionServer hosts document partitions with Raft-based replication. Gamma, the core vector search engine, lives here and is described as implemented based on faiss. Gamma stores, indexes and retrieves vectors and scalars. So the retrieval algorithm itself comes from faiss, while the distribution, replication and request handling are Vearch's own.

The dependency list in go.mod corroborates the infrastructure story: etcd client and server packages at v3.5.12, grpc, a raft-adjacent stack, prometheus client_golang for metrics, and minio-go for object storage. The README does not spell out the full data flow from a client request to a specific PartitionServer, nor does it document what happens during a PartitionServer failover from the client's perspective. Those are the two gaps I would probe first.

## Installing Vearch with Helm or Docker Compose

The README gives two quick-start paths. The Kubernetes path uses a Helm repository hosted at vearch.github.io/vearch-helm. Adding the repository, updating it and installing a release named my-release is three commands:

```bash
helm repo add vearch https://vearch.github.io/vearch-helm
helm repo update && helm install my-release vearch/vearch
```

After this, the release should appear in your cluster with the Vearch components running. The README does not state which namespace or which service exposes the Router API, so check the chart values before pointing a client at it.

The second path is Docker Compose, run from the cloud directory. There are two profiles, standalone and cluster, and each expects a config file copied into that directory first. Standalone:

```bash
cd cloud && cp ../config/config.toml .
docker-compose --profile standalone up -d
```

Cluster mode swaps the config file and the profile:

```bash
cd cloud && cp ../config/config_cluster.toml .
docker-compose --profile cluster up -d
```

The distinction between config.toml and config_cluster.toml is the single-node versus multi-node topology, and the profile flag selects which services Compose starts. The README does not document the contents of either file, so read them before changing ports or paths.

For a first real use, the natural next step is a client. The repository ships SDKs for Python, Go, Java and Rust, each with its own README under sdk/. The README does not inline a Python example, so the honest instruction is: pick sdk/python/README.md and follow it. If you prefer to build from source rather than use containers, docs/SourceCompileDeployment.md covers that, and the Makefile builds the binary with `make all`, which shells into build/build.sh with a job count you can set via the j variable.

## Where the documentation is thin

The README is a landing page, not an operations manual. Three things are conspicuously absent.

First, no failure semantics. Raft-based replication is named, but the README does not say what a client sees when a PartitionServer goes away, whether writes block, or how long a leader election takes to become visible to the Router. If your availability target depends on that answer, the README will not give it to you.

Second, no capacity guidance. The feature list claims search from millions of objects in milliseconds, which is a claim about the engine, not a sizing table. Nothing in the README tells you how much memory a million 768-dimensional float vectors consume, how many partitions to create, or when to add a PartitionServer. Those are the numbers that decide whether a cluster is affordable, and they are not here.

Third, no rollback or upgrade procedure. The repository has recent releases, v3.5.9 on 2026-02-04, v3.5.8 on 2025-11-07 and v3.5.7 on 2025-04-28, so upgrades happen, but the README does not describe how to move a running cluster between them. The last push to the repository was on 2026-07-27, so the codebase is not dormant, but the release cadence is roughly quarterly and the upgrade path is undocumented.

None of this is unusual for a project whose documentation lives in a separate Read the Docs site. It does mean you should budget time for reading the tutorial at vearch.readthedocs.io and the OpenAPI documentation at vearch.github.io/tools before you size anything.

## Vearch versus an embedded index like faiss alone

The most direct alternative is faiss used directly, and the comparison is unusually clear here because Vearch's own engine is built on faiss. The README states that Gamma is implemented based on faiss and provides the ability to store, index and retrieve vectors and scalars.

If you use faiss alone, you own everything around the index: persistence, process lifetime, concurrency, replication if you need it, and any scalar filtering logic. Filtering in particular tends to become a post-filter or pre-filter you write yourself, and both have failure modes: post-filtering can return fewer than k results, pre-filtering can degrade recall depending on how the index is built.

Vearch moves those concerns into the cluster. Scalar filtering is a first-class part of the query, replication is handled by Raft at the PartitionServer layer, and the Router merges results across partitions. The cost is that you now run etcd, a Master, at least one Router and at least one PartitionServer, and you debug across process boundaries instead of inside one. The trade is operational weight for distribution and filtering. If your corpus fits in one process and you filter in application code, faiss alone is the smaller system and the smaller problem.

## Licence and the cost of staying current

Vearch is licensed under the Apache License, Version 2.0, per the README and the LICENSE file at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant, and the repository also carries a NOTICE file, which the licence references. If you redistribute Vearch or a derivative, the NOTICE handling is the part people forget; read the LICENSE and NOTICE files in the repository rather than relying on a summary. This is not legal advice, and if your use is unusual, talk to someone qualified.

The upgrade cost is harder to estimate because the README does not describe one. What the repository does show is a release history at roughly quarterly intervals through 2025 and into 2026, and a go.mod pinned to Go 1.22.0 with etcd v3.5.12 and grpc v1.64.1. Those pins tell you the operational baseline: you will be running etcd alongside Vearch whether or not you already do. The Makefile's test target runs pytest against test_vearch.py and the test_document_* and test_module_* suites, which is the project's own regression net; running it against your build is the cheapest way to confirm a version bump did not break your deployment. The README does not document a migration tool, so plan on validating each upgrade in a staging cluster before touching production.

## Conclusion

Adopt Vearch if you need vector search and scalar filtering in one query and you are willing to run a multi-process cluster: Master, Router and PartitionServer, with etcd and a Raft log underneath. Do not adopt it if a single-node index inside your application process is enough, because the operational surface here is a distributed system, not a library. Before committing, verify three things against the repository: that the v3.5.9 release from 2026-02-04 matches the API you plan to call, that your deployment target is covered by either the Helm charts or the docker-compose standalone and cluster profiles, and that the SDK you intend to use (Python, Go, Java or Rust) exposes the upsert, delete, search and query endpoints your application needs. The README documents the deployment commands and the component split; it does not document rollback, so treat that as an open question to settle with the maintainers before production.

## FAQ

### What is Vearch?

Vearch is a cloud-native distributed vector database for similarity search of embedding vectors in AI applications, according to its README. It combines vector search with scalar filtering and runs as a cluster of Master, Router and PartitionServer components.

### How do I install Vearch?

The README gives two quick-start paths: a Helm chart from the vearch.github.io/vearch-helm repository, or Docker Compose run from the cloud directory with either the standalone or cluster profile after copying the matching config file. Source compilation is covered separately in docs/SourceCompileDeployment.md.

### What is the relationship between Vearch and faiss?

The README states that Gamma, the core vector search engine inside PartitionServer, is implemented based on faiss and provides the ability to store, index and retrieve vectors and scalars. Distribution, replication and request routing are Vearch's own layers on top.

## Sources

- [License: Apache-2.0](https://github.com/vearch/vearch/blob/master/LICENSE)
- [Project website](https://vearch.github.io)
- [README](https://github.com/vearch/vearch/blob/master/README.md)
- [Releases](https://github.com/vearch/vearch/releases)
- [vearch/vearch on GitHub](https://github.com/vearch/vearch)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vearch-vearch