Install APOC Core plugin and confirm availability: CALL apoc.help('periodic.iterate') YIELD name, text RETURN name, text
Call apoc.periodic.iterate with a data-fetching Cypher as the first argument and a mutation Cypher as the second, passing batchSize to control commit frequency: CALL apoc.periodic.iterate('MATCH (n:OldNode) RETURN n', 'SET n:NewLabel REMOVE n:OldNode', {batchSize: 1000, parallel: false})
Use parallel: true only when the mutation Cypher operates on disjoint node sets to avoid deadlocks; for connected graph mutations keep parallel: false
Capture the return value to check for errors: YIELD batches, total, timeTaken, committedOperations, failedOperations, errorMessages
For very large graphs set iterateList: true (default) to pass a batch list to the inner query rather than re-running the outer query per batch, which reduces planning overhead
Monitor progress by periodically running CALL apoc.periodic.list() to see running jobs
Known gotchas
apoc.periodic.iterate runs within the same transaction scope per batch — if the inner query fails, only that batch is rolled back; set retries: 2 in the config map to retry failed batches automatically
The outer (data-fetching) query must be read-only; placing write operations in the outer query causes unpredictable behavior as it is re-executed per batch
APOC Core and APOC Extended are separate plugins since Neo4j 5; apoc.periodic.iterate is in APOC Core — verify the correct JAR is installed for your Neo4j version
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp