Utility functions

This section provides explanations and examples for each of the utility functions in the Neo4j Graph Data Science library.

1. System Functions

Name Description

gds.version

Return the version of the installed Neo4j Graph Data Science library.
Usage:
RETURN gds.version() AS version
Table 1. Results
version

"1.5.2"

2. Numeric Functions

Table 2. Numeric Functions
Name Description

gds.util.NaN

Returns NaN as a Cypher value.

gds.util.infinity

Return infinity as a Cypher value.

gds.util.isFinite

Return true iff the given argument is a finite value (not ±Infinity, NaN, or null).

gds.util.isInfinite

Return true iff the given argument is not a finite value (not ±Infinity, NaN, or null).

2.1. Syntax

Name Parameter

gds.util.NaN()

-

gds.util.infinity()

-

gds.util.isFinite(value: NUMBER)

value to be checked if it is finite

gds.util.isInfinite(value: NUMBER)

value to be checked if it is infinite.

2.2. Examples

Example for gds.util.IsFinite:
UNWIND [1.0, gds.util.NaN(), gds.util.infinity()] AS value
RETURN gds.util.isFinite(value) AS isFinite
Table 3. Results
isFinite

true

false

false
Example for gds.util.isInfinite():
UNWIND [1.0, gds.util.NaN(), gds.util.infinity()] AS value
RETURN gds.util.isInfinite(value) AS isInfinite
Table 4. Results
isInfinite

false

true

true

The utility function gds.util.NaN can be used as an default value for input parameters, as shown in the examples of cosine similarity. A common usage of gds.util.IsFinite and gds.util.IsInfinite is for filtering streamed results, as for instance seen in the examples of gds.alpha.allShortestPaths.

3. Node and Path Functions

Table 5. Node and Path Functions
Name Description

gds.util.asNode

Return the node object for the given node id or null if none exists.

gds.util.asNodes

Return the node objects for the given node ids or an empty list if none exists.

3.1. Syntax

Name Parameters

gds.util.asNode(nodeId: NUMBER)

nodeId of a node in the neo4j-graph

gds.util.asNodes(nodeIds: NUMBER[])

list of nodeIds of nodes in the neo4j-graph

3.2. Examples

Consider the graph created by the following Cypher statement:

Example graph:
CREATE  (nAlice:User {name: 'Alice'})
CREATE  (nBridget:User {name: 'Bridget'})
CREATE  (nCharles:User {name: 'Charles'})
CREATE  (nAlice)-[:LINK]->(nBridget)
CREATE  (nBridget)-[:LINK]->(nCharles)
Example for gds.util.asNode:
MATCH (u:User{name: 'Alice'})
WITH id(u) AS nodeId
RETURN gds.util.asNode(nodeId).name AS node
Table 6. Results
node

"Alice"
Example for gds.util.asNodes:
MATCH (u:User)
WHERE NOT u.name = 'Charles'
WITH collect(id(u)) AS nodeIds
RETURN [x in gds.util.asNodes(nodeIds)| x.name] AS nodes
Table 7. Results
nodes

[Alice, Bridget]

As many algorithms streaming mode only return the node id, gds.util.asNode and gds.util.asNodes can be used to retrieve the whole node from the neo4j database.

4. Catalog Functions

Catalog functions allow accessing in-memory graphs directly from a Cypher query.

Table 8. Catalog Functions
Name Description

gds.util.nodeProperty

Allows accessing a node property stored in a named graph.

4.1. Syntax

Name Description

gds.util.nodeProperty(graphName: STRING, nodeId: INTEGER, propertyKey: STRING, nodeLabel: STRING?)

Named graph in the catalog, Neo4j node id, node property key and optional node label present in the named-graph.

If a node label is given, the property value for the corresponding projection and the given node is returned. If no label or '*' is given, the property value is retrieved and returned from an arbitrary projection that contains the given propertyKey. If the property value is missing for the given node, null is returned.

4.2. Examples

Create a graph in the catalog:
CALL gds.graph.create('my-graph', 'User', 'LINK');
Run an algorithm that updates the named-graph:
CALL gds.pageRank.mutate('my-graph', { mutateProperty: 'score' })

We can now access the property score without writing the data to Neo4j.

Access a property node property for Alice:
MATCH (alice:User)
WHERE alice.name = 'Alice'
RETURN
  alice.name AS name,
  gds.util.nodeProperty('my-graph', id(alice), 'score') AS score
Table 9. Results
name score

"Alice"

0.15000000000000002

We can also specifically return the score property from the User projection in case other projections also have a score property as follows.

Access a property node property from User for Alice:
MATCH (alice:User)
WHERE alice.name = 'Alice'
RETURN
  alice.name AS name,
  gds.util.nodeProperty('my-graph', id(alice), 'score', 'User') AS score
Table 10. Results
name score

"Alice"

0.15000000000000002