Skip to content

Schema — constraints and indexes

NamiDB is schema-optional: labels, relationship types and properties need no declaration. You declare only what you want enforced or accelerated:

DeclarationEnforcesAccelerates
Unique constraintNo two nodes of a label share the value (or tuple)Equality lookups and MERGE on the key
IndexNothingEquality and IN lookups, numeric ranges, vector-search filters
Vector indexEmbedding dimension on writeKNN search
Full-text indexNothingsearch.bm25, the text leg of search.hybrid

Constraints and indexes apply to node properties. Relationship property constraints and indexes are not supported.

Every DDL statement must be the only statement in its request (one HTTP call, one cypher() call, one Bolt run). The CLI’s ;-separated scripts run each statement separately, so a schema script works there.

Unique constraints

CREATE CONSTRAINT user_email IF NOT EXISTS
FOR (u:User) REQUIRE u.email IS UNIQUE
  • The name (user_email) is optional. Without one, the constraint is named uniq_<Label>_<property>.
  • IF NOT EXISTS makes the statement a no-op when an equivalent constraint already exists. Without it, re-declaring fails: a uniqueness constraint on User(email) already exists.
  • The Neo4j 4 spelling also works: CREATE CONSTRAINT ON (u:User) ASSERT u.email IS UNIQUE.
  • Declaring a constraint on a label that already holds duplicate values fails: cannot create unique constraint on User(email): duplicate (email=Str("a")) already exists.

A write that would break the constraint is rejected and the whole statement rolls back (HTTP 409, code: "constraint"):

constraint violation: User.email = Str("a@x") already exists (unique constraint)

Composite uniqueness

CREATE CONSTRAINT cfg_uq IF NOT EXISTS
FOR (c:Config) REQUIRE (c.tenant, c.name) IS UNIQUE

No two :Config nodes may share the same (tenant, name) tuple. The constraint applies only to nodes that carry every listed property; a node missing one of them is not checked.

constraint violation: (tenant = Str("t"), name = Str("n")) already exists (composite unique constraint on Config)

Values are typed: the integer 1 and the string '1' are different keys.

Indexes

// One property:
CREATE INDEX FOR (d:Doc) ON (d.slug)
// A composite (tuple) index, named and idempotent:
CREATE INDEX doc_ts IF NOT EXISTS FOR (d:Doc) ON (d.tenant, d.slug)
// Neo4j 4 spelling:
CREATE INDEX ON :Doc(slug)

An index speeds up:

  • equality and IN filters (WHERE d.slug = $s, {slug: $s}, WHERE d.slug IN $list);
  • a composite lookup when every indexed property is constrained by equality, in any order (WHERE d.tenant = $t AND d.slug = $s);
  • range predicates on numeric properties (WHERE d.score >= 0.5);
  • metadata filters inside search.vector, search.bm25 and search.hybrid (see filters).

A unique constraint already provides an index on its key; you do not need both.

Single-property indexes are reported as index_<Label>_<property> in SHOW INDEXES, whatever name you gave them; composite indexes keep their name.

Indexes and constraints can be declared before or after the data is loaded. Declaring them first (“schema, then load”) is fully supported, including for numeric keys since 3.2.0.

Check whether a query uses an index with EXPLAIN: an indexed lookup shows as NodeByPropertyValue with a # route: line instead of a filtered NodeScan:

EXPLAIN MATCH (p:Person {id: 1}) RETURN p
Project [p=p]
NodeByPropertyValue label=Person alias=p id=1
Empty
# route: Person.id → memtable (unique lookup; no SSTs in scope)

Show what is declared

SHOW CONSTRAINTS
[{"name": "cfg_uq", "type": "UNIQUENESS", "entityType": "NODE",
"labelsOrTypes": ["Config"], "properties": ["tenant", "name"]},
{"name": "u_email", "type": "UNIQUENESS", "entityType": "NODE",
"labelsOrTypes": ["User"], "properties": ["email"]}]
SHOW INDEXES

SHOW INDEXES returns the same columns, with type RANGE for property and composite indexes (including the index behind each single-property unique constraint), VECTOR for vector indexes and FULLTEXT for full-text indexes. Only the bare forms are accepted: SHOW CONSTRAINT[S] and SHOW INDEX[ES], without YIELD, BRIEF or VERBOSE.

Dropping

StatementRemoves
DROP INDEX <name> [IF EXISTS]A full-text index
DROP VECTOR INDEX <name> [IF EXISTS]A vector index

Dropping a unique constraint or a property index is not supported in 3.3.0 (DROP CONSTRAINT does not parse, and DROP INDEX only finds full-text indexes). To change one, load the data into a fresh namespace with the schema you want.

Introspection

ProcedureYields
CALL db.labels()label
CALL db.relationshipTypes()relationshipType
CALL db.propertyKeys()propertyKey
CALL db.schema.visualization()nodes, relationships: one node per label, carrying its constraints and indexes
CALL db.labels() YIELD label RETURN label

These are what graph GUIs and Neo4j tooling call when they connect over Bolt.

A migration script

Because every statement here is idempotent with IF NOT EXISTS, a schema script can run on every deploy. With the CLI:

Terminal window
namidb run --store "file:///var/lib/namidb?ns=prod" "
CREATE CONSTRAINT user_email IF NOT EXISTS FOR (u:User) REQUIRE u.email IS UNIQUE;
CREATE CONSTRAINT cfg_uq IF NOT EXISTS FOR (c:Config) REQUIRE (c.tenant, c.name) IS UNIQUE;
CREATE INDEX doc_ts IF NOT EXISTS FOR (d:Doc) ON (d.tenant, d.slug)
"

Against a running server, send each statement as its own POST /v0/cypher.