Skip to main content
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 and API key scoping work on the prefix (acme/prod/). Deleting works on one namespace at a time. A key scoped to a prefix or a namespace can be created before anything under it exists, and its writes create the namespaces. A judgment created on acme/prod/* is a template 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. The first query after a namespace has been idle is slower (cold); pin it to avoid that.
  • Unlimited per organization. Names are up to 256 bytes of A-Z a-z 0-9 . _ : / -, never exactly . or .., which a URL path can’t carry.

​
Tenants and environments

  • A tenant is whose data it is: one of your customers, if you run a platform. If you don’t, you have a single tenant.
  • An environment is which copy of your software wrote it: production or staging.
The default is one namespace per tenant per environment, environment first: acme/prod/tenant_123 and acme/staging/tenant_123. Each environment is then a prefix, so one key scope, one template and one non-production marking cover it whole. Split a tenant into more namespaces only for data no judgment reads together. Related documents must be in the judged document’s namespace, so a ticket and the account it points at belong in one. A tenant’s support tickets and its invoices, if no judgment ever reads both, can be acme/prod/tenant_123/support and acme/prod/tenant_123/billing. Each namespace counts on its own toward the tenant fee.

​
Settings

PATCH /namespaces/{ns} changes these settings. Each change is recorded in your organization’s audit log.
  • budget caps judgment compute per billing period, which starts on the day of the month your organization’s card was added, not on the 1st. The budget starts again with each period. Each request to the engine is priced before it is sent, and one that would take the namespace past its budget is not sent: its documents wait, unjudged and unbilled. So judging stops at the budget, not after it; see system behavior for the exact bound. on_exceeded: "pause" then lets answers go stale, or unavailable for documents never judged, while writes continue. "reject" makes writes fail with budget_exceeded. The namespace reports budget_paused: true, and your organization’s owners and admins get an email. Raising the budget clears it, and the documents that waited are judged.
  • pinned: true keeps the namespace resident in cache, so it never has a cold query. It is billed per GiB-month as a pinned namespace.
  • default_engine fills in engine when a judgment is created without one. It never changes existing judgments.
  • fanout decides how fan-out runs here, for judgments that read the document each judged document points at, or the documents that share a key with it: share, the most of the namespace’s in-flight engine requests fan-out may use (0.5 by default, always at least one request). GET returns the value in effect. Each judgment’s rolling limit is its own, in freshness.fanout.
GET /namespaces/{ns} returns the settings, budget_paused, and stats: documents, bytes, what judging has cost in the current billing period (spend_month_usd) and the projected monthly cost of periodic judgments, both at the judgment prices for your organization’s volume in the period. Amounts are US dollars counted to the micro-dollar ($0.000001), as your bill counts them, so three standard judgments at $0.00025 read 0.00075; a budget is kept to the micro-dollar too.

​
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.