stream, stats, mutate, write, and estimate Modes: Separating Exploration from Persistent Changes

Learning outcomes

1. Execution mode is a data-governance decision

AtlasMart has accumulated enough connected customer/product behavior that analysts want graph algorithms, but running “an algorithm” is not one operation. The analytical graph must first be selected, copied into a GDS representation, sized, verified, executed, and removed or refreshed deliberately. AtlasMart analysts need to explore centrality, chain algorithms, and eventually publish one feature. If every experiment writes properties to Product/Customer nodes, the operational graph becomes an accidental scratchpad.

The safety rule for this chapter is therefore: treat projection definition, memory allocation, algorithm mode, and lifecycle as part of the analytical result. A score without those inputs is not reproducible evidence.

2. Five modes, five state boundaries

3. Prepare and estimate before running

CYPHER 25
// Chapter 23 fixture: bounded and safe to delete by labTag.
CREATE CONSTRAINT ch23_customer_id IF NOT EXISTS
FOR (c:Customer) REQUIRE c.customerId IS UNIQUE;
CREATE CONSTRAINT ch23_product_id IF NOT EXISTS
FOR (p:Product) REQUIRE p.productId IS UNIQUE;

UNWIND [
 {id:'C-2301',segment:'LOYAL',value:92.0},
 {id:'C-2302',segment:'LOYAL',value:78.0},
 {id:'C-2303',segment:'NEW',value:35.0},
 {id:'C-2304',segment:'NEW',value:28.0},
 {id:'C-2305',segment:'B2B',value:96.0},
 {id:'C-2306',segment:'B2B',value:84.0}
] AS row
MERGE (c:Customer {customerId:row.id})
SET c.segment=row.segment,c.customerValue=row.value,c.labTag='ch23';

UNWIND [
 {id:'P-2301',name:'Trail Camera Pro',margin:0.31},
 {id:'P-2302',name:'Action Camera 4K',margin:0.27},
 {id:'P-2303',name:'Solar Trail Charger',margin:0.24},
 {id:'P-2304',name:'Indoor Security Camera',margin:0.29},
 {id:'P-2305',name:'Hydration Vest',margin:0.22},
 {id:'P-2306',name:'Wildlife Field Guide',margin:0.35}
] AS row
MERGE (p:Product {productId:row.id})
SET p.name=row.name,p.margin=row.margin,p.labTag='ch23';

MATCH (c:Customer {labTag:'ch23'}),(p:Product {labTag:'ch23'})
WITH c,p WHERE
 (c.customerId='C-2301' AND p.productId IN ['P-2301','P-2303','P-2306']) OR
 (c.customerId='C-2302' AND p.productId IN ['P-2301','P-2302']) OR
 (c.customerId='C-2303' AND p.productId IN ['P-2302','P-2305']) OR
 (c.customerId='C-2304' AND p.productId IN ['P-2304','P-2305']) OR
 (c.customerId='C-2305' AND p.productId IN ['P-2301','P-2303','P-2304']) OR
 (c.customerId='C-2306' AND p.productId IN ['P-2303','P-2306'])
MERGE (c)-[r:VIEWED]->(p)
SET r.weight = CASE c.segment WHEN 'LOYAL' THEN 2.0 WHEN 'B2B' THEN 1.5 ELSE 1.0 END,
    r.labTag='ch23';

MATCH (c:Customer {labTag:'ch23'}),(p:Product {labTag:'ch23'})
WHERE (c.customerId='C-2301' AND p.productId='P-2301') OR
      (c.customerId='C-2302' AND p.productId='P-2302') OR
      (c.customerId='C-2305' AND p.productId='P-2303') OR
      (c.customerId='C-2306' AND p.productId='P-2306')
MERGE (c)-[r:PURCHASED]->(p)
SET r.weight=3.0,r.labTag='ch23';


CALL gds.graph.exists('atlasmart-ch23') YIELD exists
WITH exists WHERE exists
CALL gds.graph.drop('atlasmart-ch23') YIELD graphName
RETURN graphName;


CALL gds.graph.project(
  'atlasmart-ch23',
  {
    Customer:{properties:['customerValue']},
    Product:{properties:['margin']}
  },
  {
    VIEWED:{orientation:'NATURAL',properties:['weight']},
    PURCHASED:{orientation:'NATURAL',properties:['weight']}
  },
  {readConcurrency:2}
)
YIELD graphName,nodeCount,relationshipCount,projectMillis,configuration
RETURN graphName,nodeCount,relationshipCount,projectMillis,configuration;
// Expected deterministic counts: nodeCount=12, relationshipCount=18.

CALL gds.pageRank.stream.estimate('atlasmart-ch23', {
  relationshipTypes:['VIEWED','PURCHASED'],
  relationshipWeightProperty:'weight',
  concurrency:2,
  maxIterations:20,
  dampingFactor:0.85
})
YIELD nodeCount,relationshipCount,requiredMemory,bytesMin,bytesMax,heapPercentageMin,heapPercentageMax
RETURN *;

PageRank is used here because it exposes all teaching modes. Chapter 24 will teach what centrality means and when it is appropriate. In this chapter, the score is just a result payload whose state boundary must be controlled.

4. stream: inspect individual results without changing graph state

CALL gds.pageRank.stream('atlasmart-ch23', {
  relationshipTypes:['VIEWED','PURCHASED'],
  relationshipWeightProperty:'weight',
  concurrency:2,
  maxIterations:20,
  dampingFactor:0.85
})
YIELD nodeId,score
RETURN gds.util.asNode(nodeId).productId AS productId,
       gds.util.asNode(nodeId).customerId AS customerId,
       score
ORDER BY score DESC LIMIT 8;
// stream returns rows; it does not alter graph catalog properties or Neo4j properties.

Stream is ideal for exploration, evaluation, external post-processing, or a service response when result cardinality is bounded. Large streams can themselves create network/client-memory pressure, so use top-N/filtering/consumer backpressure where appropriate.

5. stats: prove behavior without moving all scores

CALL gds.pageRank.stats('atlasmart-ch23', {
  relationshipTypes:['VIEWED','PURCHASED'],
  relationshipWeightProperty:'weight',
  concurrency:2,
  maxIterations:20
})
YIELD ranIterations,didConverge,centralityDistribution,computeMillis
RETURN *;
// stats returns summary evidence without exposing per-node scores or writing state.

Stats mode answers “what happened during the computation?” with summary evidence such as convergence/distribution/timing. It does not give per-node scores and does not write them anywhere.

6. mutate: chain analytics inside the catalog

CALL gds.pageRank.mutate('atlasmart-ch23', {
  relationshipTypes:['VIEWED','PURCHASED'],
  relationshipWeightProperty:'weight',
  mutateProperty:'ch23PageRank',
  concurrency:2,
  maxIterations:20
})
YIELD nodePropertiesWritten,mutateMillis,ranIterations,didConverge
RETURN *;

CALL gds.graph.nodeProperty.stream('atlasmart-ch23','ch23PageRank')
YIELD nodeId,propertyValue
RETURN gds.util.asNode(nodeId).productId AS productId,
       gds.util.asNode(nodeId).customerId AS customerId,
       propertyValue
ORDER BY propertyValue DESC LIMIT 8;
// ch23PageRank exists only in the in-memory projected graph after mutate.

CYPHER 25
MATCH (n {labTag:'ch23'})
RETURN count(n) AS sourceNodes,
       count(n.ch23PageRank) AS persistedPageRankProperties;
// Expected persistedPageRankProperties=0 immediately after mutate.

Mutate is powerful because a later GDS algorithm can consume the new in-memory property without round-tripping through the database. It is also ephemeral: dropping the graph or stopping the source database/DBMS removes that analytical state.

7. write: persist intentionally, then verify

CALL gds.pageRank.write('atlasmart-ch23', {
  relationshipTypes:['VIEWED','PURCHASED'],
  relationshipWeightProperty:'weight',
  writeProperty:'ch23PageRankWritten',
  concurrency:2,
  maxIterations:20
})
YIELD nodePropertiesWritten,writeMillis,ranIterations,didConverge
RETURN *;

MATCH (n {labTag:'ch23'})
RETURN labels(n) AS labels,count(n.ch23PageRankWritten) AS persisted
ORDER BY labels;
// write changes Neo4j; cleanup must remove this lab property.

8. Deliberately wrong: confuse mutate with durable feature engineering

Concrete problem: mutate wrote only the named in-memory graph. After projection/DBMS loss the property is gone, and ordinary Cypher never had a persisted rank property. Repair: decide whether the feature is temporary (mutate/stream) or governed durable data (write/export + controlled transaction), then verify the correct storage layer.

9. Mode selection under production constraints

Production judgment and bridge

Lesson 5 assembles these pieces into one auditable runbook: verify compatible plugin, seed source, estimate, project, inspect, run least-persistent modes, measure, prove state boundaries, and clean up.

Summary and next step

stream, stats, mutate, write, and estimate Modes: Separating Exploration from Persistent Changes is useful only when its assumptions and observed evidence stay attached to the decision. The examples above establish a reproducible mechanism and boundary; they do not turn one lab result into a universal production rule.

Next, continue to Build, Validate, Use, and Drop a GDS Projection with Reproducible Resource Measurements. Carry forward the verified assumptions, fixture state, version/edition boundaries, and measurements from this lesson instead of treating the next topic as an isolated recipe.

Authoritative references

• GDS Manual v2026.07 — Current Graph Data Science manual and versioned feature baseline.
• GDS 2026.07 release notes — Current GDS release line; 2026.07.0 is compatible with Neo4j 2026.07.
• Supported Neo4j versions — Compatibility matrix between Neo4j Database and GDS.
• GDS editions and graph catalog — Community/Enterprise boundaries, graph catalog model, all-algorithms availability, concurrency and model-catalog limits.
• Neo4j Server GDS installation — Bundled products-to-plugins installation path and required GDS procedure security configuration.
• GDS on Docker — Container-based installation examples and plugin activation.
• System requirements — Heap/native-memory/CPU guidance and Community maximum concurrency of four.
• Native projection — Current gds.graph.project procedure, label/type/property/orientation configuration and lifecycle.
• Cypher projection — Current gds.graph.project aggregation-function projection from Cypher query context.
• Legacy Cypher projection — deprecated — Deprecated gds.graph.project.cypher procedure and migration boundary.
• Graph creation and schema — Supported projection types, relationship direction, properties, parallel relationships, and algorithm traits.
• Graph catalog operations — Current graph project/list/exists/drop and graph-property operations.
• Listing graphs — Graph metadata, schemaWithOrientation, degree distribution and configuration inspection.
• Memory estimation — Projection and algorithm estimate syntax, requiredMemory and byte-range evidence.
• Algorithm syntax and execution modes — stream/stats/mutate/write/estimate semantics.
• Running algorithms — Operational meaning and tradeoffs of algorithm execution modes.
• PageRank — Production-tier algorithm used only to demonstrate execution modes and memory estimates in this foundations chapter.
• Neo4j current versions — Current Neo4j Database release and 5.26 LTS line.