Backends

A backend label is a résumé; explain() is the reference check.

1. Motivation

Applications often turn a family label into a planner branch: “vector database” must support every vector operation, or “SQL” must share one text collation. Real providers differ by operation, field strategy, version, configuration, and live resources. HeavenBase resolves each Backend through a Context-local backend_type Registry record. Static tags describe candidate roles. Exact handler records, compiler output, and live checks decide execution. The workspace keeps provider choice inspectable without pretending that one label proves native behavior.

import heavenbase as hb

ws = hb.HeavenBase("backend-demo", preset="debug")
print(ws.backends.names())

The debug preset uses SQLite for rows plus in-memory vector and search instances. It needs no external service and is the recommended first run.

2. Choose from the 0.1.2.2 Provider Matrix

Storage role	Canonical selectors	Useful aliases
Local and file	`inmem`, `json`, `pickle`, `sqlite`, `duckdb`, `tinydb`	`memory` → `inmem`; `tiny` → `tinydb`
SQL and analytics	`postgres`, `supabase`, `mysql`, `seekdb`, `oceanbase`, `dolt`, `mssql`, `oracle`, `starrocks`, `trino`, `clickhouse`	`postgresql`, `pg` → `postgres`; `sqlserver`, `sql-server` → `mssql`
Document, key-value, and text	`mongodb`, `redis`, `elasticsearch`, `opensearch`	`mongo` → `mongodb`; `elastic`, `search` → `elasticsearch`
Vector and hybrid	`pgvector`, `lance`, `milvus`, `milvus-lite`, `chroma`, `pinecone`, `qdrant`, `weaviate`, `redisearch`	`lancedb` → `lance`; `milvus_lite` → `milvus-lite`
Graph and multi-model	`neo4j`, `surreal`	`surrealdb` → `surreal`

Protocol-compatible selectors remain distinct Backend identities. For example, Supabase and pgvector use PostgreSQL protocols but own different construction and placement behavior. Milvus Lite is not an alias for a Milvus server. The table lists 32 concrete built-in choices. The Registry also exposes generic file and sql family bases for extension and advanced construction work; they are not counted as separate concrete providers. Optional providers require their Python packages, credentials, and reachable services. The sql extra installs maintained SQL drivers; full installs the built-in provider clients available for the current platform.

3. Start with a Preset

Preset	Default layout	Intended use
`debug`	SQLite rows, in-memory vectors and search	Quickstarts, tests, local experiments
`local-lts`	PostgreSQL, LanceDB, Elasticsearch	Durable self-hosted development
`web-lts`	Supabase rows, pgvector, hosted search	Managed or shared environments

ws = hb.HeavenBase("shop", preset="local-lts")
print(ws.backends.names())

A preset is a complete construction form. Reopening a durable workspace with a different explicit preset is a conflict, even when two presets happen to resolve similar providers.

4. Use an Explicit Backend Map

Workspace-local names are map keys; Registry selectors live in each type:

ws = hb.HeavenBase(
    "search-app",
    backends={
        "main": {
            "type": "sqlite",
            "database": "search.db",
        },
        "vec": {
            "type": "qdrant",
            "url": "http://localhost:6333",
        },
        "search": {
            "type": "opensearch",
            "hosts": ["http://localhost:9201"],
        },
    },
)

Fields route to main, vec, or search, not directly to provider types. Keep credentials in environment interpolation or explicit process configuration; public diagnostics omit authentication values. Local file providers use the shared file:// locator grammar where a path locator is required. Remote providers scope physical resource names to the workspace and Backend instance so fresh-process cleanup stays bounded.

5. Place Fields by Strategy

class Article(hb.Entity):
    title = hb.field(hb.ShortText).store(to="main")
    keywords = (
        hb.field(hb.Array[hb.ShortText])
        .default([])
        .store(to="main", strategy=hb.SparseGramIndex())
    )
    embedding = hb.field(hb.Vector[3]).store(
        to="vec",
        strategy=hb.VectorIndex,
    )


ws.register(Article)

Storage strategies express field intent: InlineColumn, SideTable, JsonField, SparseGramIndex, VectorIndex, InvertedIndex, GraphEdge, and ExternalRef. Registration resolves intent against the named Backend instances and installed placement profiles. SQL Backends can host SparseGramIndex for reverse containment over short keyword arrays. The explicit gram Backend remains a narrow compatibility route; new applications normally keep sparse-GRAM postings beside SQL row storage.

6. Inspect Tags, Capabilities, and a Concrete Plan

modules = ws.context.modules()
claim = modules.tag("backend_type", "qdrant", "vector")

choices = hb.capabilities.backends(hb.Vector, op="near")
workspace_ops = ws.capabilities.ops(
    hb.Vector,
    hb.VectorIndex,
    backend="vec",
)

print(claim.value)
print([choice.type for choice in choices])
print(workspace_ops)

Static tags come from the installed subject record’s meta.tags. A missing optional tag definition leaves the raw claim visible with unresolved diagnostics; it does not erase the claim. Global capabilities describe registered candidates. Workspace capabilities filter through configured Backend instances. Neither replaces a concrete query plan:

plan = ws.query(Article).near(Article.embedding, [1.0, 0.0, 0.0]).explain()
print(plan["steps"])

Use handler_mode, fallback reasons, unsafe reasons, and portable-proof details in the plan before promising native or portable semantics.

7. Know the Provider-Specific Boundaries

Independent Backends do not form a distributed transaction.
Local JSON and pickle are development-oriented; treat pickle as trusted-local.
Milvus vector fields must be required because its rows cannot represent a missing FLOAT_VECTOR.
Provider collations and text operators may differ; HeavenBase may choose an exact portable scan unless unsafe query policy explicitly accepts provider semantics.
Pinecone cannot prove exhaustive enumeration for every unbounded fold.
Local-file and embedded providers still need explicit ownership and cleanup; detached=True does not make their data temporary.
Reachability, credentials, server versions, and quotas are live facts, not module tags.

Use the provider’s own operational guidance for deployment, backup, authentication, and capacity planning.

Summary

Backend type names identify candidates, not proven execution.
Presets simplify construction; explicit maps and placements express deliberate choices.
Tags describe, capabilities filter, and explain() reports the concrete route.

Further Exploration

Related resources:

Workspace - Choose preset or explicit construction
Routing - Place fields on named Backend instances
Query - Inspect concrete execution with explain()
Database Integrations - Configure SQL providers
Vector Database Integrations - Configure vector providers
Extensions - Publish an external Backend module

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Choose from the 0.1.2.2 Provider Matrix

3. Start with a Preset

4. Use an Explicit Backend Map

5. Place Fields by Strategy

6. Inspect Tags, Capabilities, and a Concrete Plan

7. Know the Provider-Specific Boundaries

Summary

Further Exploration

​1. Motivation

​2. Choose from the 0.1.2.2 Provider Matrix

​3. Start with a Preset

​4. Use an Explicit Backend Map

​5. Place Fields by Strategy

​6. Inspect Tags, Capabilities, and a Concrete Plan

​7. Know the Provider-Specific Boundaries

​Summary

​Further Exploration

1. Motivation

2. Choose from the 0.1.2.2 Provider Matrix

3. Start with a Preset

4. Use an Explicit Backend Map

5. Place Fields by Strategy

6. Inspect Tags, Capabilities, and a Concrete Plan

7. Know the Provider-Specific Boundaries

Summary

Further Exploration