Understand the five execution modes

Five ways to run algorithms

Every GDS algorithm supports five execution modes. Each serves a different purpose in your workflow:

Let’s explore each one.

Stats: Get Summary Statistics

The stats mode runs the algorithm and returns summary statistics without individual node results. This is perfect when you want to understand the overall algorithm outcome without viewing every single result.

Let’s run Louvain in stats mode on the actor collaboration network — without any YIELD or RETURN:

CALL gds.louvain.stats('actor-network', {})

As with other GDS operations, when we run this without a YIELD or RETURN, we get a full read-out of all outputs.

The output shows:

This tells you about the algorithm’s execution and the distribution of results without returning thousands of individual rows.

Statistics from community detection algorithms are particularly important to pay attention to. Later, you’ll learn to update algorithm configurations for yourself.

In its default configuration, Louvain aggregates nodes into new, higher-level communities up to ten times.

Check the ranLevels column from the previous output. You should see that it ran only 4 out of those possible 10. You should also notice that it identified around 1020 distinct communities.

The version below contains only a small tweak: maxLevels set to 3. This means that it will stop after creating 3 hierarchies.

Run the tweaked version below, and take note of the number of communities found.

CALL gds.louvain.stats('actor-network', {
  maxLevels: 3
})

This time, your community count should be in a slightly different range to the previous run. This happens because we stopped the algorithm before it converged. In other words, we stopped it from combining too many small groups into one larger one.

The point here is not to remember configuration settings — you’ll learn that later. Instead, you should see the value of testing those configurations with the stats operator before committing to fully running an algorithm.

Use stats when you want to:

CALL gds.degree.?????('actor-network', {})
YIELD centralityDistribution
RETURN centralityDistribution.min AS minDegree,
  centralityDistribution.max AS maxDegree,
  centralityDistribution.mean AS avgDegree

CALL gds.degree.stats('actor-network', {})
YIELD centralityDistribution
RETURN centralityDistribution.min AS minDegree,
  centralityDistribution.max AS maxDegree,
  centralityDistribution.mean AS avgDegree

Stream: View results without commitment

The stream mode returns algorithm results directly in your query output. Results aren’t stored anywhere—they exist only for the duration of your query.

This is perfect for exploration. You run the algorithm, see the results, and decide what to do next.

Let’s stream PageRank results for the actor collaboration network:

CALL gds.pageRank.stream('actor-network', {})
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS actorName, score
ORDER BY score DESC
LIMIT 10

The output shows each actor’s PageRank score. Higher scores mean the actor is more "important" in the collaboration network—they’re connected to other well-connected actors.

Notice the pattern: gds.<algorithm>.stream() returns results you can immediately use in your query with RETURN, WHERE, or other Cypher clauses.

Use stream when you want to:

CALL gds.degree.?????(?????, {})
YIELD ?????, score
RETURN gds.util.asNode(?????).name AS actorName, score
ORDER BY score DESC
LIMIT 10

CALL gds.degree.stream('actor-network', {})
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS actorName, score
ORDER BY score DESC
LIMIT 10

Mutate: Store in the projection

The mutate mode stores algorithm results as properties in your projection—not in your Neo4j database.

When you mutate, the results stay in the in-memory graph. You can then run another algorithm that uses those results as input, or write them back to the main graph when ready.

Let’s add PageRank scores to our projection:

CALL gds.pageRank.mutate('actor-network', {
  mutateProperty: 'pageRankScore'
})
YIELD nodePropertiesWritten, mutateMillis
RETURN nodePropertiesWritten, mutateMillis

The output tells you:

Now every node in your actor-network projection has a pageRankScore property. Other algorithms can use this property, but it doesn’t exist in your database—only in the projection.

Use mutate when you want to:

CALL gds.degree.?????(?????, {
  mutateProperty: '?????'
})
YIELD nodePropertiesWritten
RETURN nodePropertiesWritten

CALL gds.degree.mutate('actor-network', {
  mutateProperty: 'degreeScore'
})
YIELD nodePropertiesWritten
RETURN nodePropertiesWritten

Write: Persist outputs to your database

The write mode stores algorithm results as properties in your Neo4j database. This makes results available to applications, visualizations, and future queries, even after you drop the projection.

Let’s write PageRank scores to the database:

CALL gds.pageRank.write('actor-network', {
  writeProperty: 'pageRank'
})
YIELD nodePropertiesWritten, writeMillis
RETURN nodePropertiesWritten, writeMillis

The output shows:

Now you can query those properties directly from your database:

MATCH (a:Actor)
WHERE a.pageRank IS NOT NULL
RETURN a.name, a.pageRank
ORDER BY a.pageRank DESC
LIMIT 10

These PageRank scores now exist in your database as node properties. They’ll remain even after you drop the graph projection.

Use write when you want to:

CALL gds.degree.?????(?????, {
  ?????: 'collaborationCount'
})
YIELD nodePropertiesWritten
RETURN nodePropertiesWritten

CALL gds.degree.write('actor-network', {
  writeProperty: 'collaborationCount'
})
YIELD nodePropertiesWritten
RETURN nodePropertiesWritten

MATCH (a:Actor)
WHERE a.collaborationCount IS NOT NULL
RETURN a.name, a.collaborationCount
ORDER BY a.collaborationCount DESC
LIMIT 10

Estimate: Check Memory Requirements

The estimate mode tells you how much memory an algorithm will need without actually running it. This is the last mode to understand because it helps you plan before executing any of the other four modes.

Before running an expensive algorithm on a large graph, you’ll want to know if you have enough heap memory. The estimate mode answers that question.

Every execution mode has an estimate variant. Here’s how to estimate memory for a write operation:

CALL gds.pageRank.write.estimate('actor-network', {
  writeProperty: 'pageRank'
})
YIELD nodeCount, relationshipCount, requiredMemory
RETURN nodeCount, relationshipCount, requiredMemory

The output shows how many nodes and relationships will be processed, and how much memory the operation requires.

GDS operates entirely in heap memory. For large graphs or complex algorithms, you may need to increase your heap size.

To check or modify heap settings, open your neo4j.conf file:

Default Neo4j settings are sufficient for all datasets in this course. However, in later courses, using larger datasets, you will learn how to update your config.

Note: It is unwise to edit your neo4j.conf without fully understanding how or why.

You can estimate any execution mode:

CALL gds.pageRank.stream.estimate('actor-network', {})
YIELD requiredMemory
RETURN requiredMemory

This shows the memory needed to run PageRank in stream mode.

For this graph of 10k nodes, the required memory is trivial. In fact, you would be surprised just how large a graph must be to require an adjustment to the neo4j.conf.

Use estimate when you want to:

CALL gds.degree.?????.?????('actor-network', {
  writeProperty: 'collaborationCount'
})
YIELD ?????
RETURN ?????

CALL gds.degree.write.estimate('actor-network', {
  writeProperty: 'collaborationCount'
})
YIELD requiredMemory
RETURN requiredMemory

Choosing the Right Mode

Now that you’ve practiced all five modes, here’s how to decide which one to use:

Stats when you want to understand the overall distribution and behavior of algorithm results without viewing individual node scores.

Stream when you’re exploring data, running quick analyses, exporting results to csv or dataframe via the Python driver.

Mutate when you’re chaining algorithms or developing a machine learning pipeline and don’t want to retain results in the main graph.

Write when you need to persist results for applications, dashboards, or future queries, and you want them available even after dropping projections.

Estimate when you’re planning your workflow and need to check memory requirements before running expensive operations.

A typical workflow might use all five:

What’s Next

You’ve practiced all five execution modes and understand when to use each one.

In the next lesson, you’ll learn about GDS utility functions that help you work with algorithm results, specifically how to extract node properties from streamed results.