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

# Workspace

> The HeavenBase workspace boundary for schemas, backends, routing, system rows, and data.

<Note>
  *One workspace, many storage engines, one place to ask questions.*
</Note>

<br />

## 1. What a Workspace Owns

A `HeavenBase` workspace is the application boundary for a data application. It owns:

* entity schemas you register
* backend instances you connect
* field-level storage placement
* system rows for `Catalog`, `MetaSchema`, and other entities from the required `system` extension
* CRUD, query, audit, repair, and MCP-facing access to the data inside the workspace

You usually create one workspace for one application, agent memory, demo, or tenant boundary. Inside that boundary, HeavenBase keeps one logical API even when fields live across different physical backends.

<Info>
  Think of the workspace as the place where "what the data means" and "where the data lives" meet.
</Info>

<br />

## 2. Start with a Preset

For the first local run, use the `debug` preset. It needs no Docker services and gives you SQLite row storage plus in-memory vector and search backends.

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

ws = hb.HeavenBase("core-workspace", preset="debug")
print(ws.id)
```

Inspect the resolved preset from the CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb ws presets show debug
```

| Preset      | Backends                                               | When to use                                            |
| ----------- | ------------------------------------------------------ | ------------------------------------------------------ |
| `debug`     | SQLite `main`, in-memory `vec`, in-memory `search`     | First-run demos, tests, and examples.                  |
| `local-lts` | Postgres `main`, LanceDB `vec`, Elasticsearch `search` | Durable local development with the repo service stack. |
| `web-lts`   | Managed Postgres, pgvector, hosted search              | Shared or hosted deployments.                          |

<Tip>
  Start with `preset="debug"` until you need persistence or external services. The same entity and query code can move to a larger preset later.
</Tip>

<br />

## 3. Use Explicit Backends When Placement Matters

Presets are the shortest path, but explicit backend maps are useful when you want a custom test layout or you are documenting a deployment shape.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
ws = hb.HeavenBase(
    "core-explicit-workspace",
    backends={
        "main": {"type": "inmem"},
        "vec": {"type": "inmem"},
    },
)

print(ws.backends.names())
```

Backend keys are workspace-local names. Backend `type` values choose the provider family, such as `sqlite`, `postgres`, `inmem`, `lance`, `elasticsearch`, `json`, or `pickle`.

<br />

## 4. Register, Write, and Read

Registration is explicit. Define an entity, register it in the workspace, then write rows through the workspace API.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class Note(hb.Entity):
    title = hb.field(hb.ShortText)
    body = hb.field(hb.LongText)


ws.register(Note)

note_id = ws.upsert(
    Note,
    {
        "name": "Routing note",
        "title": "Routing note",
        "body": "One logical row can move across backends.",
    },
)

row = ws.get(note_id, entity=Note)
print(row["title"])
```

Every row has one `object_id`. When you omit it and the row has a `name`, HeavenBase derives a stable ID from the entity schema and that name.

<br />

## 5. Inspect and Repair

Workspaces always register `Catalog` and `MetaSchema` system entities. Query them when an agent or developer needs to understand what is inside the workspace.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
entity_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "entity")
    .select("subject_id", "name")
    .execute()
    .rows()
)

print([row["subject_id"] for row in entity_rows])
print(ws.audit()["catalog"]["ok"])
```

Use `ws.audit()` to check Catalog consistency. Use `ws.repair()` only when you intentionally want HeavenBase to rebuild missing or stale Catalog rows from authoritative entity rows.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Workspace Manifests](/features/workspace-manifest) - Export and replay workspace construction config
  * [Entities](/features/entities) - Define logical schemas
  * [Routing](/features/routing) - Place fields on backends
  * [Backends](/features/backends) - Choose storage providers
  * [Catalog](/features/catalog) - Browse objects and workspace structure
  * [Extensions](/features/extensions) - System extension and custom entity extensions
</Tip>

<br />