Collections, Maps, Text, Date, Conversion, Path Expansion, and Utility Procedures

Learning outcomes

AtlasMart receives product attributes in inconsistent maps and needs a bounded “related supply-chain entities” view. Both requirements can be solved several ways. The engineering question is not whether APOC has a function for them; it is whether APOC adds expressive value without hiding cardinality, compatibility or maintenance costs.

1. Prefer the language first; use APOC for a capability gap

APOC 2025.07+ evolves for Cypher 25. Some older conveniences are deprecated as Cypher gains equivalent language features. A stable codebase treats deprecation reports as migration input rather than freezing historical recipes.

2. Functions preserve the row; procedures can multiply it

CYPHER 25WITH ['Cameras','Store IoT','Cameras'] AS raw,     {source:'erp', priority:1} AS leftMap,     {priority:2, verified:true} AS rightMapRETURN apoc.coll.toSet(raw) AS uniqueCategories,       apoc.map.merge(leftMap,rightMap) AS merged,       apoc.text.clean(' Trail-Camera 1001 ') AS normalized;

A function produces a value in the current row. By contrast, a path procedure can emit many rows per input node, so its cardinality belongs in the query design.

CYPHER 25MATCH (s:Supplier {supplierId:'SUP-1001'})CALL apoc.path.expandConfig(s, {  relationshipFilter:'SUPPLIES>|SUPPLIED_BY<|IN_CATEGORY>|STOCKED_AT>',  minLevel:1,  maxLevel:3,  bfs:true,  uniqueness:'RELATIONSHIP_PATH',  limit:25}) YIELD pathRETURN length(path) AS hops,       [n IN nodes(path) | coalesce(n.productId,n.categoryId,n.storeId,n.supplierId)] AS idsORDER BY hops, ids;

3. Same result, three implementation locations

CYPHER 25MATCH (p:Product {productId:$id})RETURN p{.productId,.name,.category,.price,         displayName: toUpper(p.name)} AS product;

CYPHER 25MATCH (p:Product {productId:$id})WITH p, p{.productId,.name,.category,.price} AS baseRETURN apoc.map.merge(base,{displayName:toUpper(p.name)}) AS product;

record = session.run(    "MATCH (p:Product {productId:$id}) RETURN p{.*} AS product",    id="P-1001",).single()product = dict(record["product"])product["displayName"] = product["name"].upper()

All three can be correct. Native Cypher keeps logic near the query and avoids plugin coupling; APOC is useful for dynamic server-side transformations; application code can be easier to unit-test and keeps presentation logic out of the database. Measure payload size and round trips before assuming one is faster.

4. Edge cases that change the answer

5. Deliberately wrong: APOC path expansion as a universal shortest path engine

apoc.path.expandConfig controls traversal expansion; it is not automatically equivalent to Cypher shortest selectors or a weighted graph algorithm. If AtlasMart asks for minimum freight cost, a “first path returned by BFS” is not a weighted shortest-path guarantee. Choose transactional Cypher for bounded pattern questions and GDS/application algorithms for algorithmic weighted routing.

6. Lab: compare outputs, not syntax length

CYPHER 25MERGE (c:Customer {customerId:'C-1001'})SET c.name='Mina Rahimi'MERGE (p1:Product {productId:'P-1001'})SET p1.name='Trail Camera', p1.category='Cameras', p1.price=129.90MERGE (p2:Product {productId:'P-2001'})SET p2.name='Smart Shelf Sensor', p2.category='Store IoT', p2.price=79.50MERGE (o:Order {orderId:'O-5001'})SET o.status='PAID', o.orderedAt=datetime('2026-09-08T16:30:00Z')MERGE (c)-[:PLACED]->(o)MERGE (o)-[:CONTAINS {quantity:1}]->(p1)MERGE (o)-[:CONTAINS {quantity:2}]->(p2);

CYPHER 25CALL apoc.help('map.merge') YIELD name,type,text RETURN name,type,text;CALL apoc.help('path.expandConfig') YIELD name,type,text RETURN name,type,text;SHOW FUNCTIONS YIELD nameWHERE name IN ['apoc.map.merge','apoc.text.clean','apoc.coll.toSet']RETURN name ORDER BY name;SHOW PROCEDURES YIELD nameWHERE name='apoc.path.expandConfig'RETURN name;

Verification checklist: record whether each helper exists in your exact Core build; run the pure Cypher and APOC variants on the same fixture; compare rows and values; then inspect plan/cardinality separately rather than inferring performance from shorter query text.

7. Production judgment

Every utility moved into the server JVM inherits the server upgrade, memory and security lifecycle. A two-line APOC helper is justified when it makes a stable, well-tested requirement clearer or avoids expensive client round trips. It is not justified merely because it is shorter than native Cypher.

Summary and next step

APOC Core is most useful when it fills a specific language/tooling gap. Lesson 3 raises the risk level by crossing file and network boundaries for JSON integration and export.

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 path expander — Path-expansion procedures and control dimensions.
• APOC expandConfig — Detailed bounded path expansion configuration.