Vearch: a distributed vector database with a Master, Router and PartitionServer split
Distributed vector search for AI-native applications
At a glance
- What is it?
- Vearch is an Apache-2.0 vector database that separates cluster metadata, request routing and raft-replicated partitions, with a faiss-based search engine inside each PartitionServer. It suits teams that want vector search and scalar filtering in the same query and are willing to run a multi-process cluster.
- Who is it for?
- Adopt Vearch if you need vector search combined with scalar filtering at a scale where a single-node index is no longer enough, and you already run Kubernetes or Docker Compose. Do not adopt it if you only need an in-process index for a few hundred thousand vectors, since the Master, Router and PartitionServer split buys you nothing there.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 51 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Vearch solves: similarity search that also has to filter on metadata
Pure vector indexes answer one question: which vectors are nearest to this one. Production retrieval rarely stops there. A visual search system needs to return images that are similar and belong to a category the user is allowed to see. A retrieval-augmented generation pipeline needs chunks that are semantically close and carry a document id, a timestamp or a tenant tag. The README describes Vearch as a cloud-native distributed vector database for similarity search of embedding vectors, and lists hybrid search (vector search plus scalar filtering) as its first key feature. That combination, not vector search alone, is the problem it targets. The secondary problem is scale. The README claims retrieval from millions of objects in milliseconds and lists replication and elastic scaling out under scalability and reliability. The audience is therefore teams building AI-native applications, document retrieval or RAG, who have outgrown an embedded index and now need a service with a schema, replicas and a REST API.
Master, Router, PartitionServer: what each process actually owns
The architecture image in the repository shows three component types. Master handles schema management, cluster-level metadata and resource coordination. Router exposes the RESTful API (upsert, delete, search and query), routes requests and merges results. PartitionServer (PS) hosts document partitions with raft-based replication, and inside it Gamma is the core vector search engine, implemented on top of faiss, providing storage, indexing and retrieval for both vectors and scalars. That split has a practical consequence: the schema you define is a cluster-level object held by Master, not a per-client convention. A search request enters at Router, which fans it out to the relevant partitions and merges the partial results before returning them. Because replication is raft-based at the partition level, a partition has a leader and followers, and writes are ordered through that group. The retrieval engine itself is faiss, so the index types and their memory behaviour are inherited from that library rather than invented here. The repository does not, in the material available, spell out which faiss index families are exposed through the schema API; that detail lives in the linked documentation, not in the README.
Getting it running: Helm, Docker Compose, or a source build
The README gives two container-based paths. For Kubernetes, it shows adding the Helm repository and installing:
helm repo add vearch https://vearch.github.io/vearch-helm helm repo update && helm install my-release vearch/vearch
It also shows the local-chart variant: clone vearch-helm, then helm install my-release ./charts -f ./charts/values.yaml. For Docker Compose, the documented steps are to change into the cloud directory, copy a config file into place, and bring up a profile. Standalone mode uses config.toml with docker-compose --profile standalone up -d. Cluster mode uses config_cluster.toml with docker-compose --profile cluster up -d. The distinction matters: the standalone profile is a single-node setup for development, while the cluster profile is what exercises the Master, Router and PartitionServer topology described above. Two further deployment documents are linked, DeployByDocker and SourceCompileDeployment, for people who want to build from source rather than run the published images. The README does not list the individual keys inside config.toml or config_cluster.toml, so anyone tuning ports, paths or replication settings has to read those files in the repository rather than the front page.
Client surface: four SDKs and four framework integrations
Vearch ships SDKs for Python, Go, Java and Rust, each with its own README under sdk/. The Python SDK is the one most likely to matter for RAG work, and the repository also carries framework integrations: LangChain, LlamaIndex, Langchaingo (the Go implementation of LangChain) and LangChain4j. Those integrations are the shortest path if you are already building on one of those frameworks, because they let Vearch act as the vector store or knowledge base backend rather than something you call directly. The README frames this under use cases, describing Vearch as a memory backend for AI frameworks. There is also a visual search demo documented in docs/Quickstart.md, which the README says can be used to build a complete visual search system indexing billions of images, with an image retrieval plugin for object detection and feature extraction required alongside it. Note the wording: the plugin is an additional component you supply, not something Vearch extracts for you. Embedding generation sits outside the database in every one of these paths.
Where Vearch is the wrong choice, and what the README does not tell you
The architecture is the limitation. A Master, a Router and a set of PartitionServers with raft replication is a distributed system, and distributed systems fail in distributed ways: a partition without a quorum, a Router that cannot reach a shard, a schema change that has to propagate. For a corpus that fits in memory on one machine, an embedded index has no network hop, no schema service and no replication protocol to reason about. If your workload is a few hundred thousand vectors and a single process, Vearch's component split is cost without benefit. The second gap is documentation depth in the material provided. The README lists features but gives no numbers behind the millisecond claim, no index-type guidance, and no failure or recovery documentation. The release history shows v3.5.7 in April 2025, v3.5.8 in November 2025 and v3.5.9 in February 2026: roughly two to three releases a year, which is a slow enough cadence that a bug fix you need may wait months, and fast enough that you still have upgrade work. Anyone planning a production deployment should treat the linked readthedocs pages and the OpenAPI documentation as required reading, not optional, because the front page does not cover operations.
Alternatives: faiss directly, or a single-process vector store
The most direct alternative is faiss itself, since Vearch's Gamma engine is built on it. The difference in approach is that faiss gives you an index library and leaves persistence, schema, replication, request routing and a network API to you. Vearch packages those around the same underlying retrieval code. If your data fits on one node and you control the process, faiss alone removes the Master, Router and PartitionServer layers entirely. The other alternative class is a single-process vector store embedded in your application, which keeps the index in the same process as your code and persists it to local files. That approach wins on operational simplicity and loses on the properties Vearch advertises: replication, elastic scaling out, and a RESTful API that multiple services can share. The deciding question is not which is faster but whether more than one service needs to query the same index, and whether a node failure must be survivable without a rebuild. Vearch is on the yes side of both; an embedded store is on the no side. The README's own positioning, cloud-native and distributed, is the honest summary of which side it is on.
Maintenance, licence and upgrade cost
Vearch is Apache-2.0, the same licence as faiss, so the licensing picture is permissive and there is no copyleft obligation on your application code. Apache-2.0 also includes an explicit patent grant, which matters for a component sitting inside a commercial retrieval stack. This is a description of the licence text, not legal advice; have counsel review the LICENSE and NOTICE files the README points to if the distinction matters to you. The maintenance cost is the operational surface: a Master to keep available, Routers to scale behind a load balancer, PartitionServers whose raft groups need a healthy majority, plus config.toml or config_cluster.toml to keep in sync across environments. Upgrades mean moving all of those together, and with releases landing every few months you should read the release notes for each version you skip rather than jumping straight from v3.5.7 to v3.5.9. The repository also documents an academic citation for the original JD e-commerce visual search system, which is where the design came from, and the paper is worth reading if you want the reasoning behind the partition model rather than just the API.
Editorial conclusion
Adopt Vearch if you need vector search combined with scalar filtering at a scale where a single-node index is no longer enough, and you already run Kubernetes or Docker Compose. Do not adopt it if you only need an in-process index for a few hundred thousand vectors, since the Master, Router and PartitionServer split buys you nothing there. Before committing, verify the release cadence against your upgrade window (v3.5.7 to v3.5.8 to v3.5.9 spans April 2025 to February 2026), and check whether the Python SDK is the only client your team can maintain.
Community notes