跳转到主要内容
一个工作区，多种存储引擎，一个统一提问入口。

​
1. 工作区拥有什么

HeavenBase 工作区是数据应用的应用边界。它拥有：
  • 你注册的实体 schema
  • 你连接的后端实例
  • 字段级存储放置
  • 必需 system 扩展中 Catalog、MetaSchema 等实体的系统行
  • 对工作区内数据的 CRUD、查询、审计、修复，以及面向 MCP 的访问
通常为一个应用、Agent 记忆、demo 或租户边界创建一个工作区。在该边界内，即使字段分布在不同物理后端，HeavenBase 仍保持统一的逻辑 API。
把工作区理解为「数据的含义」与「数据的存放位置」交汇之处。

​
2. 从 preset 开始

首次本地执行时，使用 debug preset。它无需 Docker 服务，提供 SQLite 行存储以及内存向量与搜索后端。 
import heavenbase as hb

ws = hb.HeavenBase("core-workspace", preset="debug")
print(ws.id)
从 CLI 查看解析后的 preset： 
hb ws presets show debug
PresetBackendsWhen to use
debugSQLite main, in-memory vec, in-memory search首次 demo、测试与示例。
local-ltsPostgres main, LanceDB vec, Elasticsearch search使用仓库服务栈的持久化本地开发。
web-ltsManaged Postgres, pgvector, hosted search共享或托管部署。
在需要持久化或外部服务之前，先用 preset="debug"。相同的实体与查询代码之后可迁移到更大的 preset。

​
3. 放置关系明确时使用显式后端

Preset 是最短路径，但当你需要自定义测试布局或记录部署形态时，显式后端映射更有用。 
ws = hb.HeavenBase(
    "core-explicit-workspace",
    backends={
        "main": {"type": "inmem"},
        "vec": {"type": "inmem"},
    },
)

print(ws.backends.names())
后端键是工作区本地名称。后端 type 选择 provider 族，例如 sqlite、postgres、inmem、lance、elasticsearch、json 或 pickle。

​
4. 注册、写入与读取

注册是显式的：定义实体，在工作区注册，再通过工作区 API 写入行。 
class Note(hb.Entity):
    title = hb.field(hb.ShortText)
    body = hb.field(hb.LongText)


ws.register(Note)

note_id = ws.upsert(
    Note,
    {
        "name": "Routing note",
        "title": "Routing note",
        "body": "One logical row can move across backends.",
    },
)

row = ws.get(note_id, entity=Note)
print(row["title"])
每行只有一个 object_id。当你省略它且行有 name 时，HeavenBase 会根据实体 schema 与该 name 派生稳定 ID。

​
5. 检查与修复

工作区始终注册 Catalog 与 MetaSchema 系统实体。当 Agent 或开发者需要了解工作区内容时，查询它们。 
entity_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "entity")
    .select("subject_id", "name")
    .execute()
    .rows()
)

print([row["subject_id"] for row in entity_rows])
print(ws.audit()["catalog"]["ok"])
用 ws.audit() 检查 Catalog 一致性。仅当你有意让 HeavenBase 根据权威实体行重建缺失或过时的 Catalog 行时，才使用 ws.repair()。

​
Further Exploration

Related resources: