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

# 目录 (Catalog)

> 通过 Catalog 发现具体对象，通过 MetaSchema 发现工作区结构。

<Note>
  *Catalog 找东西；MetaSchema 解释架子怎么摆。*
</Note>

<br />

## 1. 用 Catalog 找具体对象

`Catalog` 是工作区内具体实体实例面向用户的目录。非系统实体写入成功后，HeavenBase 自动写入 Catalog 行。

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


class Product(hb.Entity):
    identifier = "catalog-product"

    name = hb.field(hb.ShortText).desc("Display name")
    desc = hb.field(hb.MediumText).desc("Catalog description source")
    tags = hb.field(hb.Json).default([]).desc("Catalog tags source")
    price = hb.field(hb.Float)


ws = hb.HeavenBase("core-catalog", backends={"main": {"type": "inmem"}})
ws.register(Product)
ws.upsert_many(
    Product,
    [
        {"object_id": "p1", "name": "Desk", "desc": "Oak writing desk", "tags": ["office", "furniture"], "price": 120.0},
        {"object_id": "p2", "name": "Lamp", "desc": "Adjustable task lamp", "tags": ["office", "lighting"], "price": 35.0},
    ],
)
```

当你只知道类型、名称、描述或 tags 等宽泛对象属性时，查询 Catalog。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
catalog_rows = (
    ws.query(hb.Catalog)
    .where(hb.Catalog.target_entity == "catalog-product")
    .select("target_id", "target_entity", "name", "desc", "tags")
    .execute()
    .rows()
)

print(catalog_rows[0]["name"])
```

`Catalog.object_id` 是 Catalog 行主键。`Catalog.target_id` 是目标对象的 `object_id`，`Catalog.target_entity` 是目标实体类型。

<br />

## 2. 水合类型化行

Catalog 用于发现，不能替代类型化实体查询。选定 Catalog 行后，通过 `workspace.get(...)` 水合目标行。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
catalog_row = catalog_rows[0]
product = ws.get(catalog_row["target_id"], entity=catalog_row["target_entity"])

print(product["object_id"])
print(product["price"])
```

当 object ID 可能在实体类型间重复时，使用 `target_entity + target_id` 组合。

<br />

## 3. 用 MetaSchema 看工作区结构

`MetaSchema` 描述工作区结构：实体、字段、存储放置、后端、capabilities、扩展与其他面向引擎的行。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
fields = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "field")
    .where(hb.MetaSchema.subject_id == "catalog-product")
    .select("field", "dtype", "desc")
    .execute()
    .rows()
)

storage = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "storage")
    .where(hb.MetaSchema.subject_id == "catalog-product")
    .select("field", "backend", "strategy")
    .execute()
    .rows()
)

print(fields[0]["field"])
print(storage[0]["backend"])
```

用 `MetaSchema` 了解能查什么；用 `Catalog` 找到要查询或水合的实际对象。

<br />

## 4. 用 Capabilities 看可选项

`hb.capabilities` 是逻辑类型、存储策略、后端选择与操作支持的公开索引。它与 `Catalog` 不是一回事。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
logical_type_ids = [option.identifier for option in hb.capabilities.logical_types()]
vector_backends = [option.type for option in hb.capabilities.backends(hb.Vector, op="near")]

print("short-text" in logical_type_ids)
print("inmem" in vector_backends)
```

当答案应只反映某一工作区已配置的后端实例时，用 `ws.capabilities`。

<br />

## 5. 审计与修复 Catalog 行

Catalog 行由实体行派生。若手动编辑后端文件或从部分失败恢复，在向 Agent 暴露工作区前先检查系统一致性。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
audit = ws.audit()["catalog"]
print(audit["ok"])

repair_plan = ws.repair(dry_run=True)["catalog"]
print(repair_plan["dry_run"])
```

`dry_run=True` 只报告修复计划，不写入或删除 Catalog 行。

<br />

## 进一步探索

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

  * [工作区](/zh/features/workspace) - 工作区系统行
  * [实体](/zh/features/entities) - Catalog 行的来源 schema
  * [查询](/zh/features/query) - 查询 `Catalog` 与 `MetaSchema`
  * [HeavenBase MCP](/zh/quickstart/heavenbase-mcp) - 让 Agent 浏览工作区
</Tip>

<br />