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

> Concrete object discovery through Catalog and workspace structure discovery through MetaSchema.

<Note>
  *Catalog finds the things. MetaSchema explains the shelves.*
</Note>

<br />

## 1. Use Catalog for Concrete Objects

`Catalog` is the user-facing directory of concrete entity instances in a workspace. HeavenBase writes Catalog rows automatically after successful non-system entity writes.

```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")
    keywords = hb.field(hb.Array[hb.ShortText]).default([]).desc("Short discovery keywords")
    price = hb.field(hb.Float)


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

Query Catalog when you only know broad object attributes such as type, name, description, or tags.

```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` is the Catalog row primary key. `Catalog.target_id` is the target object's `object_id`, and `Catalog.target_entity` is the target entity type.

If a concrete entity exposes short keyword arrays, query that typed entity when the input is a long phrase:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
keyword_hits = (
    ws.query(Product)
    .where(Product.keywords.contained_in("The office setup needs a writing desk and task lamp."))
    .select("name", "match")
    .execute()
    .rows()
)

print(keyword_hits[0]["match"][0]["keyword"])
```

The returned `match` metadata explains which stored keyword appeared in the longer text. Catalog can then be used to hydrate or display the selected objects.

<br />

## 2. Hydrate the Typed Row

Catalog is for discovery, not for replacing typed entity queries. Once you choose a Catalog row, hydrate the target row through `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"])
```

Use the pair `target_entity + target_id` when object IDs may repeat across entity types.

<br />

## 3. Use MetaSchema for Workspace Structure

`MetaSchema` describes workspace structure: entities, fields, storage placements, backends, capabilities, extensions, and other engine-facing rows.

```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"])
```

Use `MetaSchema` to learn what can be queried. Use `Catalog` to find actual objects to query or hydrate.

<br />

## 4. Use Capabilities for Selectable Options

`hb.capabilities` is the public index for logical types, storage strategies, backend choices, and operation support. It is not the same thing as `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)
```

Use `ws.capabilities` when the answer should reflect only the backend instances configured in one workspace.

<br />

## 5. Audit and Repair Catalog Rows

Catalog rows are derived from entity rows. If you manually edit backend files or recover from a partial failure, check system consistency before exposing the workspace to agents.

```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` reports the repair plan without writing or deleting Catalog rows.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Workspace](/features/workspace) - Workspace system rows
  * [Entities](/features/entities) - Source schemas for Catalog rows
  * [Query](/features/query) - Query `Catalog` and `MetaSchema`
  * [HeavenBase MCP](/quickstart/heavenbase-mcp) - Let agents browse workspaces
</Tip>

<br />