Using APOC periodic.commit for Bulk CSV Load in Neo4j

Useful answer

APOC's periodic.commit procedure lets you stream a large CSV file through a series of small transactions, keeping memory usage low and avoiding massive transaction logs.

How periodic.commit works

The procedure takes a Cypher statement string and a map of parameters. It repeatedly executes the statement in batches of the size you specify, committing each batch as its own transaction.

Worked example

CALL apoc.periodic.commit(
  'LOAD CSV WITH HEADERS FROM \"file:///persons.csv\" AS row
   CREATE (:Person {id: toInteger(row.id), name: row.name, age: toInteger(row.age)})',
  {batchSize: 10000}
);

Place the CSV file persons.csv in Neo4j's import directory. Run the statement in Neo4j Browser or via cypher-shell with a user that has permission to execute APOC procedures.

Configuration and permissions

• Ensure apoc plugin matches your Neo4j major version (e.g., APOC 5.13 for Neo4j 5.13).
• Set dbms.security.allow_csv_import_from_file_urls=true in neo4j.conf if you use file:/// URLs.
• The user executing the call needs EXECUTE PROCEDURE on the APOC namespace.

Verification steps

1. After the call finishes, run MATCH (n:Person) RETURN count(n) AS total to confirm the expected number of nodes.
2. Check :server.metrics in Neo4j Browser for transaction count and memory usage; you should see a series of small commits rather than one large spike.
3. Inspect logs/neo4j.log for any APOC warnings about batch size or file access.

Limits and common mistakes

• Each batch is committed independently; a failure rolls back only that batch, not the whole load.
• Choosing a batchSize that is too large can cause out‑of‑memory errors; start with 10 000–50 000 rows and adjust based on your heap.
• Constraints, indexes, or triggers fire per batch, which may increase overhead compared to a single transaction.
• If the CSV is not in the import directory or the allow_csv_import_from_file_urls flag is false, the procedure will throw a “file not found” or permission error.