Neo4j Import Skill

Neo4j Import Skill

When to Use

• Importing CSV, JSON, or Parquet files into Neo4j
• Batch-upserting nodes and relationships (UNWIND + CALL IN TRANSACTIONS)
• Migrating relational data (SQL → graph)
• Bulk-loading large datasets offline (neo4j-admin import)
• Choosing between online (Cypher) and offline (admin) import methods
• Verifying import completeness (counts, constraints, index states)

When NOT to Use

• Unstructured docs, PDFs, vector chunks → neo4j-document-import-skill
• Live application writes (MERGE/CREATE in app code) → neo4j-cypher-skill
• neo4j-admin backup/restore/config → neo4j-cli-tools-skill
• GDS algorithm projection from existing graph → neo4j-gds-skill

Method Decision Table

Aura: only https:// URLs — no file:///. Use neo4j-admin import only on self-managed.

Pre-Import Checklist

Run in this exact order — skipping causes hard-to-debug duplicates or missed index usage:

Constraints BEFORE import. Additional indexes AFTER import.

• Constraints create implicit RANGE indexes used by MERGE during load + enforce uniqueness
• Additional non-unique indexes (TEXT, RANGE on non-key props, FULLTEXT) created after load — Neo4j populates them async from the committed data; poll populationPercent until 100%
• Creating extra indexes before import slows every write during load with no benefit

1. Create uniqueness constraints (enables index used by MERGE):

   cypherCopy code
   CREATE CONSTRAINT IF NOT EXISTS FOR (n:Person) REQUIRE n.id IS UNIQUE;
   CREATE CONSTRAINT IF NOT EXISTS FOR (n:Movie)  REQUIRE n.movieId IS UNIQUE;
   

   Neo4j 2026.06+ (Enterprise/Aura, GA): ALTER CURRENT GRAPH TYPE SET { … } replaces all individual constraint statements with a single declarative block. See neo4j-cypher-skill/references/graph-type.md. Use individual CREATE CONSTRAINT on Community Edition or pre-2026.02.

2. Verify APOC if using apoc. procedures*:

   cypherCopy code
   RETURN apoc.version();
   

   If fails → APOC not installed. Use plain LOAD CSV instead.

3. Confirm target is PRIMARY (not replica):

   cypherCopy code
   CALL dbms.cluster.role() YIELD role RETURN role;
   

   If role ≠ PRIMARY → stop. Redirect write to PRIMARY endpoint.

4. Count source file rows before import (catch encoding issues early):

   bashCopy code
   wc -l data/persons.csv    # Linux/macOS
   

5. Verify UTF-8 encoding — LOAD CSV requires UTF-8. Re-encode if needed:

   bashCopy code
   file -i persons.csv       # Check encoding
   iconv -f latin1 -t utf-8 persons.csv > persons_utf8.csv
   

LOAD CSV Patterns

Basic node import with type coercion and null handling

cypherCopy code
CYPHER 25
LOAD CSV WITH HEADERS FROM 'file:///persons.csv' AS row
CALL (row) {
  MERGE (p:Person {id: row.id})
  ON CREATE SET
    p.name       = row.name,
    p.age        = toIntegerOrNull(row.age),
    p.score      = toFloatOrNull(row.score),
    p.active     = toBoolean(row.active),
    p.born       = CASE WHEN row.born IS NOT NULL AND row.born <> '' THEN date(row.born) ELSE null END,
    p.createdAt  = datetime()
  ON MATCH SET
    p.updatedAt  = datetime()
} IN TRANSACTIONS OF 10000 ROWS
  ON ERROR CONTINUE
  REPORT STATUS AS s
RETURN s.transactionId, s.committed, s.errorMessage

Null/empty-string rules:

• CSV missing column → null (safe)
• CSV empty string "" → stored as "" not null — use nullIf(row.x, '') to convert
• toInteger(null) throws → always use toIntegerOrNull()
• toFloat(null) throws → always use toFloatOrNull()
• Neo4j never stores null properties — they are silently dropped on SET

Relationship import (nodes must exist first)

cypherCopy code
CYPHER 25
LOAD CSV WITH HEADERS FROM 'file:///knows.csv' AS row
CALL (row) {
  MATCH (a:Person {id: row.fromId})
  MATCH (b:Person {id: row.toId})
  MERGE (a)-[:KNOWS {since: toIntegerOrNull(row.year)}]->(b)
} IN TRANSACTIONS OF 5000 ROWS
  ON ERROR CONTINUE
  REPORT STATUS AS s

Always import ALL nodes before ANY relationships — MATCH fails on missing nodes.

Tab-separated or custom delimiter

cypherCopy code
CYPHER 25
LOAD CSV WITH HEADERS FROM 'file:///data.tsv' AS row FIELDTERMINATOR '\t'
CALL (row) { MERGE (p:Person {id: row.id}) }
IN TRANSACTIONS OF 10000 ROWS ON ERROR CONTINUE

Compressed files (ZIP / gzip — local files only)

cypherCopy code
LOAD CSV WITH HEADERS FROM 'file:///archive.csv.gz' AS row ...

Cloud storage (Enterprise Edition)

Useful built-in functions inside LOAD CSV

cypherCopy code
linenumber()   // current line number — use as fallback ID
file()         // absolute path of file being loaded

CALL IN TRANSACTIONS — Full Reference

Syntax

cypherCopy code
CALL (row) {
  // write logic
} IN [n CONCURRENT] TRANSACTIONS
  [OF batchSize ROW[S]]
  [ON ERROR {CONTINUE | BREAK | FAIL | RETRY [FOR duration SECONDS] [THEN {CONTINUE|BREAK|FAIL}]}]
  [REPORT STATUS AS statusVar]

ON ERROR modes

ON ERROR CONTINUE/BREAK → outer transaction succeeds even if inner batches fail. ON ERROR FAIL → cannot be combined with REPORT STATUS AS.

CONCURRENT TRANSACTIONS (parallel batches)

cypherCopy code
CYPHER 25
LOAD CSV WITH HEADERS FROM 'file:///large.csv' AS row
CALL (row) {
  MERGE (p:Person {id: row.id}) SET p.name = row.name
} IN 4 CONCURRENT TRANSACTIONS OF 5000 ROWS
  ON ERROR RETRY FOR 30 SECONDS THEN CONTINUE
  REPORT STATUS AS s

Use CONCURRENT for read-heavy MERGE on non-overlapping key spaces. Risk: deadlocks on overlapping writes → combine with ON ERROR RETRY.

REPORT STATUS columns

Batch size guidance

neo4j-admin import (Offline Bulk Load)

Fastest method: ~3 min for 31M nodes / 78M rels on SSD. DB must be stopped or non-existent.

Command structure

bashCopy code
neo4j-admin database import full \
  --nodes=Person="persons_header.csv,persons.csv" \
  --nodes=Movie="movies_header.csv,movies.csv" \
  --relationships=ACTED_IN="acted_in_header.csv,acted_in.csv" \
  --relationships=DIRECTED="directed_header.csv,directed.csv" \
  --delimiter=, \
  --id-type=STRING \
  --bad-tolerance=0 \
  --threads=$(nproc) \
  --high-parallel-io=on \
  neo4j

Dry run (2026.02+) — validate without writing:

bashCopy code
neo4j-admin database import full --dry-run ...

Node header file format

Copy code
# persons_header.csv
personId:ID,name,born:int,score:float,active:boolean,:LABEL

Copy code
# persons.csv (data file — no header row)
p001,Alice,1985,9.2,true,Person
p002,Bob,1990,7.1,false,Person

Relationship header file format

Copy code
# acted_in_header.csv
:START_ID(Person),:END_ID(Movie),role,:TYPE

Copy code
# acted_in.csv
p001,tt0133093,Neo,ACTED_IN
p002,tt0133093,Morpheus,ACTED_IN

:START_ID / :END_ID must reference the same :ID group as the node files.

Key flags

Schema file (--schema) [Enterprise, block format]

Pass a Cypher file with CREATE CONSTRAINT / CREATE INDEX statements; executed automatically after import completes. Constraints are created first (correct order enforced). File paths can be local or remote (s3://, gs://, https://).

bashCopy code
neo4j-admin database import full \
  --format=block \
  --schema=schema.cypher \
  --nodes=Person="persons_header.csv,persons.csv" \
  neo4j

cypherCopy code
// schema.cypher
CREATE CONSTRAINT person_id IF NOT EXISTS FOR (n:Person) REQUIRE n.id IS UNIQUE;
CREATE CONSTRAINT movie_id  IF NOT EXISTS FOR (n:Movie)  REQUIRE n.id IS UNIQUE;
CREATE RANGE INDEX person_email IF NOT EXISTS FOR (n:Person) ON (n.email);
CREATE TEXT  INDEX movie_title  IF NOT EXISTS FOR (n:Movie)  ON (n.title);

For incremental import, DROP CONSTRAINT / DROP INDEX are also supported [2025.02+] — used to remove indexes before the merge phase and recreate them after for faster writes. --schema also accepts graph-type DDL: ALTER CURRENT GRAPH TYPE SET {…} for full [2026.05+], ALTER CURRENT GRAPH TYPE ADD/DROP/ALTER {…} for incremental [2026.06+] — see neo4j-cypher-skill/references/graph-type.md.

Incremental import (Enterprise only)

Three-phase process — use when DB must stay online during import preparation:

bashCopy code
# Phase 1: Prepare staging area
neo4j-admin database import incremental --stage=prepare \
  --nodes=Person=persons_header.csv,delta.csv --force neo4j

# Phase 2: Build indexes (DB can be read-only during this phase)
neo4j-admin database import incremental --stage=build neo4j

# Phase 3: Merge into live database (brief write-lock)
neo4j-admin database import incremental --stage=merge neo4j

Requires Enterprise Edition + block store format.

APOC Patterns (when APOC is available)

Verify first: RETURN apoc.version() — if fails, use LOAD CSV or driver instead.

apoc.periodic.iterate — batch-process existing graph data

cypherCopy code
CALL apoc.periodic.iterate(
  "MATCH (p:Person) WHERE NOT (p)-[:HAS_ACCOUNT]->() RETURN p",
  "CREATE (p)-[:HAS_ACCOUNT]->(a:Account {id: randomUUID()})",
  {batchSize: 10000, parallel: false, retries: 2}
) YIELD batches, total, errorMessages
RETURN batches, total, errorMessages

Prefer CALL IN TRANSACTIONS (native Cypher) over apoc.periodic.iterate for new code — it has REPORT STATUS, CONCURRENT, and RETRY built in without APOC dependency.

apoc.load.csv — load with config options

cypherCopy code
CALL apoc.load.csv('file:///persons.csv', {
  header: true,
  sep: ',',
  skip: 1,
  limit: 1000000
}) YIELD lineNo, map, list
CALL (map) {
  MERGE (p:Person {id: map.id}) SET p.name = map.name
} IN TRANSACTIONS OF 10000 ROWS ON ERROR CONTINUE

apoc.load.json — load JSON from file or URL

cypherCopy code
CALL apoc.load.json('https://api.example.com/persons') YIELD value
CALL (value) {
  MERGE (p:Person {id: value.id}) SET p.name = value.name
} IN TRANSACTIONS OF 1000 ROWS ON ERROR CONTINUE

Driver Batch Write Pattern

Use when source is not a file (API responses, DB migrations). Collect into BATCH_SIZE (10 000) lists, call UNWIND $rows AS row MERGE ... per batch. ~10x faster than row-at-a-time. → Python + JS examples

MCP Tool Usage

Write gate — before any bulk write via MCP, show:

1. Query + affected labels
2. Estimated row count from source
3. EXPLAIN plan

Wait for user confirmation. Never auto-execute CALL IN TRANSACTIONS or CREATE CONSTRAINT without confirmation.

Always pass database param if not default: {"code": "...", "database": "neo4j"}.

Common Errors

Post-Import Validation

After import completes — run all:

cypherCopy code
// Row counts per label
MATCH (n:Person) RETURN count(n) AS persons;
MATCH ()-[:KNOWS]->() RETURN count(*) AS knows_rels;

// After import: create additional non-unique indexes (populated async)
CREATE TEXT INDEX movie_title IF NOT EXISTS FOR (n:Movie) ON (n.title);
CREATE RANGE INDEX person_born IF NOT EXISTS FOR (n:Person) ON (n.born);

// Poll population — wait until populationPercent = 100 before opening to queries
SHOW INDEXES YIELD name, state, populationPercent
WHERE state <> 'ONLINE' OR populationPercent < 100
RETURN name, state, populationPercent
ORDER BY populationPercent;

// Spot check: null keys = import bug
MATCH (p:Person) WHERE p.id IS NULL RETURN count(p) AS missing_id;

Do NOT run production queries until all indexes are ONLINE.

References

• LOAD CSV — Cypher Manual 25
• CALL IN TRANSACTIONS — Cypher Manual
• neo4j-admin database import
• APOC periodic execution
• APOC load procedures
• GraphAcademy: Importing CSV Data
• Indexes and constraints — types, MERGE lock semantics, import pre-flight
• Data Importer GUI — when to use, Aura access, multi-pass, gotchas
• Post-import refactoring — split lists, extract nodes, add labels, FK validation

Checklist

• Uniqueness constraints created before any MERGE-based import
• APOC availability verified if using apoc.* procedures
• Target confirmed as PRIMARY (not replica)
• Source files validated: UTF-8 encoding, expected row count, no BOM
• LOAD CSV uses toIntegerOrNull() / toFloatOrNull() — never bare toInteger()/toFloat()
• nullIf(row.x, '') applied where empty string ≠ null
• CALL IN TRANSACTIONS used (not USING PERIODIC COMMIT)
• ON ERROR CONTINUE + REPORT STATUS for production loads
• Node import completed before relationship import
• neo4j-admin: --bad-tolerance=0 set; --high-parallel-io=on for SSD
• Post-import: row counts match source; all indexes ONLINE
• Write execution gate applied (MCP): showed query + estimate, got confirmation
• Credentials in .env; .env in .gitignore