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

# Namespaces

> The unit of isolation, storage, caching, billing and scale.

A namespace holds documents and the judgments defined on them. It is the unit of isolation, storage, caching, billing and scale. The usual mapping is one namespace per tenant per environment.

* **Created implicitly** by the first write or judgment. There is no create call.
* **Hierarchical names.** `acme/prod/tenant_123` is a namespace. Listing, deletion and API key scoping work on the prefix (`acme/prod/`). A judgment created on `acme/prod/*` is a [template](/guides/templates) that every namespace under the prefix inherits. In URL paths, send each `/` as `%2F`: `/namespaces/acme%2Fprod%2Ftenant_123/query`. The SDKs do this for you.
* **Idle costs nothing** beyond storage. A namespace is a prefix on object storage, and nodes cache whole namespaces and evict whole namespaces.
* **Unlimited** per organization. Names are up to 256 bytes of `A-Z a-z 0-9 . _ : / -`.

## Settings

`PATCH /namespaces/{ns}` changes these settings. Each change is recorded in your organization's audit log.

```json theme={null}
{"budget": {"compute_usd_per_month": 500, "on_exceeded": "pause"}, "pinned": false, "default_engine": {"name": "jev", "version": "current"}}
```

* **`budget`** caps judgment compute per calendar month. When a namespace reaches it, `on_exceeded: "pause"` stops evaluation and lets answers go `stale` while writes continue. `"reject"` makes writes fail with `budget_exceeded`. The namespace then reports `budget_paused: true`. Raising the budget clears it.
* **`pinned: true`** keeps the namespace resident in cache on two nodes, so it never has a cold query. It is billed as warm storage.
* **`default_engine`** fills in `engine` when a judgment is created without one. It never changes existing judgments.
* **`fanout`** decides how [fan-out](/guides/freshness-policies#fan-out-when-a-referenced-document-changes) runs here, for judgments that read the document each judged document points at: `share`, the most of the namespace's in-flight engine requests fan-out may use (0.5 by default, always at least one request), and `job_above` (10,000) and `confirm_jobs` (`true`), which its judgments follow unless they set their own. Each key is optional in a `PATCH`, and `GET` returns the values in effect.

`GET /namespaces/{ns}` returns the settings, `budget_paused`, and stats: documents, bytes, what judging has cost this month and the projected monthly cost of periodic judgments, both at the [judgment unit prices](/pricing#judgments) for your organization's monthly volume.

## Deleting

`DELETE /namespaces/{ns}` deletes the namespace at once: when it returns, nothing of it is readable, and a write to the same name creates a new, empty namespace. It also starts a `namespace_delete` job, which removes every document, answer, evaluation and usage file of the deleted namespace from storage within 24 hours. The namespace's other open jobs, such as backfills and shadow reports, are cancelled, with `error` "the namespace was deleted"; nothing they would have run carries over to the new namespace. A write that was still in flight when you deleted either happened before the deletion, and is gone with it, or lands in the new namespace, and its response says so with the revision it has there.