Catalog

Catalog finds the books; MetaSchema explains why one shelf is humming.

1. Motivation

Agents need two different kinds of discovery. They need to find concrete objects without knowing every Entity class, and they need to inspect the structure that makes those objects queryable. HeavenBase keeps those questions separate:

Catalog indexes concrete workspace objects.
MetaSchema projects safe workspace and module structure.
hb.capabilities reports selectable engine options.

2. Discover Concrete Objects

HeavenBase maintains Catalog rows after successful writes to ordinary user Entities.

import heavenbase as hb


class Product(hb.Entity):
    name = hb.field(hb.ShortText)
    desc = hb.field(hb.MediumText)
    tags = hb.field(hb.Json).default([])
    price = hb.field(hb.Float)


ws = hb.HeavenBase("catalog-demo", preset="debug")
ws.register(Product)
ws.upsert(
    Product,
    {
        "object_id": "desk",
        "name": "Oak desk",
        "desc": "A writing desk for very serious snacks.",
        "tags": ["office", "furniture"],
        "price": 120.0,
    },
)

Query Catalog when broad attributes such as type, name, description, or tags are enough:

rows = (
    ws.query(hb.Catalog)
    .available()
    .where(hb.Catalog.target_entity == "product")
    .select("target_id", "target_entity", "name", "desc", "tags")
    .execute()
    .rows()
)

Catalog.object_id identifies the Catalog row. The pair target_entity + target_id identifies the indexed object.

3. Hydrate the Typed Row

Catalog is a discovery index, not a replacement for typed Entity access. Hydrate a selected result through the workspace:

hit = rows[0]
product = ws.get(hit["target_id"], entity=hit["target_entity"])
print(product["price"])

Always keep the Entity identifier when object ids may repeat across Entity types.

4. Respect Availability

Use .available() for ordinary discovery so inactive, hidden, expired, and stale rows do not leak into agent results.

rows = ws.query(hb.Catalog).available(stale=True).execute().rows()

stale=True includes stale rows, while invisible=True includes hidden rows. Hard-expired and inactive rows remain excluded. The JSON form is {"available": {"stale": true}}.

5. Inspect Workspace Structure

MetaSchema describes Entities, fields, storage placements, Backends, extensions, and safe Registry projections.

fields = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "field")
    .where(hb.MetaSchema.subject_id == "product")
    .select("field", "dtype", "desc")
    .execute()
    .rows()
)

MetaSchema is descriptive, not an installation control plane. It redacts authored semantic tags, local paths, and executable implementation details. Use MetaSchema to learn what can be queried. Use Catalog to find actual objects.

6. Inspect Selectable Capabilities

hb.capabilities answers which logical types, storage strategies, Backend types, and operations are available.

logical_types = [item.identifier for item in hb.capabilities.logical_types()]
vector_backends = [item.type for item in hb.capabilities.backends(hb.Vector, op="near")]

Use ws.capabilities when the answer must reflect only live Backend instances in one workspace. Use ws.context.modules().tag(...) for direct module tag inspection.

7. Audit Derived Rows

Catalog rows are derived from Entity rows. After manual Backend recovery or a partial failure, audit before exposing the workspace:

audit = ws.audit()["catalog"]
plan = ws.repair(dry_run=True)["catalog"]

print(audit["ok"], plan["dry_run"])

dry_run=True reports the repair plan without writing or deleting Catalog rows.

Summary

Catalog discovers concrete objects.
MetaSchema describes safe workspace structure.
Capabilities reports selectable engine options.
Typed workspace access remains the authority for the underlying row.

Further Exploration

Related resources:

Entities — Define the rows Catalog indexes
Query — Query Catalog and MetaSchema
Routing — Inspect where fields execute
HeavenBase MCP — Let agents browse workspaces

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Discover Concrete Objects

3. Hydrate the Typed Row

4. Respect Availability

5. Inspect Workspace Structure

6. Inspect Selectable Capabilities

7. Audit Derived Rows

Summary

Further Exploration

​1. Motivation

​2. Discover Concrete Objects

​3. Hydrate the Typed Row

​4. Respect Availability

​5. Inspect Workspace Structure

​6. Inspect Selectable Capabilities

​7. Audit Derived Rows

​Summary

​Further Exploration

1. Motivation

2. Discover Concrete Objects

3. Hydrate the Typed Row

4. Respect Availability

5. Inspect Workspace Structure

6. Inspect Selectable Capabilities

7. Audit Derived Rows

Summary

Further Exploration