Catalog - HeavenBase

Catalog finds the things. MetaSchema explains the shelves.

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.

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.

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:

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.

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

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.

3. Use MetaSchema for Workspace Structure

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

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.

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.

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.

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.

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.

Further Exploration

Related resources:

Workspace - Workspace system rows
Entities - Source schemas for Catalog rows
Query - Query Catalog and MetaSchema
HeavenBase MCP - Let agents browse workspaces

​1. Use Catalog for Concrete Objects

​2. Hydrate the Typed Row

​3. Use MetaSchema for Workspace Structure

​4. Use Capabilities for Selectable Options

​5. Audit and Repair Catalog Rows

​Further Exploration

1. Use Catalog for Concrete Objects

2. Hydrate the Typed Row

3. Use MetaSchema for Workspace Structure

4. Use Capabilities for Selectable Options

5. Audit and Repair Catalog Rows

Further Exploration