Chapter 08 · Importing Data: LOAD CSV, Data Importer, Bulk Import, Transformation, and Validation
Neo4j Data Importer Workflows: Mapping Tables to Nodes/Relationships and Validating Generated Models
Use Data Importer as a mapping client and independently prove the generated graph.
Learning outcomes
AtlasMart analysts want a low-code prototype import. Data Importer can accelerate mapping, but a visually plausible mapping can still encode wrong identity, direction or cardinality.
Explain the data-source, model and mapping panels as one import specification.
Map stable source IDs to node identity and relationship endpoints.
Distinguish Desktop/standalone Data Importer from Aura-integrated Import.
Validate generated graph state independently with Cypher.
Detect a table-for-table mapping that conflicts with the target graph model.
The mandatory lab continues Neo4j Community
2026.07.1, database neo4j, explicit
CYPHER 25 for version-sensitive examples,
authentication enabled, no mandatory APOC/GDS plugin, and
stable AtlasMart business identifiers from Chapters 01–07.
Neo4j 5.26.30 remains the LTS comparison line.
Local file:/// sources are a self-managed
server-filesystem feature and are not available on Aura.
This generation environment does not run Neo4j or Docker.
Commands were checked against current official documentation
but were not executed here. Expected outputs are fixture
invariants, not fabricated captures. Every write is scoped to
labTag='ch08', dedicated CSV files, or a
disposable database. Never use broad cleanup, store overwrite,
or offline import commands against unrelated or production
data.
Deterministic Chapter 08 source fixture
The source intentionally contains a duplicate business key, an empty optional field, a malformed numeric value, and orphan foreign keys. Those defects are evidence for preflight and reconciliation, not details to ignore.
customerId,name,email,tierC-8001,Ada Lovelace,ada@example.test,goldC-8002,Grace Hopper,grace@example.test,silverC-8002,Grace Hopper Duplicate,grace.dup@example.test,silverC-8003,Linus Torvalds,,bronzeproductId,name,categoryId,priceP-8001,Trail Camera,CAT-8001,129.90P-8002,Weather Case,CAT-8001,39.50P-8003,Sensor Hub,CAT-8002,not-a-numberP-8004,Field Battery,CAT-MISSING,49.00orderId,customerId,orderedAt,statusO-8001,C-8001,2026-09-01T10:00:00Z,PAIDO-8002,C-8002,2026-09-02T11:30:00Z,SHIPPEDO-8003,C-MISSING,2026-09-03T12:00:00Z,PAIDorderId,productId,quantity,unitPriceO-8001,P-8001,1,129.90O-8001,P-8002,2,39.50O-8002,P-8004,1,49.00O-9999,P-8001,1,129.90The corrected files remove/quarantine duplicate and orphan rows, repair the malformed price, and apply a documented empty-email policy. Keep the rejection ledger so accepted + rejected rows reconcile to the source.
1. Three panels, three decisions
| Panel | Primary decision | Independent evidence |
|---|---|---|
| Data source | Which files/tables and columns enter the import? | Source counts/lineage |
| Data model | Which labels, relationship types and directions exist? | MATCH-based shape checks |
| Mapping/details | Which columns are IDs, properties and endpoints? | Constraint/duplicate/orphan checks |
The canvas is an import specification—not a substitute for the Chapter 07 modeling decisions.
2. Identity before descriptive mapping
Map customerId, orderId and
productId as stable identifiers first. For
PLACED, map customer as the start endpoint and
order as the end endpoint. Reversing the arrow changes traversal
semantics even if both IDs resolve.
3. Deployment boundary
Neo4j Desktop exposes Import as a tool; equivalent standalone
tooling can target self-managed instances. Aura integrates
Import in the managed console and supports additional source
types. The mandatory lesson remains Community/local. Local
file:/// server paths are not an Aura filesystem
mechanism.
4. Deliberately wrong: table-for-table graph
Do not convert every source table into a node label
automatically. A pure order-item join table can often become an
Order → CONTAINS →
Product relationship with quantity and unit price,
unless the line item itself has identity/lifecycle requirements.
Source shape is not target model truth.
5. Validate the UI result independently
CYPHER 25SHOW CONSTRAINTS;MATCH (c:Customer) RETURN count(c) AS customers,count(DISTINCT c.customerId) AS distinctIds;MATCH (o:Order) WHERE NOT EXISTS { MATCH (:Customer)-[:PLACED]->(o) }RETURN collect(o.orderId) AS ordersWithoutCustomer;MATCH (o:Order)-[r:CONTAINS]->(p:Product)RETURN count(r) AS edges,count(DISTINCT [o.orderId,p.productId]) AS distinctPairs;A successful UI message proves that the mapping executed. It does not prove source reconciliation, semantic direction, uniqueness or all business invariants.
Check your understanding
- What is the Data Importer canvas?
- Why map stable IDs first?
- Can file:/// self-managed instructions be used on Aura?
- Why can a join table become a relationship?
- What validates a Data Importer run?
Review the answers
1. A model/mapping specification for import, not independent proof of the business model.
2. Relationships and reruns depend on durable endpoint identity.
3. No; Aura does not expose the server import filesystem that way.
4. If it is a binary fact without independent identity/lifecycle, relationship properties can be the clearer graph model.
5. Independent Cypher counts, constraints, duplicate/orphan checks and domain invariants.
Summary and next step
Data Importer accelerates mapping but not validation. Next, very large initial loads move to the admin/offline import boundary.
Authoritative references
- Current Neo4j versions — Release/LTS snapshot used for the chapter baseline.
- Cypher LOAD CSV — Current LOAD CSV parsing, typing and local/remote source semantics.
- CALL subqueries in transactions — Bounded inner transactions, default batch size and partial-commit behavior.
- Neo4j Admin import — Current full/incremental import, dry run, headers, memory and report behavior.
- Default file locations — Self-managed import-directory and store/log boundaries.
- Desktop Import — Desktop and standalone Import workflow.
- Aura Import — Aura-managed Import source types and role boundary.
- Aura Import visual tour — Source/model/details panels and mapping flow.