Docs menu · Guides

A product space is a named partition of data inside a branch. Spaces and branches are Strata’s two organizing dimensions, not data types of their own: your data always lives in one of the five capabilities — KV, JSON, events, vectors, and graphs — while branches isolate history across forks and spaces scope which slice of that data you see within a branch. Every branch has a default space, and you can add more to keep unrelated data apart — one space per tenant, per agent session, or per dataset. This guide covers the four space verbs: list, create, exists, and delete.

Examples use a durable database at ./mydb. Pass --space <name> on any command to target a space; omit it to use default.

The default space

A fresh database reports exactly one space:

strata ./mydb space list
default

With --json, the list arrives as an envelope with a continuation cursor:

strata --json ./mydb space list
{"data":{"cursor":null,"has_more":false,"items":["default"]},"type":"space_list"}

Create a space

space create <name> registers a new space:

strata ./mydb space create analytics
created analytics applied=true

Check existence

space exists <name> prints a bare boolean — handy in scripts:

strata ./mydb space exists analytics   # true
strata ./mydb space exists ghost       # false

How spaces scope data

Each space holds its own independent instance of every primitive. The same key in two spaces refers to two different values. Write report in analytics, and the default space does not see it:

strata ./mydb --space analytics kv put report q3
strata ./mydb --space analytics kv get report   # q3
strata ./mydb kv get report                      # (nil)

Counts confirm the isolation — kv count returns 1 in analytics and 0 in default. This applies to every primitive: KV, JSON, vectors, events, and graphs are all space-scoped.

Delete a space

space delete <name> drops a space. By default it refuses to delete a space that still holds visible data:

strata ./mydb space delete analytics
failed_precondition.engine.space_not_empty: product space `analytics` contains visible data; retry with force=true to delete it (err_local_33f20156_000001)
  hint: Reload the current state and retry the operation against the latest version.
  ref: https://stratadb.org/e/failed_precondition.engine.space_not_empty

Pass --force to delete the space and its visible data together:

strata ./mydb space delete analytics --force
deleted analytics applied=true

Deleting an empty space needs no flag. Deleting a space that does not exist is a no-op — it reports applied=false and exits zero rather than failing:

strata ./mydb space delete ghost
not_found ghost applied=false

The default space cannot be deleted:

strata ./mydb space delete default
invalid_argument.engine.space_delete_default: default product space cannot be deleted (err_local_35ac8288_000001)
  hint: Correct the request input and retry the operation.
  ref: https://stratadb.org/e/invalid_argument.engine.space_delete_default

Spaces or branches?

Reach for a space when you want to keep related data organized inside one line of history — tenants, sessions, or datasets that live and version together. Reach for a branch when you want an isolated copy of history you can fork, time-travel, and discard. The two compose: a branch contains spaces, and forking a branch carries its spaces along.

Next

agents: this page as markdown → /docs/guides/spaces.md