Entities

An Entity gives data a passport before a Backend assigns it a hotel room.

1. Motivation

Applications need one durable description of what a row means. HeavenBase Entities keep that logical contract independent from physical storage, so the same schema can route across different Backends.

2. Define a Logical Shape

Extend hb.Entity and declare typed fields. Use hb.field(...) when a field needs metadata, defaults, placement, or compute Hooks.

import heavenbase as hb


class Document(hb.Entity):
    title = hb.field(hb.ShortText).desc("Display title")
    body = hb.field(hb.LongText)
    tags = hb.field(hb.Array[hb.ShortText]).default([])
    embedding = hb.field(hb.Vector[2])


Document.schema().validate()
print(Document.schema().entity_id)

HeavenBase derives the identifier document and injects the required object_id field when it is absent. schema() returns a compiled EntitySchema; to_dict() and to_str() provide JSON-compatible and agent-readable views.

3. Choose Logical Types

Logical types describe meaning. Backends decide physical representation.

Type	Typical use
`Identifier`	Stable ids and slugs
`ShortText`, `MediumText`, `LongText`	Labels, descriptions, and documents
`Integer`, `Float`, `Boolean`	Scalar values
`Categorical([...])`	Values restricted to known choices
`Timestamp(unit="ms")`, `Date()`	Instants and calendar dates
`Array[...]`	Lists with an optional item type
`Vector[dim]`	Embeddings and numeric vectors
`Json`	JSON-compatible objects
`HyperG`	Repeatable relation-like records
`Artifact`	Binary payloads

Use Timestamp for instants and Date for calendar dates. HeavenBase does not expose separate Datetime or Interval logical types.

4. Preserve Identity

Every Entity row has one user-facing object_id. If it is omitted, HeavenBase derives a deterministic id from the row’s name.

ws = hb.HeavenBase("entity-demo", preset="debug")
ws.register(Document)

object_id = ws.upsert(
    Document,
    {
        "name": "Agent guide",
        "title": "Agent guide",
        "body": "Use one logical schema.",
        "tags": ["docs"],
        "embedding": [1.0, 0.0],
    },
)

print(ws.get(object_id, entity=Document)["title"])

Declare object_id explicitly when a different natural key should control identity. Compute Hooks can derive that key from other fields.

5. Add Compute Hooks

Write-time compute Hooks derive stored values. Query-compute Hooks normalize a query value before routing, such as turning text into a vector.

def embed(text: str) -> list[float]:
    return [1.0, 0.0] if "agent" in text.lower() else [0.0, 1.0]


class Issue(hb.Entity):
    summary = hb.field(hb.LongText)
    embedding = (
        hb.field(hb.Vector[2])
        .compute(embed, inputs=["summary"])
        .query_compute(embed)
    )


ws.register(Issue)
ws.upsert(Issue, {"object_id": "i1", "summary": "Agent memory"})
rows = ws.query(Issue).near(Issue.embedding, "agent search", top_k=1).execute().rows()

Compute callables are part of application behavior. Keep them deterministic, small, and importable when the schema must be reconstructed.

6. Build from JSON

Agents and external clients can create the same logical schema from a JSON-compatible mapping.

Product = hb.Entity.from_schema(
    {
        "entity_id": "product",
        "fields": {
            "name": "ShortText",
            "price": "Float",
            "status": {
                "type": {
                    "type": "categorical",
                    "values": ["draft", "active"],
                }
            },
        },
    }
)

ws.register(Product)

The generated class behaves like an ordinary hb.Entity subclass. The same definition can also travel inside a workspace manifest.

Summary

Entities define logical meaning and stable identity.
Fields carry types, metadata, defaults, placement, and compute Hooks.
Physical storage remains a routing concern.
Python and JSON definitions compile to the same schema contract.

Further Exploration

Related resources:

Workspace — Register schemas in an application boundary
Routing — Place fields on Backends
Query — Read and aggregate Entity rows
Catalog — Discover concrete objects after writes

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Define a Logical Shape

3. Choose Logical Types

4. Preserve Identity

5. Add Compute Hooks

6. Build from JSON

Summary

Further Exploration

​1. Motivation

​2. Define a Logical Shape

​3. Choose Logical Types

​4. Preserve Identity

​5. Add Compute Hooks

​6. Build from JSON

​Summary

​Further Exploration

1. Motivation

2. Define a Logical Shape

3. Choose Logical Types

4. Preserve Identity

5. Add Compute Hooks

6. Build from JSON

Summary

Further Exploration