Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Data & analytics

neo4j-import-skill

Import structured data into Neo4j — LOAD CSV, CALL IN TRANSACTIONS, neo4j-admin

neo4j-contrib · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-import-skill

About this skill


name: neo4j-import-skill description: Import structured data into Neo4j — LOAD CSV, CALL IN TRANSACTIONS, neo4j-admin database import full (offline bulk), apoc.load.csv/json, apoc.periodic.iterate, driver batch writes. Covers method selection, header file format, type coercion, null handling, ON ERROR modes, CONCURRENT TRANSACTIONS, pre-import constraint setup, and post-import validation. Use when importing CSV/JSON/Parquet files, migrating relational data to graph, or bulk-loading large datasets. Does NOT handle unstructured document/PDF/vector chunking pipelines — use neo4j-document-import-skill. Does NOT handle live app write patterns (MERGE/CREATE) — use neo4j-cypher-skill. Does NOT handle neo4j-admin backup/restore/config — use neo4j-cli-tools-skill. version: 1.0.11 allowed-tools: Bash WebFetch

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

Dataset sizeDB stateSourceMethod
Any sizeOnlineCSV (Aura or local)LOAD CSV + CALL IN TRANSACTIONS
< 1M rowsOnlineList/API responseUNWIND + CALL IN TRANSACTIONS
> 10M rowsOffline (local/self-managed)CSV / Parquetneo4j-admin database import full
Any sizeOnlineAPOC availableapoc.periodic.iterate + apoc.load.csv
Any sizeOnlineJSON/APIapoc.load.json or driver batching
Incremental deltaOffline (Enterprise)CSVneo4j-admin database import incremental

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):

    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*:

    RETURN apoc.version();
    

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

  3. Confirm target is PRIMARY (not replica):

    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):

    wc -l data/persons.csv    # Linux/macOS
    
  5. Verify UTF-8 encoding — LOAD CSV requires UTF-8. Re-encode if needed:

    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

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)

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

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)

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

Cloud storage (Enterprise Edition)

SchemeExample
AWS S3s3://my-bucket/data/persons.csv
Google Cloud Storage`gs://my-bucket/persons.
Read the complete source ↗