CREATE

Generic Description

Insert new nodes, relationships, and property structures exactly as written.

Simple example:

CREATE (:Person {name: 'Alix'})

Consumer-Level Explanation

Use CREATE when the query must insert new nodes, relationships, and property structures exactly as written and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

CREATE is the direct insertion primitive. It is best when you know you want a new structure, not a match-or-create workflow. In Nexyron it is often paired with UNWIND for batch inserts or with document-style property maps for richer payload creation.

What this clause is really for:

it defines one concrete stage in the Cypher row pipeline, so variables available before and after CREATE must be clear
it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps CREATE inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

UNWIND [{user_id: 'u-1', doc_id: 'd-1', ts: '2025-01-02T10:00:00Z', payload: {kind: 'view'}, doc_metadata: {kind: 'report'}, embedding: [0.22, 0.18, 0.44]}] AS evt
MERGE (u:User {user_id: evt.user_id})
MERGE (d:Document {doc_id: evt.doc_id})
CREATE (u)-[e:VIEWED]->(d)
SET e.ts = toDateTime(evt.ts),
    e.payload = evt.payload,
    d.metadata = evt.doc_metadata,
    d.embedding = vector(evt.embedding)
WITH u, d, e, date_trunc('day', e.ts) AS day_bucket
RETURN u.user_id, d.doc_id, day_bucket, keys(properties(d)) AS doc_keys

Real Use Cases

deterministic ingestion of new facts
loading event or content entities from upstream streams
seed data creation

Real Limitations And Tradeoffs

no deduplication logic is implied
naive repeated CREATE can produce duplicate logical entities
bulk CREATE benefits from careful batching patterns