Namespaces

Creating a namespace

create namespace registers the container; from then on, every reference to an object inside it uses the :: separator. Run the snippets on this page in order:

create namespace dm_ns;
create table dm_ns::users { id: int4, name: utf8 };
insert dm_ns::users [{ id: 1, name: "Ada" }];
from dm_ns::users

Names are scoped, not global

Two namespaces can hold objects with the same name without conflict. This is the natural way to separate environments, tenants, or subsystems inside one database: prod::orders and staging::orders are entirely distinct tables.

create namespace dm_ns_prod;
create namespace dm_ns_staging;
create table dm_ns_prod::orders { id: int4 };
create table dm_ns_staging::orders { id: int4 };
insert dm_ns_prod::orders [{ id: 1001 }];
insert dm_ns_staging::orders [{ id: 1 }];
from dm_ns_prod::orders

Idempotent creation

if not exists makes creation safe to re-run, which matters for setup scripts and migrations. The result reports created: false when the namespace was already there:

create namespace dm_ns if not exists

Nested namespaces

Namespaces nest. Creating dm_ns::internal places a child namespace under dm_ns, and objects inside it are addressed with the full path, for example dm_ns::internal::audit. Use nesting to group related state without inventing name prefixes:

create namespace dm_ns::internal;
create table dm_ns::internal::audit { id: int4, action: utf8 };
insert dm_ns::internal::audit [{ id: 1, action: "login" }];
from dm_ns::internal::audit

Inspecting namespaces

The system catalog is itself queryable. system::namespaces lists every namespace with its full name, its local name, and the id of its parent - nested namespaces show up as children of the namespace that contains them:

from system::namespaces
filter { local_name == "internal" }

The system namespace also exposes system::tables, system::views, system::policies, and storage metrics. Reads on system::* are policy-gated for non-root identities.

Where to go next

• --Tables - the primary shape for authoritative state
• --Policies - control what each identity may read and write, per namespace or per object
• --Data Model overview - all primitives at a glance