Getting Started

Getting Started

Prerequisites

• Docker (recommended) — Docker 20+ with Docker Compose
• Or Rust 1.84+ for building from source

Docker Compose Quickstart

git clone https://github.com/aghatage/zeppelin.git
cd zeppelin
docker compose up

This starts:

• Zeppelin on http://localhost:8080
• MinIO (S3-compatible storage) on http://localhost:9000
• MinIO Console on http://localhost:9001 (login: minioadmin / minioadmin)

Wait for the health check to pass, then you're ready to go.

First API Calls

1. Create a namespace

curl -X POST http://localhost:8080/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_vectors",
    "dimensions": 4,
    "distance_metric": "cosine"
  }'

2. Upsert vectors

curl -X POST http://localhost:8080/v1/namespaces/my_vectors/vectors \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "id": "vec-1",
        "values": [0.1, 0.2, 0.3, 0.4],
        "attributes": {"color": "red", "price": 29.99}
      },
      {
        "id": "vec-2",
        "values": [0.5, 0.6, 0.7, 0.8],
        "attributes": {"color": "blue", "price": 49.99}
      },
      {
        "id": "vec-3",
        "values": [0.9, 0.1, 0.2, 0.3],
        "attributes": {"color": "red", "price": 19.99}
      }
    ]
  }'

3. Query

curl -X POST http://localhost:8080/v1/namespaces/my_vectors/query \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "top_k": 3
  }'

4. Query with filters

curl -X POST http://localhost:8080/v1/namespaces/my_vectors/query \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "top_k": 3,
    "filter": {
      "op": "and",
      "filters": [
        {"op": "eq", "field": "color", "value": "red"},
        {"op": "range", "field": "price", "lte": 30.0}
      ]
    }
  }'

5. Check health

curl http://localhost:8080/healthz
# {"status":"ok"}

curl http://localhost:8080/readyz
# {"status":"ready","s3_connected":true}

Building from Source

# Install Rust 1.84+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build
cargo build --release

# Run (requires S3 or MinIO)
export STORAGE_BACKEND=s3
export S3_BUCKET=zeppelin
export S3_ENDPOINT=http://localhost:9000
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export S3_ALLOW_HTTP=true

./target/release/zeppelin

Next Steps

• API Reference — Full endpoint documentation
• Python SDK / TypeScript SDK — Client libraries
• Configuration — Tuning and environment variables
• Full-Text Search — BM25 search setup