Skip to main content
Pick storage for the workload, keep one API for the data.

​
1. What a Backend Is

A backend is a physical storage provider registered inside a workspace. HeavenBase routes fields to backend instances by name, then uses handlers to compile supported query operations for each provider. For normal application code, you usually choose a preset and let the workspace build the backends. 
import heavenbase as hb

ws = hb.HeavenBase("core-backends", preset="debug")
print(ws.backends.names())
The debug preset creates three backend instances: main, vec, and search.

​
2. Built-In Backend Families

HeavenBase ships backend builders for local, SQL, vector, file, and search use cases.
FamilyBackend keysUse it for
Local memoryinmemTests, demos, temporary rows.
Local filesjson, pickle, fileSimple persistent local stores.
SQL rowssqlite, duckdb, postgres, pgvector, mysql, oceanbase, mssql, oracle, trino, starrocksStructured row storage and SQL-native filters.
Vector storeslance, chroma, milvus, pinecone, pgvectorNative vector search.
SearchelasticsearchText search and search-engine-backed filters.
Optional providers require their Python drivers and, for server backends, reachable services. If a provider is unavailable, use debug or an explicit inmem/sqlite layout for examples and tests.

​
3. Configure a Custom Map

Explicit backend dictionaries use the workspace-local name as the key and the provider type inside the value. 
ws = hb.HeavenBase(
    "core-backends-explicit",
    backends={
        "main": {"type": "sqlite", "database": ":memory:"},
        "scratch": {"type": "inmem"},
    },
)

print(ws.backends.names())
Fields route to backend names, not provider types: 
class Event(hb.Entity):
    title = hb.field(hb.ShortText).store(to="main")
    payload = hb.field(hb.Json).store(to="scratch")


ws.register(Event)
ws.upsert(Event, {"object_id": "e1", "title": "Import complete", "payload": {"rows": 12}})
print(ws.get("e1", entity=Event)["payload"]["rows"])

​
4. Discover Capabilities

Use hb.capabilities for globally registered options. Use ws.capabilities when you want the answer filtered through the workspace’s configured backend instances. 
vector_backend_types = [option.type for option in hb.capabilities.backends(hb.Vector, op="near")]
workspace_ops = ws.capabilities.ops(hb.ShortText, hb.InlineColumn, backend="main")

print("inmem" in vector_backend_types)
print("match" in workspace_ops)
Capabilities answer questions like:
  • which backends can store Vector
  • which strategies work for Array
  • which operations a backend can execute natively or with fallback
  • whether a specific dtype, operation, backend, and strategy combination is registered

​
5. Know the Safety Boundary

Workspace methods are thread-safe on one HeavenBase instance. Current public operations are serialized by the workspace lock so schema registration, routing reads, CRUD, query, refresh, drop, audit, and repair do not race each other. Persistent backends can be opened by multiple workspace instances when the provider supports that pattern. SQL backends rely on the database engine. File backends expose refresh() as an explicit cache invalidation hook after manual external edits.

​
Further Exploration

Related resources: