Vearch Cheat Sheet

Overview

Vearch is a distributed vector search engine developed by JD.com for large-scale embedding retrieval. It supports real-time vector indexing, scalar filtering combined with vector search, and multiple index types including HNSW, IVF-PQ, and GPU-accelerated indexes. Vearch is designed for production environments requiring low-latency search across billions of vectors.

The system provides a master-router-partition server architecture for horizontal scaling, RESTful APIs for CRUD operations, and built-in support for document storage alongside vector data. Vearch is used in recommendation systems, image search, NLP applications, and RAG pipelines where high throughput and low latency are critical.

Installation

Docker

# Pull and run Vearch
docker run -d --name vearch \
  -p 8817:8817 \
  -p 9001:9001 \
  -v vearch_data:/datas \
  vearch/vearch:latest all

# Port 8817: Router (query API)
# Port 9001: Master (management API)

Docker Compose

version: '3.8'
services:
  vearch:
    image: vearch/vearch:latest
    command: all
    ports:
      - "8817:8817"
      - "9001:9001"
    environment:
      - VEARCH_MASTER_ADDR=127.0.0.1:9001
    volumes:
      - vearch_data:/datas
      - ./config.toml:/vearch/config.toml

volumes:
  vearch_data:

Cluster Deployment

# Master node
docker run -d --name vearch-master \
  -p 9001:9001 \
  -v ./config.toml:/vearch/config.toml \
  vearch/vearch:latest master

# Router node
docker run -d --name vearch-router \
  -p 8817:8817 \
  -v ./config.toml:/vearch/config.toml \
  vearch/vearch:latest router

# Partition server nodes
docker run -d --name vearch-ps1 \
  -v ./config.toml:/vearch/config.toml \
  -v ps1_data:/datas \
  vearch/vearch:latest ps

Python Client

pip install pyvearch

Core Operations

Create Database and Space

# Create a database (namespace)
curl -X PUT http://localhost:9001/db/mydb \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mydb"
  }'

# Create a space (table/collection)
curl -X PUT http://localhost:9001/space/mydb/documents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "documents",
    "partition_num": 1,
    "replica_num": 1,
    "fields": [
      {"name": "text", "type": "string"},
      {"name": "source", "type": "string"},
      {"name": "timestamp", "type": "integer"},
      {
        "name": "embedding",
        "type": "vector",
        "dimension": 1536,
        "index": {
          "name": "gamma",
          "type": "HNSW",
          "params": {
            "metric_type": "InnerProduct",
            "nlinks": 32,
            "efConstruction": 200,
            "efSearch": 64
          }
        }
      }
    ]
  }'

Insert Documents

# Insert single document
curl -X POST http://localhost:8817/document/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "documents": [
      {
        "_id": "doc-001",
        "text": "Introduction to RAG systems",
        "source": "wiki",
        "timestamp": 1700000000,
        "embedding": {"feature": [0.1, 0.2, 0.3]}
      }
    ]
  }'

# Batch insert
curl -X POST http://localhost:8817/document/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "documents": [
      {"_id": "doc-002", "text": "Vector databases", "source": "docs", "timestamp": 1700000100, "embedding": {"feature": [0.4, 0.5, 0.6]}},
      {"_id": "doc-003", "text": "Embedding models", "source": "blog", "timestamp": 1700000200, "embedding": {"feature": [0.7, 0.8, 0.9]}}
    ]
  }'

Vector Search

# Basic vector search
curl -X POST http://localhost:8817/document/search \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "vectors": [
      {
        "field": "embedding",
        "feature": [0.1, 0.2, 0.3],
        "min_score": 0.5
      }
    ],
    "limit": 10,
    "fields": ["text", "source", "timestamp"]
  }'

# Search with scalar filter
curl -X POST http://localhost:8817/document/search \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "vectors": [
      {"field": "embedding", "feature": [0.1, 0.2, 0.3]}
    ],
    "filters": [
      {"field": "source", "operator": "=", "value": "wiki"},
      {"field": "timestamp", "operator": ">", "value": 1700000000}
    ],
    "limit": 5
  }'

# Multi-vector search
curl -X POST http://localhost:8817/document/search \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "vectors": [
      {"field": "embedding", "feature": [0.1, 0.2, 0.3], "boost": 0.7},
      {"field": "image_embedding", "feature": [0.4, 0.5], "boost": 0.3}
    ],
    "limit": 10
  }'

Index Types

Index	Description	Use Case
HNSW	Hierarchical navigable small world	Low latency, high recall
IVFPQ	Inverted file with product quantization	Large-scale, memory efficient
IVFFLAT	Inverted file with flat storage	Medium scale, exact scoring
FLAT	Brute-force search	Small datasets, exact results
GPU	GPU-accelerated search	High throughput batch queries

Python Client

import pyvearch

# Connect
client = pyvearch.Vearch(host="localhost", router_port=8817, master_port=9001)

# Create database
client.create_db("mydb")

# Create space
space_config = {
    "name": "documents",
    "partition_num": 1,
    "replica_num": 1,
    "fields": [
        {"name": "text", "type": "string"},
        {"name": "source", "type": "string"},
        {
            "name": "embedding",
            "type": "vector",
            "dimension": 1536,
            "index": {"type": "HNSW", "params": {"metric_type": "InnerProduct"}}
        }
    ]
}
client.create_space("mydb", space_config)

# Insert
docs = [
    {"_id": "1", "text": "RAG overview", "source": "wiki", "embedding": vector1},
    {"_id": "2", "text": "Vector search", "source": "docs", "embedding": vector2},
]
client.upsert("mydb", "documents", docs)

# Search
results = client.search("mydb", "documents", {
    "vectors": [{"field": "embedding", "feature": query_vec}],
    "limit": 10,
    "fields": ["text", "source"]
})

Configuration

config.toml

[global]
name = "vearch"
data = ["/datas/"]
log = "/log/"
level = "info"
signkey = "secret"

[masters]
  [masters.m1]
  name = "master1"
  address = "127.0.0.1"
  api_port = 9001
  etcd_port = 2378
  etcd_peer_port = 2390
  etcd_client_port = 2370

[routers]
  [routers.r1]
  port = 8817
  skip_auth = true

[ps]
  rpc_port = 8081
  raft_heartbeat_port = 8898
  raft_replicate_port = 8899
  heartbeat_interval = 200
  raft_retain_logs = 10000
  engine_dwpt_num = 8

Advanced Usage

Document CRUD

# Get document by ID
curl -X POST http://localhost:8817/document/query \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "document_ids": ["doc-001", "doc-002"]
  }'

# Update document
curl -X POST http://localhost:8817/document/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "documents": [
      {"_id": "doc-001", "text": "Updated text", "embedding": {"feature": [0.2, 0.3, 0.4]}}
    ]
  }'

# Delete documents
curl -X POST http://localhost:8817/document/delete \
  -H "Content-Type: application/json" \
  -d '{
    "db_name": "mydb",
    "space_name": "documents",
    "document_ids": ["doc-001"]
  }'

Cluster Management

# Get cluster status
curl http://localhost:9001/cluster/stats

# List databases
curl http://localhost:9001/list/db

# List spaces in database
curl http://localhost:9001/list/space/mydb

# Get space details
curl http://localhost:9001/space/mydb/documents

# Get partition info
curl http://localhost:9001/partitions

Troubleshooting

Issue	Solution
Connection refused	Check Docker is running, verify port mappings
Space creation fails	Verify vector dimension, check index params
Search returns empty	Ensure documents are indexed, check space name
Slow search latency	Tune HNSW params (efSearch), add more PS nodes
OOM on partition server	Reduce index memory footprint, use IVFPQ
Cluster node offline	Check network connectivity, restart failed node
Index build slow	Increase efConstruction for better build parallelism
Inconsistent results	Wait for replication, check replica_num setting

# View logs
docker logs vearch

# Health check
curl http://localhost:9001/cluster/health

# Force index rebuild
curl -X POST http://localhost:9001/space/mydb/documents/rebuild_index