Chapter 12 · APOC, Procedures, Functions, Triggers-Like Workflows, and Extending Cypher
Decide When to Use Pure Cypher, APOC, Application Code, or a Custom Extension for a Real Requirement
Choose the least-coupled correct implementation for each AtlasMart requirement and prove extension value with compatibility, security and identical-result evidence.
Learning outcomes
The final chapter exercise is a design review. AtlasMart wants product normalization, a bounded supply-chain traversal, a supplier JSON feed, order-event publication and one specialized transformation. The team must choose where each responsibility belongs rather than adopting one extension technology for everything.
Use a repeatable decision matrix for pure Cypher, APOC Core, application code and custom Java extensions.
Compare identical-result implementations before choosing on syntax convenience.
Account for upgrade/support/security/portability costs in technical design.
Keep external side effects and retry-sensitive workflows outside opaque database hooks where possible.
Produce an extension inventory with owner, version, privilege, evidence and rollback metadata.
The mandatory lab continues Neo4j Community
2026.07.1, database neo4j, explicit
CYPHER 25 for version-sensitive examples,
container atlasmart-neo4j, authentication
enabled, loopback HTTP/Bolt endpoints, and the AtlasMart
identifiers/model built in Chapters 01–11. Neo4j
5.26.30 remains the LTS comparison line. This
chapter adds APOC Core 2026.07.1 as an optional
extension; APOC Extended is never required.
This generation environment does not run the Neo4j container, so no plugin load, procedure list, filesystem read/write, HTTP request, trigger execution or custom-JAR output is invented. The lab tells you exactly what to inspect. Community Edition lacks Enterprise RBAC/load privileges, so the free path emphasizes configuration minimization, loopback-only access, file/network denial by default, and application-level authorization boundaries.
1. Start with the least-coupled layer that satisfies the requirement
| Requirement | Default choice | Escalate when |
|---|---|---|
| Graph filtering/projection/aggregation | Pure Cypher | Language cannot express required operation clearly/efficiently |
| Dynamic maps/text utilities/configurable traversal | APOC Core | Measured benefit outweighs server plugin coupling |
| External APIs, messaging, business orchestration | Application/service code | Rare server-local capability is unavoidable and carefully controlled |
| Specialized deterministic server computation | Custom function/procedure | Native/APOC/application alternatives cannot meet a proven latency/data-locality requirement |
| Post-commit external side effect | Transactional outbox + worker | A trigger is intentionally accepted with explicit operational ownership |
2. AtlasMart requirement-by-requirement review
| Requirement | Chosen implementation | Reason |
|---|---|---|
| Product response map | Pure Cypher map projection | No plugin dependency; clear query contract |
| Dynamic metadata map merge | APOC apoc.map.merge |
Dynamic keys make Core helper simpler; identical-output test retained |
| Supply-chain traversal with complex allow/deny filters |
APOC apoc.path.expandConfig only if
quantified Cypher becomes materially less clear
|
Explicit bounds and dense-fixture test required |
| Supplier JSON integration | Application fetch/validate preferred; APOC only for controlled local/server-side integration | Application provides stronger egress/secret/testing boundary |
| Order-ready notification | Outbox node + worker | External side effect stays retryable/idempotent outside DB transaction |
| SKU normalization | Pure/application code by default | Custom JVM function is excessive unless profiling proves server-local benefit |
3. Build an extension inventory before production
neo4j_extensions: server: 2026.07.1 cypher: 25 apoc_core: version: 2026.07.1 required_names: - apoc.map.merge - apoc.path.expandConfig unrestricted: [] file_import: false file_export: false outbound_http: false apoc_extended: installed: false custom_jars: [] triggers: [] owner: data-platform rollback: remove optional plugin usage, restart tested server imageThe inventory makes hidden operational coupling visible. Add checksums/SBOMs and exact artifact provenance in a real production repository.
4. Evidence suite: identical results before architecture claims
CYPHER 25MATCH (p:Product)WHERE p.productId IN ['P-1001','P-2001']RETURN p{.productId,.name,.category,.price} AS productORDER BY product.productId;CYPHER 25MATCH (p:Product)WHERE p.productId IN ['P-1001','P-2001']WITH apoc.map.merge( {productId:p.productId,name:p.name}, {category:p.category,price:p.price}) AS productRETURN productORDER BY product.productId;First prove semantic equivalence. Then benchmark representative sparse/dense data after warmup, measure DB/server/client costs, and record version/config. If the APOC variant is merely shorter, that is a readability observation—not a performance result.
5. Failure-injection review
| Failure | What must remain true |
|---|---|
| APOC JAR absent/mismatched | Application detects missing capability at startup/health check; no silent fallback with changed semantics |
| File access disabled | Integration fails closed; no configuration drift that opens arbitrary paths |
| HTTP source unavailable | Graph state is not partially mutated without explicit reconciliation semantics |
| Driver retries transaction | External side effects are not duplicated because they are outside the retryable callback or keyed idempotently |
| Custom function throws | Query fails visibly; input remains available for diagnosis; no server-wide instability |
| Upgrade removes/deprecates helper | Compatibility test catches it before production and native/application fallback is documented |
6. Deliberately wrong: “APOC everywhere” platform standard
Standardizing one library can reduce discoverability cost, but making every transformation depend on APOC adds server coupling even when native Cypher is clearer. The opposite extreme—banning all extensions—can force excessive client round trips or reimplementation. The correct standard is a decision process with measurable acceptance criteria and an extension inventory.
7. Production scorecard
| Dimension | Pure Cypher | APOC Core | Application code | Custom extension |
|---|---|---|---|---|
| Upgrade coupling | Low | Medium | Low to DBMS | High |
| Server attack surface | Lowest | Depends on enabled procedures/config | Moves network/file privileges to service boundary | Highest if poorly controlled |
| Data locality | High | High | Requires Bolt transfer | High |
| Portability to managed tiers | Usually highest | Procedure availability/tier dependent | High if driver-compatible | Often lowest |
| Testing isolation | Query tests | Query + plugin/version tests | Conventional unit/integration tests | Harness + server deployment tests |
| Best use | Graph language logic | Well-scoped supported utilities | Orchestration/external I/O | Proven server-side capability gap |
Check your understanding
- What is the default layer for ordinary graph filtering/projection?
- When is APOC Core a strong choice?
- Where should most external HTTP/messaging business workflows live?
- What must exist before custom-JAR production deployment?
- What should the team record for every extension?
Review the answers
1. Pure Cypher, because it minimizes deployment coupling and keeps semantics visible.
2. When a supported helper materially improves a stable requirement and its privilege/version/portability cost is acceptable.
3. Application/workflow services, coordinated with durable graph state such as an outbox event.
4. Pinned build, tests/Harness, security review, provenance, server compatibility evidence, observability and rollback.
5. Exact version/artifact, required names, privileges/config, owner, tests, platform support and rollback path.
8. Chapter cleanup and bridge
Keep APOC Core installed only if later chapters need it; otherwise document/remove the dependency and recreate the disposable container without the plugin. Chapter 13 shifts from extension points to official application drivers, connection pools, sessions, transactions and result consumption.
CYPHER 25RETURN apoc.version() AS apocVersion;SHOW PROCEDURES YIELD name WHERE name STARTS WITH 'apoc.' RETURN count(*) AS apocProcedureCount;SHOW FUNCTIONS YIELD name WHERE name STARTS WITH 'apoc.' RETURN count(*) AS apocFunctionCount;Summary
Extension power should be earned by evidence. Pure Cypher minimizes coupling, APOC Core supplies supported utilities, application code owns orchestration and external side effects, and custom Java is reserved for a proven server-side gap. Security, support status, compatibility, observability and rollback are part of the feature—not operational paperwork added later.
Authoritative references
- Current Neo4j versions — Release/LTS snapshot used for this chapter.
- APOC Core 2026.07 documentation — Current officially supported APOC Core manual.
- APOC installation and compatibility — Matching Neo4j/APOC year-month lines, deployment and restart requirements.
- APOC introduction: Core vs Extended — Support boundary between officially supported Core and community-maintained Extended.
- APOC security guidelines — Allowlist/unrestricted execution, file/network and SSRF guidance.
- APOC configuration — apoc.conf location, file/HTTP/trigger-related settings and defaults.
- APOC procedures and functions — Current procedure/function catalog and Cypher 25 status.
- Neo4j Java Reference: extending Neo4j — Custom procedures, functions and server extension boundaries.
- APOC deprecations and compatibility — Cypher 25 compatibility and current APOC deprecations/removals.
- Neo4j plugin configuration — Current plugin identifiers and deployment context.