Vector Database Integrations

Vector fields route through the same workspace storage planner as SQL and search fields.

1. Why Vector Routing Exists

Vector providers differ in local versus remote lifecycle, filtering, exhaustive scans, index ownership, and supported distance metrics. HeavenBase keeps the Entity and query surface stable while Registry records, handlers, and explain() expose what one concrete route can actually do.

import heavenbase as hb

workspace = hb.HeavenBase("vector-demo", preset="debug")
print(workspace.backends.names())

2. Choose a Vector Backend

HeavenBase includes vector backend implementations for:

inmem for dependency-light local tests
pgvector for vectors beside PostgreSQL rows
lance for local LanceDB storage
milvus and milvus-lite for server and embedded Milvus deployments
chroma and pinecone for Chroma and hosted Pinecone indexes
qdrant for local-path or server deployments
weaviate for workspace-scoped remote collections
redisearch for Redis Stack vector and hybrid search

These ten usable routes include the multi-role inmem Backend plus nine concrete vector and hybrid providers. They do not promise identical native filtering or exhaustive enumeration; inspect the generated capability matrix and the concrete query plan.

3. Start from a Preset

The built-in debug workspace preset uses SQLite for rows plus in-memory vector and search backends:

import heavenbase as hb

workspace = hb.HeavenBase("demo", preset="debug")

The local-lts preset is shaped for a local stack with Postgres rows, LanceDB vectors, and Elasticsearch search:

workspace = hb.HeavenBase("agent-shop", preset="local-lts")

The Lance path uses the workspace id in its configured URI, so each workspace gets an isolated vector directory.

4. Use Explicit Backend Configuration

You can pass backend config directly when a test or application should avoid global presets:

workspace = hb.HeavenBase(
    "vector-demo",
    backends={
        "main": {"type": "sqlite", "database": ":memory:"},
        "vec": {"type": "inmem", "name": "vec"},
    },
)

Then define vector fields in normal entities:

class Issue(hb.Entity):
    title = hb.field(hb.ShortText)
    emb = hb.field(hb.Vector[3])

Queries use the same JSON and Python DSL surfaces:

workspace.query(Issue).near(Issue.emb, [1.0, 0.0, 0.0], top_k=5).execute()

5. Inspect the Concrete Route

plan = workspace.query(Issue).near(Issue.emb, [1.0, 0.0, 0.0], top_k=5).explain()
print(plan["steps"])

Milvus vector fields must be required because its rows cannot represent a missing FLOAT_VECTOR. Pinecone cannot prove exhaustive unbounded folds. Local Qdrant, Milvus Lite, and TinyDB-style paths remain explicitly workspace-owned; detached=True does not make their data temporary.

Summary

Choose from ten usable built-in vector routes, including local, embedded, and hosted providers.
Keep placement on named workspace Backends and query through the same typed surface.
Treat explain() as execution evidence instead of inferring behavior from a provider label.

Further Exploration

Related resources:

Backends - Backend capabilities and storage families
Routing - How field placement is planned
Query - JSON and Python query surfaces
Database integrations - SQL-family provider setup

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

Vector Database Integrations

1. Why Vector Routing Exists

2. Choose a Vector Backend

3. Start from a Preset

4. Use Explicit Backend Configuration

5. Inspect the Concrete Route

Summary

Further Exploration

​1. Why Vector Routing Exists

​2. Choose a Vector Backend

​3. Start from a Preset

​4. Use Explicit Backend Configuration

​5. Inspect the Concrete Route

​Summary

​Further Exploration

1. Why Vector Routing Exists

2. Choose a Vector Backend

3. Start from a Preset

4. Use Explicit Backend Configuration

5. Inspect the Concrete Route

Summary

Further Exploration