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

# 后端 (Backend)

> 可插拔存储 provider，在统一工作区 API 之后承载 HeavenBase 字段。

<Note>
  *按工作负载选存储，用一套 API 访问数据。*
</Note>

<br />

## 1. 后端是什么

后端是注册在工作区内的物理存储 provider。HeavenBase 按名称将字段路由到后端实例，再用处理器为每个 provider 编译受支持的查询操作。

对普通应用代码，通常选择 preset，让工作区构建后端。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

ws = hb.HeavenBase("core-backends", preset="debug")
print(ws.backends.names())
```

`debug` preset 创建三个后端实例：`main`、`vec` 与 `search`。

<br />

## 2. 内置后端族

HeavenBase 为本地、SQL、向量、文件与搜索场景提供后端构建器。

| Family        | Backend keys                                                                                              | Use it for        |
| ------------- | --------------------------------------------------------------------------------------------------------- | ----------------- |
| Local memory  | `inmem`                                                                                                   | 测试、demo、临时行。      |
| Local files   | `json`, `pickle`, `file`                                                                                  | 简单持久化本地存储。        |
| SQL rows      | `sqlite`, `duckdb`, `postgres`, `pgvector`, `mysql`, `oceanbase`, `mssql`, `oracle`, `trino`, `starrocks` | 结构化行存储与 SQL 原生过滤。 |
| Vector stores | `lance`, `chroma`, `milvus`, `pinecone`, `pgvector`                                                       | 原生向量搜索。           |
| Search        | `elasticsearch`                                                                                           | 文本搜索与搜索引擎支持的过滤。   |

可选 provider 需要对应 Python 驱动；服务器后端还需可达服务。若 provider 不可用，示例与测试请用 `debug` 或显式 `inmem`/`sqlite` 布局。

<br />

## 3. 配置自定义映射

显式后端字典以工作区本地名称为键，值内写 provider 类型。

```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())
```

字段路由到后端名称，而非 provider 类型：

```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. 发现能力

用 `hb.capabilities` 查看全局注册选项。需要答案限定在工作区已配置后端实例时，用 `ws.capabilities`。

```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 回答诸如：

* 哪些后端可存 `Vector`
* 哪些策略适用于 `Array`
* 某后端可原生执行哪些操作或需回退
* 特定 `dtype`、操作、后端与策略组合是否已注册

<br />

## 5. 了解安全边界

工作区方法在单个 `HeavenBase` 实例上线程安全。当前公开操作由工作区锁串行化，schema 注册、路由读取、CRUD、查询、refresh、drop、audit 与 repair 彼此不会竞态。

持久化后端在 provider 支持时，可被多个工作区实例打开。SQL 后端依赖数据库引擎。文件后端在外部手动编辑后，通过 `refresh()` 显式使缓存失效。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [工作区](/zh/features/workspace) - 构建后端映射
  * [路由](/zh/features/routing) - 将字段放到后端实例
  * [查询](/zh/features/query) - 通过 `explain()` 查看后端选择
  * [数据库集成](/zh/integrations/databases) - SQL provider 配置
  * [向量数据库集成](/zh/integrations/vector-databases) - 向量 provider 配置
</Tip>

<br />