Use GDS utility functions

You’ve already been using it

Look back at queries you’ve run in previous lessons. You’ve seen this pattern repeatedly:

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

That gds.util.asNode(nodeId).name is converting an internal node identifier into an actual node so you can access its properties.

Why do we need this?

Remember back in module 2, you saw this image:

In this image, we can see generic nodes connected by generic relationships. However, it doesn’t tell the whole story.

A more accurate image might look something like this:

If we zoom in on just two of those nodes, we’ll see that they are not labeled as Node at all. Instead, they have specific id numbers, assigned by GDS.

These GDS nodeIds connect directly back to their elementIds in the main graph. So, we could instead think of them as looking like this.

By default, when you project into GDS, the shorter nodeId is what GDS will see. The nodeId is how it can identify specific nodes within a bank of generic ones.

You can rest assured that these nodes are indeed 'Kevin Bacon' and 'Ryan Reynolds'. However, you can’t see either actor’s name, a movie’s title, or any other property just from the ID.

The problem: Algorithm results give you nodeId, but you need node properties like name, title, or revenue when streaming results.

The solution: gds.util.asNode() translates the internal ID back into the actual database elementId, allowing you to access its properties from the main graph.

How it works

Let’s see this in action.

First, run PageRank on the actor network without converting node IDs:

CALL gds.pageRank.stream('actor-network', {})
YIELD nodeId, score
RETURN nodeId, score
ORDER BY score DESC
LIMIT 5

You’ll see results like:

The nodeId is just a number. It doesn’t tell you which actor it represents.

Now use gds.util.asNode() to connect to the actual node as it exists in the main graph:

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

Now you should see something along the lines of:

What happened?

Extracting multiple properties

You can access any property of the node once you’ve converted it.

The following example first runs the algorithm, then assigns a variable to the nodes: actor.

Then, we simply access the full node, actor, as many times as we like to get its properties.

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

This returns:

Pattern: Use WITH to convert the nodeId once, then access multiple properties from the node.

Extract community information

Run Louvain community detection and extract both the actor name and the community they belong to.

Fill in the blanks to return:

CALL gds.louvain.stream('actor-network', {})
YIELD nodeId, communityId
RETURN ????, ????
ORDER BY communityId DESC
LIMIT 10

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

Group community members

Now let’s get more advanced. For each community, collect the names of its members.

CALL gds.louvain.stream('actor-network', {})
YIELD nodeId, communityId
WITH gds.util.asNode(nodeId) AS actor, communityId
RETURN communityId,
       collect(????) AS members,
       count(*) AS size
ORDER BY size DESC
LIMIT 5

Fill in the blank to collect actor names for each community.

CALL gds.louvain.stream('actor-network', {})
YIELD nodeId, communityId
WITH gds.util.asNode(nodeId) AS actor, communityId
RETURN communityId,
       collect(actor.name) AS members,
       count(*) AS size
ORDER BY size DESC
LIMIT 5

Other utility functions

GDS provides other utility functions you might encounter:

gds.util.nodeProperty(): Get a specific property without converting the full node:

RETURN gds.util.nodeProperty('actor-network', nodeId, 'name')

This is more efficient if you only need one property, but less flexible than asNode().

gds.util.asNodes(): Convert multiple node IDs at once:

RETURN gds.util.asNodes([nodeId1, nodeId2, nodeId3])

Useful when working with lists of node IDs (like from pathfinding algorithms).

When to use gds.util.asNode()

Always use it when:

You don’t need it when:

What’s next

You now understand how to convert internal node IDs into actual database nodes using gds.util.asNode(). This is essential for making streamed algorithm results readable and useful.

In the next lesson, you’ll learn how to read the GDS documentation to understand algorithm requirements, configurations, and capabilities.