Collections

A collection is NodeDB's top-level data container — analogous to a table in PostgreSQL or a collection in MongoDB. Each collection has a storage engine chosen at creation time.

Creating Collections

-- Schemaless document (default)
CREATE COLLECTION users;

-- Strict document (schema-enforced)
CREATE COLLECTION orders (
    id UUID DEFAULT gen_uuid_v7(),
    customer_id UUID NOT NULL,
    total DECIMAL NOT NULL,
    status STRING DEFAULT 'pending'
) WITH (engine='document_strict');

-- Columnar (analytics)
CREATE COLLECTION events (
    ts TIMESTAMP TIME_KEY,
    user_id UUID,
    event VARCHAR,
    duration_ms INT
) WITH (engine='columnar');

-- Key-Value
CREATE COLLECTION sessions (key TEXT PRIMARY KEY) WITH (engine='kv');

Storage Engines

NodeDB has eight peer engines. Seven of them are picked per collection via WITH (engine='<name>') — the default (no engine=) is document_schemaless. The eighth, Array, uses its own CREATE ARRAY DDL family. See Array Engine for that path.

Engine	Selector	Best for
`document_schemaless`	(default)	Flexible data, prototyping, agent state
`document_strict`	`WITH (engine='document_strict')`	OLTP, transactions, known schemas
`columnar`	`WITH (engine='columnar')`	Analytics, reporting, scan-heavy workloads
`timeseries`	`WITH (engine='timeseries')`	Append-only metrics, retention, continuous aggs
`spatial`	`WITH (engine='spatial')`	Geo-primary workloads, R*-tree, OGC predicates
`kv`	`WITH (engine='kv')`	Sessions, caches, counters, key-dominant access
`vector`	`WITH (engine='vector', vector_field='emb')`	Vector-primary collections

Column modifiers add capabilities to any engine:

Modifier	Effect
`TIME_KEY`	Marks the time column (used by timeseries engine, allowed elsewhere)
`SPATIAL_INDEX`	R*-tree index on a `GEOMETRY` column
`PRIMARY KEY`	Row identity column (inline only — table-level not supported)

Cross-Engine Indexes

Any collection can have indexes from multiple engines:

CREATE COLLECTION products;

-- Add a vector index for semantic search
CREATE VECTOR INDEX ON products METRIC cosine DIM 384;

-- Add a full-text index for keyword search
CREATE SEARCH INDEX ON products FIELDS title, description ANALYZER 'english';

-- Add a spatial index for location queries
CREATE SPATIAL INDEX ON products FIELDS location;

-- Add graph edges for relationships
GRAPH INSERT EDGE IN 'products' FROM 'products:p1' TO 'products:p2' TYPE 'similar';

Converting Between Engines

Collections can be converted at any time without data loss:

CONVERT COLLECTION users TO document_strict;
CONVERT COLLECTION cache TO kv;
CONVERT COLLECTION events TO document_schemaless;

NodeDB infers the schema from existing documents when converting to strict mode.