Getting Started

This page walks you from a fresh clone to your first vector search in under five minutes.

1. Build the native library

The C core has no external dependencies — just a C compiler and CMake 3.15+.

Windows (MSVC)

scripts\windows\build.bat Release

Linux (GCC/Clang)

bash scripts/linux/build.sh Release

macOS (Apple Clang)

bash scripts/macos/build.sh Release

The script auto-detects the host architecture and copies the artifact into libs/<os>/<arch>/ (e.g. libs/linux/x86_64/libpistadb.so). The produced library has zero runtime dependencies.

2. Install the Python wrapper

pip install -e wrap/python/

The wrapper auto-discovers libs/<os>/<arch>/ at import time, so no environment variable is required when working inside this checkout.

Using PistaDB from a separate Python project? See INTEGRATION.md for vendoring, PISTADB_LIB_DIR / PISTADB_LIB_PATH, and a Docker recipe.

3. Your first search

import numpy as np
from pistadb import PistaDB, Metric, Index, Params

# 1536-d HNSW index, cosine distance — good defaults for text embeddings
params = Params(hnsw_M=16, hnsw_ef_construction=200, hnsw_ef_search=50)

with PistaDB("mydb.pst", dim=1536,
             metric=Metric.COSINE, index=Index.HNSW, params=params) as db:

    # Insert a vector with an optional human-readable label
    vec = np.random.rand(1536).astype("float32")
    db.insert(1, vec, label="chunk_0001")

    # k-NN search
    query = np.random.rand(1536).astype("float32")
    results = db.search(query, k=10)
    for r in results:
        print(f"id={r.id}  dist={r.distance:.4f}  label={r.label!r}")

    db.save()  # flush to disk

That's the whole loop: insert, search, save. No server, no schemas required.

4. Run the test suite

To confirm everything links correctly:

Windows

set PISTADB_LIB_DIR=build\Release
pytest tests\ -v

Linux / macOS

PISTADB_LIB_DIR=build pytest tests/ -v

You should see 148 / 148 tests passing.

Where to next?

• Pick the right index algorithm for your workload.
• Use the Schema / Collection API when a single label isn't enough.
• See the language bindings for Go, Rust, Swift, Kotlin, C#, Julia, and WASM.