### Run RAG quickstart: start server and run script Source: https://github.com/achref-soua/quiver/blob/main/examples/rag/README.md Starts a local Quiver server in insecure dev mode and runs the RAG quickstart script. Requires installing the Python SDK first. Override target with QUIVER_URL / QUIVER_API_KEY if the server is elsewhere. ```bash # 1. Start a local server (insecure mode is dev-only) QUIVER_INSECURE=true QUIVER_API_KEYS=dev cargo run --release -p quiverdb-cli -- serve & # 2. Install the SDK and run the script pip install ./sdks/python python examples/rag/quickstart.py ``` -------------------------------- ### Install the quiver CLI with cargo install Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/quickstart.md Installs the `quiver` binary from crates.io as `quiverdb-cli` or from a cloned repo. Note that the `quiver-cli` name on crates.io is an unrelated third-party project; the `quiverdb-*` namespace is used (ADR-0056). ```bash # from crates.io (the `quiver` binary, published as quiverdb-cli): cargo install quiverdb-cli # …or from a cloned repo: cargo install --path crates/quiver-cli quiver serve # gRPC + REST, encrypted by default quiver tui # the cockpit quiver mcp # MCP server (stdio) for AI agents ``` -------------------------------- ### Clone and run the demo with just demo Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/quickstart.md Clones the repository, enters the directory, and runs `just demo` to build, start an encrypted server, and seed a demo collection. The server runs with encryption-at-rest enabled and prints how to open the cockpit. ```bash git clone https://github.com/achref-soua/quiver cd quiver just demo # build, start an encrypted server, seed a demo collection ``` -------------------------------- ### Development setup and test commands Source: https://github.com/achref-soua/quiver/blob/main/sdks/python/README.md Create the virtual environment and install dependencies with `uv sync`, then run the test suite with `uv run pytest` (HTTP mocked with respx). ```bash uv sync # create the venv and install dependencies uv run pytest # run the test suite (HTTP mocked with respx) ``` -------------------------------- ### Quiver Go SDK Quickstart Source: https://github.com/achref-soua/quiver/blob/main/sdks/go/README.md Shows core operations: create collection, upsert points, dense/hybrid/full-text search, server-side embedding, and snapshot. Requires a running server and an embedding provider for UpsertText/SearchText. ```go ctx := context.Background() c := quiver.New("http://localhost:8080", quiver.WithAPIKey("secret")) // Create a collection and add points. c.CreateCollection(ctx, "kb", 4, nil) c.Upsert(ctx, "kb", []quiver.Point{ {ID: "a", Vector: []float32{1, 0, 0, 0}, Payload: map[string]any{"lang": "en"}}, {ID: "b", Vector: []float32{0, 1, 0, 0}}, }) // Dense search. hits, _ := c.Search(ctx, "kb", []float32{1, 0, 0, 0}, &quiver.SearchOptions{K: 5}) // Hybrid (dense ⊕ BM25, fused with RRF). hits, _ = c.HybridSearch(ctx, "kb", &quiver.HybridOptions{ Vector: []float32{1, 0, 0, 0}, QueryText: "hello world", }) // Full-text only. hits, _ = c.HybridSearch(ctx, "kb", &quiver.HybridOptions{QueryText: "hello"}) // Server-side embedding (requires an [embedding.kb] provider on the server). c.UpsertText(ctx, "kb", []quiver.TextPoint{{ID: "d", Text: "the quick brown fox"}}) hits, _ = c.SearchText(ctx, "kb", "a fast fox", &quiver.SearchTextOptions{Rerank: true}) // Online backup (admin). info, _ := c.Snapshot(ctx, "/backups/snap1") _ = info ``` -------------------------------- ### Run Quiver demo with cargo Source: https://github.com/achref-soua/quiver/wiki/FAQ Starts a zero-configuration demo of Quiver using the CLI. No setup or configuration is required. ```bash cargo run -p quiverdb-cli -- demo ``` -------------------------------- ### Start Quiver server for benchmarking Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Start a Quiver server on the reference machine with the required environment variables and run it in the background. ```bash QUIVER_DATA_DIR=/tmp/quiver-ref QUIVER_API_KEY=ref-bench-key QUIVER_INSECURE=true \ ./target/release/quiver serve & ``` -------------------------------- ### Install quiver CLI from source (cargo install --path crates/quiver-cli) Source: https://github.com/achref-soua/quiver/blob/main/docs/roadmap.md Use this command to install the `quiver` binary from source because the `quiver-cli` name on crates.io is an unrelated third-party crate. This is the corrected installation method documented in v0.12.0. ```bash cargo install --path crates/quiver-cli ``` -------------------------------- ### Install nightly toolchain and cargo-fuzz Source: https://github.com/achref-soua/quiver/blob/main/docs/security/fuzzing.md Prerequisite setup for fuzzing. Requires a nightly toolchain and cargo-fuzz installed before building or running any fuzz target. ```bash rustup toolchain install nightly cargo install cargo-fuzz ``` -------------------------------- ### Open the cockpit with quiver tui Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/quickstart.md Starts the retro cockpit TUI in another terminal using the demo API key. Press `v` or `enter` on a collection to open the constellation view, a 2-D random-projection scatter with the query's nearest neighbour highlighted; move the cursor and press `enter` to re-query around any point. ```bash quiver tui --api-key quiver-demo-key # the retro cockpit ``` -------------------------------- ### Start Quiver server, TUI, and MCP server Source: https://github.com/achref-soua/quiver/blob/main/README.md Full server quick start: 'quiver serve' starts gRPC + REST on :6333 with encryption by default, 'quiver tui' opens the retro cockpit, and 'quiver mcp' starts the MCP server (stdio) for AI agents. ```bash quiver serve # gRPC + REST on :6333, encrypted by default quiver tui # the retro cockpit quiver mcp # MCP server (stdio) so AI agents can drive Quiver ``` -------------------------------- ### Development setup commands Source: https://github.com/achref-soua/quiver/blob/main/CONTRIBUTING.md Sets up the Rust development environment for Quiver. Requires Rust (stable) pinned by rust-toolchain.toml and the `just` task runner. Run `just build` to compile and `just verify` to pass the quality gate before pushing. ```bash cargo install just # task runner git clone https://github.com/achref-soua/quiver && cd quiver just build just verify # must pass before you push ``` -------------------------------- ### Install Quiver from package registries Source: https://github.com/achref-soua/quiver/blob/main/README.md Install the Quiver binary from crates.io, the Python SDK from PyPI, or the TypeScript SDK from npm. The crates publish under the quiverdb-* namespace; cargo install quiverdb-cli installs the same 'quiver' binary as the script installer. ```bash cargo install quiverdb-cli # the `quiver` binary, from crates.io pip install quiver-client # the Python SDK, from PyPI npm install quiver-client # the TypeScript SDK, from npm ``` -------------------------------- ### Install quiver-client with uv or pip Source: https://github.com/achref-soua/quiver/blob/main/sdks/python/README.md Install the Python client package. Use `uv add quiver-client` or `pip install quiver-client`. ```bash uv add quiver-client # or: pip install quiver-client ``` -------------------------------- ### Set Up Python Environment for LanceDB Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Creates a virtual environment and installs LanceDB, PyArrow, and NumPy for the LanceDB benchmark. ```powershell uv venv ; uv pip install lancedb pyarrow numpy ``` -------------------------------- ### Install Python competitor clients for comparison harness Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Install the Python clients required by the multi-DB comparison harness (ADR-0037) into the bench virtual environment. Run from the quiver repo root on the reference machine. ```bash # From the quiver repo root on the reference machine: /path/to/quiver/bench/.venv/bin/python -m pip install \ faiss-cpu lancedb pyarrow chromadb pymilvus milvus-lite \ qdrant-client psycopg2-binary weaviate-client ``` -------------------------------- ### Run Quiver demo with zero configuration Source: https://github.com/achref-soua/quiver/blob/main/README.md Starts a zero-config first run that seeds two collections (a text-searchable 'articles' set and 1,000 synthetic vectors for the constellation), starts the REST server on :7333, and opens the retro cockpit. No config files, env vars, or external downloads are needed. ```bash quiver demo ``` -------------------------------- ### Install Quiver on Linux/macOS with curl Source: https://github.com/achref-soua/quiver/blob/main/README.md One-command installer for Linux and macOS that detects OS and architecture, downloads the pre-built binary from the latest GitHub Release, verifies its SHA-256 checksum, and installs to ~/.local/bin. On Linux it also creates a .desktop entry and app-launcher icon; on macOS it creates a Quiver.app bundle. Set QUIVER_VERSION=1.0.0 to pin a specific version. ```bash curl -fsSL https://raw.githubusercontent.com/achref-soua/quiver/main/scripts/install.sh | sh ``` -------------------------------- ### Build Quiver from source and run demo Source: https://github.com/achref-soua/quiver/blob/main/README.md Build from source requires rustup stable, just, and uv. Clones the repo, builds and starts an encrypted server with a demo collection, then opens the retro cockpit with the demo API key. The cockpit supports pressing 'v' or 'enter' to open the constellation view. ```bash git clone https://github.com/achref-soua/quiver cd quiver just demo # build, start an encrypted server, seed a demo collection # then, in another terminal: quiver tui --api-key quiver-demo-key # the retro cockpit ``` -------------------------------- ### Reproduce SIFT1M recall@10 with sift_recall example Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/results/sift1m.md Run the release example `sift_recall` against the SIFT1M dataset files to reproduce the recall@10 benchmark. Requires fetching SIFT1M into `bench/datasets/sift1m/` (git-ignored) first. The command passes the base, query, and ground truth files as arguments. ```bash # fetch SIFT1M into bench/datasets/sift1m/ (git-ignored), then: cargo run --release --example sift_recall -- \ bench/datasets/sift1m/sift_base.fvecs \ bench/datasets/sift1m/sift_query.fvecs \ bench/datasets/sift1m/sift_groundtruth.ivecs ``` -------------------------------- ### TypeScript SDK usage with quiver-client Source: https://github.com/achref-soua/quiver/blob/main/README.md Install via `npm install quiver-client` or `pnpm add ./sdks/typescript` from a checkout. Dependency-free over global fetch; can use disk index with `disk_vamana` and `pqSubspaces`. Creates collection, upserts point, and searches. ```typescript import { Client } from "quiver-client"; const q = new Client("http://127.0.0.1:6333", { apiKey: "…" }); await q.createCollection("items", 3, { metric: "cosine", index: "disk_vamana", pqSubspaces: 1 }); await q.upsert("items", [{ id: "a", vector: [0.1, 0.2, 0.3], payload: { tag: "x" } }]); const hits = await q.search("items", [0.1, 0.2, 0.3], { k: 5 }); ``` -------------------------------- ### Install Quiver on Windows with PowerShell Source: https://github.com/achref-soua/quiver/blob/main/README.md One-command installer for Windows PowerShell 5.1+ that detects OS and architecture, downloads the pre-built binary from the latest GitHub Release, verifies its SHA-256 checksum, and installs to %LOCALAPPDATA%\quiver\bin. The binary has the icon embedded natively. Set QUIVER_VERSION=1.0.0 to pin a specific version. ```powershell irm https://raw.githubusercontent.com/achref-soua/quiver/main/scripts/install.ps1 | iex ``` -------------------------------- ### Install Quiver Helm chart with master key and API key Source: https://github.com/achref-soua/quiver/blob/main/infra/helm/quiver/README.md Generates a 256-bit master key and an API key, then installs the Quiver Helm chart with the required encryption.masterKey and apiKeys values. The install fails fast unless encryption.masterKey, encryption.existingSecret, or encryption.insecure=true is set. ```bash KEY=$(openssl rand -hex 32) helm install quiver ./infra/helm/quiver \ --set image.repository=ghcr.io/achref-soua/quiver \ --set encryption.masterKey="$KEY" \ --set apiKeys="$(openssl rand -hex 24)" ``` -------------------------------- ### Quiver Read Command with Status Source: https://github.com/achref-soua/quiver/blob/main/docs/quiver-explained.pdf Example command to read data with a completion status indicator. ```bash quiver@cockpit:~$./read--status=complete ✓ ``` -------------------------------- ### Run Quiver server with quiver serve Source: https://github.com/achref-soua/quiver/wiki/FAQ Starts the Quiver server. Requires the QUIVER_API_KEYS and QUIVER_ENCRYPTION_KEY environment variables to be set. ```bash quiver serve ``` -------------------------------- ### Python SDK usage with quiver-client Source: https://github.com/achref-soua/quiver/blob/main/README.md Install via `pip install quiver-client` or `pip install ./sdks/python` from a checkout. Creates a collection with dimension 3 and cosine metric, upserts a point with payload, and searches with k=5. ```python from quiver import Client, Point with Client("http://127.0.0.1:6333", api_key="…") as q: q.create_collection("items", dim=3, metric="cosine") q.upsert("items", [Point("a", [0.1, 0.2, 0.3], {"tag": "x"})]) hits = q.search("items", [0.1, 0.2, 0.3], k=5) ``` -------------------------------- ### Install quiver-client with pnpm Source: https://github.com/achref-soua/quiver/blob/main/sdks/typescript/README.md Install the dependency-free TypeScript/JavaScript client for Quiver. Requires Node >= 20 or a modern runtime with global fetch. ```bash pnpm add quiver-client ``` -------------------------------- ### Go: Initialize client and perform basic operations Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/sdks.md Install from sdks/go, standard-library only. Create a client with an API key, then create a collection, upsert a point, and run a hybrid search. Every call takes a context.Context; non-2xx responses return a typed *quiver.APIError. ```go import quiver "github.com/achref-soua/quiver/sdks/go" c := quiver.New("http://127.0.0.1:8080", quiver.WithAPIKey("…")) c.CreateCollection(ctx, "items", 3, &quiver.CreateCollectionOptions{Metric: "cosine"}) c.Upsert(ctx, "items", []quiver.Point{{ID: "a", Vector: []float32{0.1, 0.2, 0.3}}}) hits, _ := c.HybridSearch(ctx, "items", &quiver.HybridOptions{QueryText: "hello"}) ``` -------------------------------- ### Generate encryption key and start server Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/self-hosting.md Sets QUIVER_ENCRYPTION_KEY to a random 256-bit hex key and starts the server. Encryption at rest is on by default; the key is a master key that wraps per-collection data-encryption keys. ```bash export QUIVER_ENCRYPTION_KEY=$(openssl rand -hex 32) quiver serve ``` -------------------------------- ### Sample steady-state RSS of disk_recall process Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md While `serve` waits, run this in a second PowerShell to get the steady-state resident set size in MB. Record the RSS at the `l_search` that hits your chosen recall operating point (see §7). ```powershell (Get-Process disk_recall).WorkingSet64 / 1MB # steady-state RSS in MB ``` -------------------------------- ### Import Quiver Go SDK Source: https://github.com/achref-soua/quiver/blob/main/sdks/go/README.md Import the Quiver Go SDK package using its module path. ```go import quiver "github.com/achref-soua/quiver/sdks/go" ``` -------------------------------- ### GET /readyz Source: https://github.com/achref-soua/quiver/blob/main/docs/api/rest-grpc.md Readiness check endpoint for operational monitoring. ```APIDOC ## [GET] /readyz ### Description Readiness check endpoint for operational monitoring. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - **status** (string) - Readiness status ``` -------------------------------- ### Publish wiki pages to quiver.wiki.git Source: https://github.com/achref-soua/quiver/blob/main/docs/wiki/README.md One-time setup requires creating the first wiki page via the web UI before cloning. Clones the wiki repo, copies Home.md and FAQ.md, then commits and pushes. ```bash git clone https://github.com/achref-soua/quiver.wiki.git cp docs/wiki/Home.md docs/wiki/FAQ.md quiver.wiki/ cd quiver.wiki && git add -A && git commit -m "docs(wiki): home hub + faq" && git push ``` -------------------------------- ### First query with the Python SDK Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/quickstart.md Creates a client, creates a collection with dimension 3 and cosine metric, upserts a point with metadata, and searches for the nearest neighbours. The same flow is available over REST & gRPC, the MCP server, and the TypeScript SDK. ```python from quiver import Client, Point with Client("http://127.0.0.1:6333", api_key="…") as q: q.create_collection("items", dim=3, metric="cosine") q.upsert("items", [Point("a", [0.1, 0.2, 0.3], {"tag": "x"})]) hits = q.search("items", [0.1, 0.2, 0.3], k=5) print(hits) ``` -------------------------------- ### Run Quiver Go SDK Tests Source: https://github.com/achref-soua/quiver/blob/main/sdks/go/README.md Runs formatting, vetting, and tests using httptest mocks; no server needed. ```sh just test-go # gofmt -l + go vet + go test (httptest-mocked; no server needed) ``` -------------------------------- ### Run Qdrant Docker Container Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Starts a Qdrant container with ports 6333 and 6334 exposed. Replace with a specific version tag for reproducibility. ```powershell docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant: ``` -------------------------------- ### Install Quiver Helm chart with encryption key and API key Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/kubernetes.md Generates a 256-bit master key and installs the Quiver Helm chart with the image repository, tag, master key, and API key. The master key is generated once and kept safe; rotating it re-encrypts data. The install fails fast unless a key strategy is provided. ```bash # A 256-bit master key, generated once and kept safe (rotating it re-encrypts). KEY=$(openssl rand -hex 32) helm install quiver ./infra/helm/quiver \ --set image.repository=ghcr.io/achref-soua/quiver \ --set image.tag=0.20.1 \ --set encryption.masterKey="$KEY" \ --set apiKeys="$(openssl rand -hex 24)" ``` -------------------------------- ### Run unit tests Source: https://github.com/achref-soua/quiver/blob/main/bench/README.md Installs dependencies and runs metric and ground-truth unit tests without requiring a server. ```bash uv sync && uv run pytest # metric + ground-truth unit tests (no server) ``` -------------------------------- ### Run a Quiver leader and follower with QUIVER_LEADER_URL Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/features/replication.md Start a normal Quiver server as the leader, then start a follower with QUIVER_LEADER_URL pointing at the leader's gRPC address and QUIVER_LEADER_API_KEY set to an admin key on the leader. The follower bootstraps a full snapshot, then streams the live commit tail; it serves reads and refuses writes (HTTP 403 / gRPC PermissionDenied). ```bash # Leader — a normal server QUIVER_GRPC_ADDR=0.0.0.0:6334 quiver serve ``` ```bash # Follower — a read replica of that leader QUIVER_LEADER_URL=http://leader-host:6334 \ QUIVER_LEADER_API_KEY= \ QUIVER_GRPC_ADDR=0.0.0.0:7334 quiver serve ``` -------------------------------- ### Build and preview commands for Quiver docs site Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/README.md Install mdBook once, build the docs to apps/docs/book/, and serve a live-reload preview on http://localhost:3000. Use 'just docs' as an alternative to 'mdbook build apps/docs'. ```bash cargo install mdbook # once just docs # build to apps/docs/book/ (or: mdbook build apps/docs) mdbook serve apps/docs # live-reload preview on http://localhost:3000 ``` -------------------------------- ### Build and serve the disk index with disk_recall example Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/results/disk-path.md Two-phase workflow: first build the encrypted disk index (RAM-heavy, one-time), then serve it so only PQ codes are resident. Measure the serve process's RSS for the frugal footprint. Run from the project root with the release profile. ```bash # build the encrypted disk index (RAM-heavy, one-time) cargo run --release --example disk_recall -- build \ bench/datasets/siftsmall/siftsmall_base.fvecs /tmp/sift.qvx ``` ```bash # serve it (only PQ codes resident) — measure this process's RSS cargo run --release --example disk_recall -- serve \ /tmp/sift.qvx bench/datasets/siftsmall/siftsmall_query.fvecs \ bench/datasets/siftsmall/siftsmall_groundtruth.ivecs ``` -------------------------------- ### get Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/mcp.md Fetches a single point by ID. ```APIDOC ## get ### Description Fetch one point. ### Arguments - `collection` (string) - Required - The collection name. - `id` (string) - Required - Point ID. ``` -------------------------------- ### Development commands for quiver-client Source: https://github.com/achref-soua/quiver/blob/main/sdks/typescript/README.md Install dependencies, typecheck with tsc --noEmit, run tests with vitest, and build to dist/ as ESM with .d.ts files. ```bash pnpm install pnpm typecheck # tsc --noEmit pnpm test # vitest pnpm build # tsc -> dist/ (ESM + .d.ts) ``` -------------------------------- ### LangChain VectorStore adapter with QuiverVectorStore Source: https://github.com/achref-soua/quiver/blob/main/sdks/python/README.md Use the LangChain `VectorStore` adapter from `quiver.langchain` (install `quiver-client[langchain]`). Create a store from texts with an embedding function and client, then run similarity search. ```python from quiver import Client from quiver.langchain import QuiverVectorStore store = QuiverVectorStore.from_texts( texts, embedding, client=Client(api_key="…"), collection="docs", index="disk_vamana", pq_subspaces=48, ) docs = store.similarity_search("query", k=4) ``` -------------------------------- ### GET /v1/collections Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/rest-grpc.md Lists all collections using cursor-based pagination. ```APIDOC ## GET /v1/collections ### Description Lists all collections using cursor-based pagination. ### Method GET ### Endpoint /v1/collections ### Response #### Success Response (200) - **collections** (array) - List of collections - **next_cursor** (string) - Cursor for the next page ``` -------------------------------- ### quiver serve command Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/cli.md Runs the server (gRPC + REST) with no flags; configuration comes entirely from `quiver.toml` and `QUIVER_*` environment variables. The example shows setting `QUIVER_API_KEYS` and `QUIVER_ENCRYPTION_KEY` before invoking `quiver serve`. ```bash QUIVER_API_KEYS=… QUIVER_ENCRYPTION_KEY=… quiver serve ``` -------------------------------- ### Serve imported data with the same encryption key Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/features/migration.md Start the Quiver server with the same `QUIVER_ENCRYPTION_KEY` used during import, because the importer writes the same encrypted format the server reads. `data_dir` defaults to `./data`. ```bash QUIVER_ENCRYPTION_KEY= quiver serve # data_dir defaults to ./data ``` -------------------------------- ### Run MCP server in insecure development mode Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/mcp.md Starts the MCP server without encryption at rest. Intended for development only. ```bash quiver mcp --data-dir ./data --insecure ``` -------------------------------- ### Python: Create client-side encrypted collection and search Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/security/client-side-vectors.md Uses VectorCipher.from_hex with a 64-hex-char key, creates a collection with vector_encryption="client_side", upserts a zero placeholder vector plus the sealed blob, and ranks client-side via search_client_side. Requires pip install quiver-client[encryption]. ```python from quiver import Client from quiver.vector import VectorCipher # pip install quiver-client[encryption] cipher = VectorCipher.from_hex("…64 hex chars…") with Client("https://…", api_key="…") as q: q.create_collection("vault", dim=8, metric="l2", vector_encryption="client_side") vec = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] # A zero placeholder vector + the sealed blob (and any cleartext fields). q.upsert("vault", [{"id": "a", "vector": [0.0] * 8, "payload": {"tier": "gold", **cipher.seal(vec)}}]) # Fetch + decrypt + rank, entirely client-side: hits = q.search_client_side("vault", my_query, cipher, k=10) ``` -------------------------------- ### Run asynchronous read replica Source: https://github.com/achref-soua/quiver/blob/main/README.md Starts a Quiver server as an asynchronous read replica by pointing it at a leader with QUIVER_LEADER_URL and QUIVER_LEADER_API_KEY. The follower continuously applies the leader's committed operations and serves reads, lagging by the replication delay. Followers refuse writes; this is an advanced feature without consensus or failover. ```bash QUIVER_LEADER_URL=http://leader-host:6334 QUIVER_LEADER_API_KEY= quiver serve ``` -------------------------------- ### Error message when release asset is missing Source: https://github.com/achref-soua/quiver/blob/main/docs/adr/0044-automated-release-assets.md Example error output when quiver update fails to download a missing release asset, showing the 404 URL for the Windows binary. ```text Error: failed to download https://github.com/achref-soua/quiver/releases/download/v0.18.0/quiver-windows-x86_64.exe ``` -------------------------------- ### DCPE encryption example in Python Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/sdks.md Encrypt vectors before upsert and queries before search using the DcpeCipher from the optional quiver.dcpe module. Requires installing the audited crypto peer dependency with `pip install quiver-client[dcpe]`. The cipher is created from a 64-character hex key with an approximation factor of 0.02. ```python from quiver import Client from quiver.dcpe import DcpeCipher # pip install quiver-client[dcpe] cipher = DcpeCipher.from_hex("…64 hex chars…", approximation_factor=0.02) with Client("https://…", api_key="…") as q: q.create_collection("vault", dim=8, metric="l2", vector_encryption="dcpe") sealed = cipher.encrypt([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]) q.upsert("vault", [{"id": "a", "vector": sealed.ciphertext}]) hits = q.search("vault", cipher.encrypt_query(my_query), k=10) ``` -------------------------------- ### Quick smoke run with synthetic dataset Source: https://github.com/achref-soua/quiver/blob/main/bench/README.md Starts a Quiver server in the background (dev only) and runs the synthetic smoke set to validate the harness without downloading a dataset. Requires QUIVER_INSECURE=true for the server. ```bash QUIVER_INSECURE=true cargo run -p quiverdb-cli -- serve & # dev only uv run --project bench python -m quiver_bench.run --synthetic ``` -------------------------------- ### Run full comparison benchmark (sift1m and deep10m) Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Run the full multi-DB comparison using `just bench-compare`. The first command benchmarks all competitors on sift1m; the second benchmarks a subset on deep10m (10M vectors) as the memory headline. ```bash # In-process competitors (FAISS, LanceDB, Chroma, Milvus Lite) + Docker ones: just bench-compare --dataset sift1m --competitors all \ --quiver-url http://127.0.0.1:6333 --quiver-key ref-bench-key \ --out /path/to/results ``` ```bash # Deep10M (the memory headline — 10M vectors): just bench-compare --dataset deep10m --competitors faiss,lancedb,qdrant,quiver \ --quiver-url http://127.0.0.1:6333 --quiver-key ref-bench-key \ --out /path/to/results ``` -------------------------------- ### Build and serve encrypted disk index with disk_recall Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md Manual steps for §4: `build` creates the encrypted disk index (RAM-heavy, one-time) and prints on-disk index size plus RAM-resident PQ-code footprint vs full-precision. `serve` loads only PQ codes into RAM, prints recall@10 and QPS per `l_search`, then waits so you can sample its resident set. ```powershell # Build the encrypted disk index (RAM-heavy, one-time). cargo run --release --example disk_recall -- build C:\data\sift\sift_base.fvecs C:\data\sift.qvx ``` ```powershell # Serve it: only the PQ codes are RAM-resident. The process holds at the end so # you can sample its resident set. cargo run --release --example disk_recall -- serve C:\data\sift.qvx ` C:\data\sift\sift_query.fvecs C:\data\sift\sift_groundtruth.ivecs ``` -------------------------------- ### Clone and run automated disk-frugality benchmark Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/reference-hardware-runbook.md One-command measurement for §4: fetches the dataset, builds the disk index, serves it, samples steady-state serving RSS, and emits a verdict plus JSON. Defaults to `siftsmall`; pass `-Dataset sift1m` or `-Dataset gist1m` for scale. Output lands in `bench\results\windows-local\`. ```powershell git clone https://github.com/achref-soua/quiver ; cd quiver powershell -ExecutionPolicy Bypass -File scripts\bench-disk-frugality.ps1 -Dataset sift1m ``` -------------------------------- ### DCPE encryption example in TypeScript Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/sdks.md Encrypt vectors before upsert and queries before search using the DcpeCipher from the optional quiver-client/dcpe module. Requires installing the audited crypto peer dependencies with `pnpm add @stablelib/{chacha,hkdf,hmac,sha256}`. The cipher is created from a 64-character hex key with an approximation factor of 0.02. ```typescript import { DcpeCipher } from "quiver-client/dcpe"; // pnpm add @stablelib/{chacha,hkdf,hmac,sha256} const cipher = DcpeCipher.fromHex("…64 hex chars…", 0.02); const sealed = cipher.encrypt([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]); // upsert sealed.ciphertext; search with cipher.encryptQuery(myQuery). ``` -------------------------------- ### Install optional encryption peer dependency Source: https://github.com/achref-soua/quiver/blob/main/sdks/typescript/README.md Install @stablelib/xchacha20poly1305 to use client-side payload encryption. The core client stays dependency-free; the encryption helper is at the quiver-client/encryption subpath. ```bash pnpm add @stablelib/xchacha20poly1305 ``` -------------------------------- ### Build and verify Quiver workspace Source: https://github.com/achref-soua/quiver/blob/main/README.md Compile the workspace, run the full local quality gate (lint, test, doc, deny, audit), and show the CLI help. Use these commands to build and exercise the workspace directly. ```bash just build # compile the workspace just verify # the full local quality gate (lint · test · doc · deny · audit) cargo run -p quiverdb-cli -- --help ``` -------------------------------- ### GET /metrics Source: https://github.com/achref-soua/quiver/blob/main/docs/api/rest-grpc.md Metrics endpoint for operational monitoring. ```APIDOC ## [GET] /metrics ### Description Metrics endpoint for operational monitoring. ### Method GET ### Endpoint /metrics ### Response #### Success Response (200) - **metrics** (object) - Metrics data ``` -------------------------------- ### GET /cluster/map Source: https://github.com/achref-soua/quiver/blob/main/CHANGELOG.md Retrieves the cluster map. Requires any valid key due to default-deny RBAC. ```APIDOC ## [GET] /cluster/map ### Description Retrieves the cluster map. Requires any valid key due to default-deny RBAC. ### Method GET ### Endpoint /cluster/map ### Response #### Success Response (200) - **map** (object) - The cluster map. ### Request Example ``` GET /cluster/map ``` ### Response Example ``` { "map": {} } ``` ``` -------------------------------- ### GET /healthz Source: https://github.com/achref-soua/quiver/blob/main/docs/api/rest-grpc.md Health check endpoint for operational monitoring. ```APIDOC ## [GET] /healthz ### Description Health check endpoint for operational monitoring. ### Method GET ### Endpoint /healthz ### Response #### Success Response (200) - **status** (string) - Health status ``` -------------------------------- ### Run Quiver with Docker Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/self-hosting.md Builds the image with `just docker` and runs the container, mapping ports 6333 and 6334, setting the encryption key, and mounting a volume for data. The image is multi-stage and runs as a non-root user. ```bash just docker # build the image (infra/docker/Dockerfile) docker run --rm -p 6333:6333 -p 6334:6334 \ -e QUIVER_ENCRYPTION_KEY=$(openssl rand -hex 32) \ -v quiver-data:/data quiver:dev serve ``` -------------------------------- ### GET /cluster/health Source: https://github.com/achref-soua/quiver/blob/main/CHANGELOG.md Retrieves cluster health status. Requires any valid key due to default-deny RBAC. ```APIDOC ## [GET] /cluster/health ### Description Retrieves cluster health status. Requires any valid key due to default-deny RBAC. ### Method GET ### Endpoint /cluster/health ### Response #### Success Response (200) - **status** (string) - Health status. ### Request Example ``` GET /cluster/health ``` ### Response Example ``` { "status": "healthy" } ``` ``` -------------------------------- ### quiver CLI usage overview Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/cli.md Shows the top-level `quiver` command and its subcommands: serve, tui, mcp, admin, bench, update, and demo. Use `quiver --help` to see details for each command. ```text Usage: quiver Commands: serve Run the server (gRPC + REST) tui Launch the terminal cockpit mcp Run the MCP server for AI agents (JSON-RPC over stdio) admin Administrative commands (imports, collections, keys) bench Run benchmarks update Check for a newer release and optionally install it demo Zero-config demo: seeds vectors, starts the server, opens the cockpit ``` -------------------------------- ### GET /v1/collections/{id}/points/{point_id} Source: https://github.com/achref-soua/quiver/blob/main/docs/api/rest-grpc.md Retrieves a single point by its ID. ```APIDOC ## [GET] /v1/collections/{id}/points/{point_id} ### Description Retrieves a single point by its ID. ### Method GET ### Endpoint /v1/collections/{id}/points/{point_id} ### Parameters #### Path Parameters - **id** (string) - Required - Collection ID - **point_id** (string) - Required - Point ID ### Response #### Success Response (200) - **point** (object) - The requested point ``` -------------------------------- ### just bench-compare and bench-report recipes Source: https://github.com/achref-soua/quiver/blob/main/docs/adr/0037-scientific-multi-db-benchmark-suite.md Defines two just recipes: bench-compare runs the comparison module with optional arguments, and bench-report generates the report from the results directory. ```justfile bench-compare *ARGS: uv run --project bench python -m quiver_bench.comparison {{ ARGS }} bench-report: uv run --project bench python -m quiver_bench.report \ docs/benchmarks/results/comparison-v0.17.0 ``` -------------------------------- ### Run live acceptance test with just acceptance Source: https://github.com/achref-soua/quiver/blob/main/docs/testing/manual-acceptance.md Boots a real encrypted server, drives REST, both SDKs, CLI, and MCP. This is the live end-to-end run that crosses a real socket and is also run in CI. ```bash just acceptance # boots a real encrypted server, drives REST + both SDKs + CLI + MCP ``` -------------------------------- ### Run contention sweep benchmark with quiver_bench Source: https://github.com/achref-soua/quiver/blob/main/docs/benchmarks/results/read-during-write.md Prebuild the server binary with `cargo build --release -p quiverdb-cli` before running; never `cargo build` mid-run on the shared box. Then execute the contention sweep with the specified dataset, workers, duration, writers, batches, MVCC modes, and output directory. ```bash # prebuild the server binary first; never `cargo build` mid-run on the shared box cargo build --release -p quiverdb-cli PATH="$PWD/target/release:$PATH" uv run --project bench \ python -m quiver_bench.contention_sweep \ --dataset siftsmall --workers 8 --duration 4 \ --writers 1,2,4 --batches 1,64,512 --mvcc both \ --out docs/benchmarks/results/contention ``` -------------------------------- ### GET /cluster/map Source: https://github.com/achref-soua/quiver/blob/main/docs/api/rest-grpc.md Returns the shard map that a router has adopted. Returns 404 on a non-router server. This endpoint is read-only. ```APIDOC ## [GET] /cluster/map ### Description Returns the shard map that a router has adopted. Returns 404 on a non-router server. This endpoint is read-only. ### Method GET ### Endpoint /cluster/map ### Response #### Success Response (200) - **shard_map** (object) - The adopted shard map #### Error Response (404) - **error** (object) - Not found on non-router server ``` -------------------------------- ### snapshot Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/mcp.md Takes a consistent online backup of the whole database into a server-local directory. ```APIDOC ## snapshot ### Description Take a consistent online backup of the whole database into a server-local directory (ADR-0050). ### Arguments - `destination` (string) - Required - Server-local directory path for the backup. ``` -------------------------------- ### GET /v1/collections/{id} Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/rest-grpc.md Retrieves a single collection by its ID. The response echoes the collection's index configuration and filterable fields. ```APIDOC ## GET /v1/collections/{id} ### Description Retrieves a single collection by its ID. The response echoes the collection's index configuration and filterable fields. ### Method GET ### Endpoint /v1/collections/{id} ### Parameters #### Path Parameters - **id** (string) - Required - Collection ID ### Response #### Success Response (200) - **index** (string) - The selected index type - **pq_subspaces** (integer) - Quantized subspaces if set - **filterable** (array) - Declared filterable fields ``` -------------------------------- ### listCollections() / getCollection(name) / deleteCollection(name) Source: https://github.com/achref-soua/quiver/blob/main/sdks/typescript/README.md Collection CRUD operations: list all collections, get a specific collection, or delete a collection. ```APIDOC ## listCollections() / getCollection(name) / deleteCollection(name) ### Description Collection CRUD operations. ### Methods - `listCollections()` - List all collections - `getCollection(name)` - Get a collection by name - `deleteCollection(name)` - Delete a collection by name ### Parameters - **name** (string) - Required - Collection name (for get/delete) ``` -------------------------------- ### Quiver TUI Command Source: https://github.com/achref-soua/quiver/blob/main/docs/quiver-explained.pdf Command to launch the Quiver terminal user interface (TUI) for a live dashboard and interactive query runner. ```bash quiver tui ``` -------------------------------- ### Live import from Chroma Source: https://github.com/achref-soua/quiver/blob/main/README.md Imports a collection live from a running Chroma instance without an export step. Preserves ids, vectors, and payloads, and writes the same encrypted format the server reads. Requires the Chroma server URL and an admin API key. ```bash quiver admin import --source chroma --chroma-url http://localhost:8000 \ --collection docs --data-dir ./data --metric cosine ``` -------------------------------- ### Over-fetch and rerank with CrossEncoder and quiver.rerank Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/guides/rag.md Over-fetches 50 results, re-scores them with a cross-encoder, and trims to the top 4 using the quiver.rerank helper. Requires installing sentence-transformers and providing a scorer function. ```python # pip install sentence-transformers from sentence_transformers import CrossEncoder from quiver import rerank ce = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2") hits = q.search("kb", embed(question), k=50) # over-fetch top = rerank(question, hits, lambda query, texts: ce.predict([(query, t) for t in texts]), key="text", top_k=4) # best-first RerankResults context = "\n\n".join(r.match.payload["text"] for r in top) ``` -------------------------------- ### Import from export file (Qdrant) Source: https://github.com/achref-soua/quiver/blob/main/README.md Imports a Qdrant collection from a JSONL export file into a Quiver store, preserving ids, vectors, and payloads. Optionally declares --filterable path:type fields for hybrid search. The result is an ordinary Quiver store that can be served immediately. ```bash quiver admin import --source qdrant --input qdrant.jsonl \ --collection my_collection --data-dir ./data --metric cosine ``` -------------------------------- ### DcpeCipher Source: https://github.com/achref-soua/quiver/blob/main/apps/docs/src/api/sdks.md DCPE encrypted search (experimental). Available as optional subpath modules: Python `quiver.dcpe`, TypeScript `quiver-client/dcpe`. Example shows encrypting vectors before upsert and queries before search with the same cipher. ```APIDOC ## DcpeCipher ### Description [DCPE](../security/dcpe.md) encrypted search (experimental). Available as optional subpath modules: Python `quiver.dcpe`, TypeScript `quiver-client/dcpe`. Example shows encrypting vectors before upsert and queries before search with the same cipher. ### Method SDK helper ### Endpoint `DcpeCipher` ### Parameters - **from_hex** (string) - Required - 64 hex chars - **approximation_factor** (number) - Required - Approximation factor for DCPE. ### Response No response details provided. ### Request Example ```python from quiver import Client from quiver.dcpe import DcpeCipher # pip install quiver-client[dcpe] cipher = DcpeCipher.from_hex("…64 hex chars…", approximation_factor=0.02) with Client("https://…", api_key="…") as q: q.create_collection("vault", dim=8, metric="l2", vector_encryption="dcpe") sealed = cipher.encrypt([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]) q.upsert("vault", [{"id": "a", "vector": sealed.ciphertext}]) hits = q.search("vault", cipher.encrypt_query(my_query), k=10) ``` ```ts import { DcpeCipher } from "quiver-client/dcpe"; // pnpm add @stablelib/{chacha,hkdf,hmac,sha256} const cipher = DcpeCipher.fromHex("…64 hex chars…", 0.02); const sealed = cipher.encrypt([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]); // upsert sealed.ciphertext; search with cipher.encryptQuery(myQuery). ``` ``` -------------------------------- ### Run multi-DB comparison on GIST1M Source: https://github.com/achref-soua/quiver/blob/main/bench/README.md Runs the multi-DB comparison runner on GIST1M (1M x 960, L2) with concurrency 16, downloading and caching the dataset on first use (~2.6 GB). Writes results to docs/benchmarks/results/comparison-v0.18.0. ```bash # GIST1M (1M x 960, L2) — downloaded + cached on first use (~2.6 GB) uv run --project bench python -m quiver_bench.comparison \ --dataset gist1m --competitors all --concurrency 16 \ --out docs/benchmarks/results/comparison-v0.18.0 ```