neo4j-import-skill
Import structured data into Neo4j — LOAD CSV, CALL IN TRANSACTIONS, neo4j-admin
neo4j-contrib · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-import-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 size | DB state | Source | Method |
|---|---|---|---|
| Any size | Online | CSV (Aura or local) | LOAD CSV + CALL IN TRANSACTIONS |
| < 1M rows | Online | List/API response | UNWIND + CALL IN TRANSACTIONS |
| > 10M rows | Offline (local/self-managed) | CSV / Parquet | neo4j-admin database import full |
| Any size | Online | APOC available | apoc.periodic.iterate + apoc.load.csv |
| Any size | Online | JSON/API | apoc.load.json or driver batching |
| Incremental delta | Offline (Enterprise) | CSV | neo4j-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
populationPercentuntil 100% - Creating extra indexes before import slows every write during load with no benefit
-
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. Seeneo4j-cypher-skill/references/graph-type.md. Use individualCREATE CONSTRAINTon Community Edition or pre-2026.02. -
Verify APOC if using apoc. procedures*:
RETURN apoc.version();If fails → APOC not installed. Use plain LOAD CSV instead.
-
Confirm target is PRIMARY (not replica):
CALL dbms.cluster.role() YIELD role RETURN role;If role ≠
PRIMARY→ stop. Redirect write to PRIMARY endpoint. -
Count source file rows before import (catch encoding issues early):
wc -l data/persons.csv # Linux/macOS -
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""notnull— usenullIf(row.x, '')to convert toInteger(null)throws → always usetoIntegerOrNull()toFloat(null)throws → always usetoFloatOrNull()- Neo4j never stores
nullproperties — 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)
| Scheme | Example |
|---|---|
| AWS S3 | s3://my-bucket/data/persons.csv |
| Google Cloud Storage | `gs://my-bucket/persons. |