Library / SDK
vearch/vearch avatar
vearch/vearch

vearch: the language stat says Python, the project is Go, and make test cannot fail

Distributed vector search for AI-native applications

2,334 stars364 forksPythonApache-2.0

At a glance

What is it?
Vearch is a distributed vector database written in Go, with a master, a router and partition servers replicating partitions through raft, indexing vectors with an engine derived from faiss. Reading its build file and manifest closely shows the recorded primary language is not the language the server is written in, the test target runs three groups without stopping on the first failure and excludes the project's own upsert benchmark, four direct dependencies are pinned to untagged commits between 2017 and 2023, and the only citable paper describes a 2019 e-commerce visual search system.
Who is it for?
Vearch suits a team that wants a self-hosted distributed vector index with scalar filtering alongside vector search, that already runs containers or Kubernetes, and that can pick between a standalone and a clustered deployment from two configuration files.
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 111 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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • vearch/vearch2,334 ★ · +9
Star history
Repository2026-09-112026-11-15
vearch/vearch2.3k2.3k

9 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The recorded language is not the language the server is written in

The repository is a Go module. The manifest declares a module path with a major version suffix, the build file invokes the Go toolchain, and the source tree is made of Go packages: the command entry points, an internal directory, an api directory and a build script. The vector index itself is described in the readme as implemented on top of faiss, which is a C++ library with Go bindings. Against all of that, the hosting site records the project's primary language as Python. The reason is visible if you look at how the project is tested: the test target shells out to a Python test runner against a Python test directory, and there is a Python software development kit in the tree alongside Go, Java and Rust ones. So the language statistic is counting the test harness and one of four clients, and reporting it as the language of the project. That is a small thing on its own, but it is the kind of wrong answer that gets a repository filtered out of a search for a Go vector database, and it is the second time in this batch of work that a project's self-description and its language metadata have pointed in different directions.

The test target runs three groups and cannot fail on the first

The build file has one test target, and it is four lines of shell:

code
test:
	cd test;\
	pytest -x --log-cli-level=INFO test_vearch.py;\
	pytest test_document_* -k "not test_vearch_document_upsert_benchmark" -x --log-cli-level=INFO;\
    pytest test_module_* -x --log-cli-level=INFO

Each runner is told to stop at its own first failure, which is the right flag and is not the problem. The problem is the separator. The three invocations are joined with semicolons rather than with a conjunction that short-circuits, so a failure in the first group does not prevent the second and third from running. The target's exit status is the exit status of the last command. So if the module tests pass and the document tests fail, the target reports success. The same is true for the first group. Anyone gating a pipeline on this target is gating it on the last group alone. The fix is one character per separator, and the fact that the per-runner fail-fast flag is present but the between-runner flag is not suggests the two decisions were made separately. The indentation is inconsistent as well: the first two continuation lines begin with a tab like the recipe line, and the third begins with spaces, which works only because the continuation keeps it on one logical line.

The upsert benchmark is deliberately excluded from the test run

That second line contains the detail worth reading twice. The document test group is given a keyword filter that excludes a specific test by name: the document upsert benchmark. So the project's own measurement of write throughput is the one thing its test target is designed not to run, while everything else in the document suite is. That is a reasonable exclusion, since benchmarks are slow and flaky in a correctness suite, and it is the kind of thing a maintainer does deliberately. What makes it worth mentioning is that it is invisible from the outside in every other respect. There is no separate benchmark target in the build file, no documentation of how to run it, and the only evidence that it exists is a negative filter inside an otherwise ordinary test invocation. So a reader auditing the repository would reasonably conclude the suite covers document writes, and the gap between that impression and the reality is encoded in a string in the middle of a command line. If you care about upsert throughput, you have to find that name and run it yourself.

Four direct dependencies float on untagged commits from 2017 onward

In Go, a dependency pinned to a bare commit rather than a release is recorded as a pseudo-version whose middle component is a timestamp. Reading the direct requirements, four of them are pinned that way, and the timestamps span six years. A connection pool library is pinned to a commit from September 2017. An in-memory cache library is pinned to a commit from August 2018, with a compatibility suffix that tells you its version line never adopted module semantics. A profiling library is pinned to a commit from July 2020. A distributed file system client is pinned to a commit from June 2023. The rest of the direct list is conventionally versioned, so the project is not uniformly loose; it has four specific places where an upstream tag was never adopted. The practical risk is not that these will break, since untagged commits do not move. It is that nobody can tell from the manifest whether the pinned commit is the tip of anything, whether it carries a fix that landed later, or whether upstream renamed the default branch and the commit is now only reachable by hash.

Two deployment modes need a copied config and a matching profile

The container route selects a mode with two independent choices, and the quick start does not say they have to agree:

code
# Standalone Mode
$ cd cloud && cp ../config/config.toml .
$ docker-compose --profile standalone up -d

# Cluster Mode
$ cd cloud && cp ../config/config_cluster.toml .
$ docker-compose --profile cluster up -d

So the mode is expressed twice: once by which of two configuration files you copy into the directory, and once by which profile you pass to the compose command. Nothing on the page states what happens when the two disagree, and nothing at startup appears to validate that the configuration you supplied was written for the mode you selected. The deployment modes map onto the component list, which is a master for schema and cluster metadata, a router that exposes the four write and read operations and merges results from partitions, and partition servers that host the shards with raft replication. Running the cluster profile against a standalone configuration is not obviously a crash and not obviously harmless, which is exactly the kind of thing worth testing yourself before you trust it. The chart route, by contrast, lives in a separate repository and does not have this problem, though its two documented forms differ in whether a values file is passed explicitly.

The default build is one job and the phony line omits the build target

The build file sets a job count with a conditional, defaulting it to one:

code
ifdef j
JOBS := $(j)
else
JOBS := 1
endif

all:
	cd build && ./build.sh -n $(JOBS)

A bare make therefore builds serially, and the parallelism knob is a single lowercase variable that you pass on the command line. For a project whose selling points are distribution, parallelism and elastic scaling, having the default build be the serial one is a defensible choice for portability and an odd one to discover. The conditional also tests whether the variable is defined rather than whether it has a value, so passing it empty satisfies the test and forwards an empty count to the build script. Below that, the declared-phony line names three targets and not the one that produces the binary. The build target is first in the file, so a bare make still reaches it, and a stray file named after it would be the only thing that could stop that. The file's help output is headed as documentation and then lists three targets, the first of which builds the executable rather than documentation.

Four wire formats, two histogram libraries, and an embedded etcd

The dependency list doubles as an architecture diagram, and a few entries describe decisions the readme does not mention. Three related key-value store packages are required at the same version: the application programming interface, the client and the server. So the cluster's metadata lives in a key-value store the project links into itself rather than one you operate. Tracing is handled by an OpenTracing interface plus that implementation's client, which is the generation of tracing libraries that predates the current standard, alongside a Prometheus client for metrics. There is also a library that sets the process's processor count from the operating system's resource limits, which is the standard way to make a Go program container-aware, and its presence says the maintainers expect this to run under a scheduler. Object storage is handled by a client for a compatible object store, matching the file management and delivery feature. And four different serialisation formats appear in the direct list, one of them a byte-compiler JSON library with a separate loader, which suggests performance pressure on the request path. Two histogram libraries also appear, one direct and one pulled in transitively.

The only citable paper is a 2019 retail visual search system

The readme asks research users to cite one paper, and it is the only citable artefact the project offers. Its title describes the design and implementation of a real time visual search system on a large e-commerce platform, authored by seven people and dated 2019, with an arXiv identifier in the information retrieval category. That is a genuinely useful citation, and it is also a citation for something narrower than what the repository now is. The project is a general distributed vector database whose own headline is similarity search for artificial intelligence applications, with one worked use case documented, a visual search pipeline that needs an additional plugin for object detection and feature extraction. The paper predates the current architecture by seven years and describes none of the three components, the replication scheme or the interface. And the origin is never stated in prose anywhere: the retail platform appears only inside the citation's title, while the repository, the readme and the maintainers' mailing alias all present the project without a parent company. Read the paper if you want the original system, and say plainly which project you actually used.

Editorial conclusion

Vearch suits a team that wants a self-hosted distributed vector index with scalar filtering alongside vector search, that already runs containers or Kubernetes, and that can pick between a standalone and a clustered deployment from two configuration files. It does not suit anyone who wants a managed service or a small single-node library, and it does not suit a build pipeline that trusts a passing test target, because the target's own structure means a green result does not mean every group passed. Before you adopt it, run the test groups yourself with a fail-fast separator, pin the dependencies that are currently floating on untagged commits, and confirm that the configuration file you copied matches the deployment profile you selected. And if you cite it, cite carefully, because the only paper the project offers describes a narrower product from seven years ago.

Frequently asked questions

What is Vearch and what is it written in?

It is a cloud-native distributed vector database for similarity search over embedding vectors, with hybrid search combining vector retrieval and scalar filtering. The server is a Go module, with the vector index implemented on top of faiss, though the hosting site records the project's primary language as Python, which reflects its Python test harness and one of its four client libraries.

How do I deploy Vearch in standalone or cluster mode?

Both modes use the compose file, and each needs two choices to agree: copy one of two configuration files into the cloud directory, then start with the matching compose profile. The documentation does not say what happens if the copied configuration and the selected profile do not correspond. A chart route in a separate repository is also documented, in one form passing a values file and one not.

What are the main components of Vearch?

A master responsible for schema management, cluster-level metadata and resource coordination. A router that exposes the REST interface for upsert, delete, search and query, handles request routing and merges results. And partition servers that host document partitions with raft-based replication, running Gamma as the core vector search engine, which is implemented based on faiss and stores, indexes and retrieves vectors and scalars.

Which SDKs and AI framework integrations does Vearch have?

Four clients: Python, Go, Java and Rust. Four framework integrations, described as using it as a vector store or knowledge base: LangChain, LlamaIndex, a Go implementation of LangChain, and a Java implementation. The readme's language toggle row labels one of the two tutorial links in Chinese characters while the other is in English.

What should I cite if I use Vearch in research?

The project asks you to cite a 2019 paper on the design and implementation of a real time visual search system on a retail e-commerce platform, given as a BibTeX entry with an arXiv identifier, and to cite the original authors of anything else you use. No paper describing the current distributed vector database is offered.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. vearch/vearch on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/vearch-vearch.svg)](https://hysenlabs.com/projects/vearch-vearch)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/vearch-vearch.svg)](https://hysenlabs.com/projects/vearch-vearch)

Was this useful?