> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Backends

> Pluggable storage providers that hold HeavenBase fields behind one workspace API.

<Note>
  *Pick storage for the workload, keep one API for the data.*
</Note>

<br />

## 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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

<br />

## 2. Built-In Backend Families

HeavenBase ships backend builders for local, SQL, vector, file, and search use cases.

| Family        | Backend keys                                                                                              | Use it for                                     |
| ------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Local memory  | `inmem`                                                                                                   | Tests, demos, temporary rows.                  |
| Local files   | `json`, `pickle`, `file`                                                                                  | Simple persistent local stores.                |
| SQL rows      | `sqlite`, `duckdb`, `postgres`, `pgvector`, `mysql`, `oceanbase`, `mssql`, `oracle`, `trino`, `starrocks` | Structured row storage and SQL-native filters. |
| Vector stores | `lance`, `chroma`, `milvus`, `pinecone`, `pgvector`                                                       | Native vector search.                          |
| Search        | `elasticsearch`                                                                                           | Text 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.

<br />

## 3. Configure a Custom Map

Explicit backend dictionaries use the workspace-local name as the key and the provider type inside the value.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"])
```

<br />

## 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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<br />

## 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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Workspace](/features/workspace) - Build backend maps
  * [Routing](/features/routing) - Place fields on backend instances
  * [Query](/features/query) - See backend choices through `explain()`
  * [Database integrations](/integrations/databases) - SQL provider setup
  * [Vector database integrations](/integrations/vector-databases) - Vector provider setup
</Tip>

<br />