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:
| Declaration | Enforces | Accelerates |
|---|---|---|
| Unique constraint | No two nodes of a label share the value (or tuple) | Equality lookups and MERGE on the key |
| Index | Nothing | Equality and IN lookups, numeric ranges, vector-search filters |
| Vector index | Embedding dimension on write | KNN search |
| Full-text index | Nothing | search.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 EXISTSFOR (u:User) REQUIRE u.email IS UNIQUE- The name (
user_email) is optional. Without one, the constraint is nameduniq_<Label>_<property>. IF NOT EXISTSmakes 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 EXISTSFOR (c:Config) REQUIRE (c.tenant, c.name) IS UNIQUENo 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
INfilters (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.bm25andsearch.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 pProject [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 INDEXESSHOW 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
| Statement | Removes |
|---|---|
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
| Procedure | Yields |
|---|---|
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 labelThese 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:
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.