Aura Graph Analytics Serverless

Aura Graph Analytics Serverless is currently in Early Access and not available by default. Contact your account manager to get the feature enabled.

Aura Graph Analytics Serverless is an on-demand ephemeral compute environment for running GDS workloads. Each compute unit is called a GDS Session. It is offered as part of Neo4j Aura, a fast, scalable, always-on, fully automated cloud graph platform.

A GDS Session reads data from one of three categories of data sources:

Neo4j AuraDB
Self-managed Neo4j DBMS
A non-Neo4j data source

We call the process of populating the session with data a remote projection. Once populated, a GDS Session can run GDS workloads, such as algorithms and machine learning models. The results from these computations can be written back to the original source, using remote write-back in the case of a Neo4j data source (Aura or self-managed).

Primary API surfaces

GDS Sessions do not require any installation to a Neo4j DBMS. Instead, a GDS Session is started on-demand to perform GDS computations. There are two primary APIs for working with GDS Sessions: the GDS Python Client and the GDS Session Cypher API.

GDS Python Client

Using the client, it is possible to perform all operations on a GDS Session. For a comprehensive API overview including examples and tutorials, see the GDS Python Client manual.

In particular, the GDS Python Client allows you to:

A good place to start are the Tutorials:

GDS Session Cypher API

This manual covers all aspects of the GDS Session Cypher API. The Cypher API supports remote projections, calling algorithms and machine learning operations, and remote write back to the AuraDB instance. It is currently offered only for AuraDB and is used from within a Cypher query context, such as Query in the Aura Console. This means that the session is created automatically when a remote graph projection runs, and deleted automatically when the graph is dropped.

In the following sections we will focus only on the GDS Session Cypher API, assuming that it is used from an AuraDB instance.

Session lifecycle and configuration

In the Cypher API, sessions are managed implicitly. That means that there is no operation to create or delete a session. Instead, a session is created when a remote projection is run, and deleted when the graph is dropped. Sessions cannot be listed directly, but graphs can be listed using gds.graph.list().

Session size

When the graph projection is requested, a mandatory memory parameter must be specified, indicating the size of the session. The size of the session is the maximum amount of memory allocated to the analytical process. A larger size means faster runtime and an ability to process larger volumes of data, but it will also be more expensive.

Supported values are: 4GB, 8GB, 16GB, 24GB, 32GB, 48GB, 64GB, 96GB, 128GB, 192GB, 256GB, 384GB, and 512GB.

Session maximum size can be configured for your Aura organization. Check with your organization administrator what your maximum size is.

AuraDB source instance limitations

The GDS Session Cypher API is available only for AuraDB instances in the Business Critical or Virtual Dedicated Cloud plans. Depending on which plan is used, different limitations apply. See Graph analytics in Aura for a comparison view.

Session expiration and deletion

When the graph projection is requested, an optional ttl parameter can be configured, which specifies how quickly an inactive session will expire. The default value for ttl is 1 hour and the maximum allowed value is 7 days. An expired session cannot be used to run workloads, does not cost anything, and will be deleted automatically after 7 days. It can also be deleted through the Aura Console UI.

Syntax

The GDS Session Cypher API matches the GDS plugin API as closely as possible. Thus, most of the content in this manual applies to both products. In general, expect to be able to use all query examples in this manual with the GDS Session Cypher API, subject to the limitations described in this section.

Authentication to Aura API

One key difference is the requirement for the GDS Session Cypher API to authenticate to the Aura API. This is done by calling the gds.aura.api.credentials() function in each Cypher query. An easy way to do that is to use a leading WITH clause in all queries.

The function does not return any value, but registers the credentials in the query context of that query. The credentials are not persisted anywhere and will be immediately forgotten after the Cypher query has completed.

Due to this requirement, short-form CALL-only queries cannot be used. See the Cypher manual for additional details.

Calling an algorithm with only a CALL clause:

CALL gds.wcc.stream('g')

The above will fail with an error indicating the missing call to gds.aura.api.credentials().

Examples

Projecting a graph to a GDS Session:

// you can use any alias
WITH gds.aura.api.credentials() AS credentials
MATCH (n)
OPTIONAL MATCH (n)-->(m)
RETURN gds.graph.project('g', n, m, {}, {memory: '4GB'})

Calling an algorithm in stream mode:

// you can use any alias
WITH gds.aura.api.credentials() AS c
CALL gds.pageRank.stream('g')
YIELD nodeId, score // must specify YIELD
RETURN *

Projecting a graph

Use a Cypher projection to project a graph into a GDS Session. Make sure to include all the additional parameters with the Aura Graph Analytics Serverless label.

Native projections and legacy Cypher projections are not supported.

Running algorithms

The GDS Session Cypher API supports most algorithms and machine learning operations in all existing execution modes. The syntax is the same as for the GDS plugin, but with the additional WITH gds.aura.api.credentials() AS credentials clause.

Unsupported algorithms

Not all algorithms have been implemented in the GDS Session Cypher API. The following algorithms are not supported:

API limitations

The GDS Session Cypher API does not support all procedures and functions available in the GDS plugin. Some that are mentioned here may be supported in the future, while others may never be supported.

Graph Catalog

The following Graph Catalog procedures are not supported in GDS Session Cypher API:

gds.graph.project
gds.graph.project.estimate
gds.graph.project.cypher
gds.graph.project.cypher.estimate
gds.graph.export
gds.graph.export.csv
gds.graph.export.csv.estimate
gds.backup
gds.restore
gds.graph.graphProperty.drop
gds.graph.graphProperty.stream

Machine Learning

Trained models can only be used for prediction using the same session in which they were trained. After the session is deleted, all trained models will be lost.

The following Machine Learning procedures are not supported in GDS Session Cypher API:

gds.model.publish
gds.model.store
gds.model.load
gds.model.delete
gds.alpha.linkprediction.adamicAdar
gds.alpha.linkprediction.commonNeighbors
gds.alpha.linkprediction.preferentialAttachment
gds.alpha.linkprediction.resourceAllocation
gds.alpha.linkprediction.sameCommunity
gds.alpha.linkprediction.totalNeighbors
gds.alpha.ml.splitRelationships

Additionally, all pipeline procedures are unsupported.

Additional Operations

The following Additional Operations are not supported in GDS Session Cypher API:

gds.license.state
gds.debug.arrow
gds.debug.sysInfo
gds.license.state
gds.userLog
gds.version

Examples

In this section we will illustrate how to use the GDS Session Cypher API to project a graph, run a few algorithms, and process results.

The following Cypher statement will create the example graph in the Neo4j database:

CREATE
  (a:User {name: 'Alice', age: 23}),
  (b:User {name: 'Bridget', age: 34}),
  (c:User {name: 'Charles', age: 45}),
  (d:User {name: 'Dana', age: 56}),
  (e:User {name: 'Eve', age: 67}),
  (f:User {name: 'Fawad', age: 78}),

  (a)-[:LINK {weight: 0.5}]->(b),
  (b)-[:LINK {weight: 0.2}]->(a),
  (a)-[:LINK {weight: 4}]->(c),
  (c)-[:LINK {weight: 2}]->(e),
  (e)-[:LINK {weight: 1.1}]->(d),
  (e)-[:LINK {weight: -2}]->(f);

First, project the graph into a GDS Session, using a remote Cypher projection. Specify the memory and ttl parameters.

Projecting a graph called 'myGraph' using a remote Cypher projection into a new GDS Session:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
MATCH (source:User)
OPTIONAL MATCH (source)-[r:LINK]->(target:User)
WITH gds.graph.project('myGraph', source, target, {
  sourceNodeProperties: source { .age },
  targetNodeProperties: target { .age },
  relationshipProperties: r { .weight }
}, {
  memory: '4GB', ttl: duration({minutes: 5})
}) AS g
RETURN g.graphName, g.nodeCount, g.relationshipCount

Table 1. Results
graphName	nodeCount	relationshipCount
'myGraph'	6	6

After this completes, we now have a GDS Session with a projected graph. If you have the Aura Console open, you should be able to see the session listed in the Sessions view. Next, list the projected graph using the gds.graph.list() procedure.

Listing the projected graph:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.graph.list()
YIELD graphName, nodeCount, relationshipCount
RETURN *

Table 2. Results
graphName	nodeCount	relationshipCount	credentials
'myGraph'	6	6	null

With a graph projected, we can now run algorithms. First, run PageRank and Fast Random Projection in mutate mode. Then, stream the node properties and lastly write them back to the AuraDB instance.

Run PageRank in mutate mode:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.pageRank.mutate('myGraph', { mutateProperty: 'pageRank' })
YIELD ranIterations, nodePropertiesWritten
RETURN *

Table 3. Results
ranIterations	nodePropertiesWritten	credentials
20	6	null

Use the mutated pageRank property as input to the FastRP algorithm.

Run FastRP in mutate mode:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.fastRP.mutate('myGraph', {
  featureProperties: ['pageRank'],
  relationshipWeightProperty: 'weight',
  iterationWeights: [1, 1, 1],
  randomSeed: 42,
  embeddingDimension: 8,
  mutateProperty: 'fastrp'
})
YIELD nodePropertiesWritten
RETURN *

Table 4. Results
nodePropertiesWritten	credentials
6	null

Now, stream the node properties back to the AuraDB instance.

Stream node properties:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.graph.nodeProperty.stream('myGraph', "fastrp")
YIELD nodeId, propertyValue
RETURN *

Table 5. Results
nodeId	propertyValue
0	[-0.6834304332733154, 0.0, 0.0, 1.190035343170166, 1.2754640579223633, 0.08542880415916443, 1.3372166156768799, -0.08542880415916443]
1	[-0.6575959920883179, 0.0, 0.0, 0.6249072551727295, 0.7071067690849304, 0.08219949901103973, 0.739795446395874, -0.08219949901103973]
2	[0.0, 0.0, 0.0, 1.2844570875167847, 1.2844570875167847, 0.0, 0.5773503184318542, 0.0]
3	[0, 0, 0, 0, 0, 0, 0, 0]
4	[0.0, 0.0, 0.0, 0.5773503184318542, 0.5773503184318542, 0.0, 0.5773503184318542, 0.0]
5	[0, 0, 0, 0, 0, 0, 0, 0]

It is also possible to write the results using the gds.graph.nodeProperty.write() procedure. Another alternative is to write results directly using the write algorithm execution mode:

Run Louvain in write mode:

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.louvain.write('myGraph', { writeProperty: 'louvain' })
YIELD communityCount, modularity
RETURN communityCount, modularity

Table 6. Results
communityCount	modularity
2	0.3333333333333333

Now we can find our results in the AuraDB instance using standard Cypher queries. Finally, drop the projected graph, which will also delete the GDS Session.

Drop the graph 'myGraph':

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.graph.drop('myGraph')
YIELD graphName
RETURN graphName

Table 7. Results
graphName
'myGraph'

After this completes, no more costs are incurred for the GDS Session. You will find that the session is no longer visible in the Aura Console. If you forget to drop the graph, the session will automatically expire after the configured ttl time has passed.