Cypher API

The Cypher API for Aura Graph Analytics matches the GDS plugin API as closely as possible. Except for some limitations, you can adapt most of the examples from the rest of the documentation.

Authentication to the Aura API

One key difference with the GDS plugin is the requirement to authenticate to the Aura API using the gds.aura.api.credentials() function in each Cypher query.

Use of gds.aura.api.credentials

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials (1)
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { memory: '4GB' }
)

1	You can use any alias, provided that you specify one.

The function does not return any value, but registers the credentials in the query context. The credentials are not persisted anywhere and are immediately discarded after the query has completed.

Once you have created a graph within a session, a query like the following will fail with an error indicating the missing call to gds.aura.api.credentials().

Call an algorithm procedure without Aura API credentials

CALL gds.wcc.stream('g') // This alone will not work

Syntax

RETURN gds.aura.api.credentials(
  clientId: String,
  clientSecret: String
) AS credentials

Table 1. Configuration
Name	Type	Default	Optional	Description
clientId	String	`n/a`	no	The Client ID for an Aura API key pair.
clientSecret	String	`n/a`	no	The Client Secret for an Aura API key pair.

Table 2. Results
Name	Type	Description
-	-	Always returns `null`.

Projecting a graph

Native projections and legacy Cypher projections are not supported in Aura Graph Analytics.

Use a Cypher projection with the additional authentication clause to project a graph into a GDS Session.

Make sure to include the additional parameters with the Aura Graph Analytics label to create a session at the same time.

Project a graph into a new GDS Session

CYPHER runtime=parallel (1)
WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { memory: '4GB' } (2)
)

1	The Cypher `parallel` runtime is recommended but not mandatory.
2	Map containing session-related parameters such as `memory` (mandatory).

If you have created a session explicitly, add the session ID as the sessionId parameter to use that session instead.

Project a graph into an existing GDS Session

CYPHER runtime=parallel (1)
WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { sessionId: '00000000-11111111' }
)

1	The Cypher `parallel` runtime is recommended but not mandatory.

Running algorithms

See the Limitations section for the list of unsupported algorithms.

The Cypher API for Aura Graph Analytics supports most algorithms and machine learning operations in all existing execution modes. The syntax is the same as for the GDS plugin, with the additional authentication clause.

Call an algorithm procedure in stream mode

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.pageRank.stream('g')
YIELD nodeId, score (1)
RETURN *

1	Due to the authentication requirement, you must always add a `YIELD` clause. See the Cypher manual for additional details.

Session management

The session management procedures allow to explicitly create new sessions without any attached graphs, or to list and delete existing sessions.

Creating sessions

Calling the gds.session.getOrCreate procedure triggers the creation of a GDS Session based on the specified procedure parameters. If a session with the given name and configuration already exists, that session is returned instead.

Create an empty GDS Session

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.session.getOrCreate(
  'test-session',
  '4GB',
  duration({minutes: 30})
)
YIELD id AS sessionId, name AS sessionName
RETURN sessionId, sessionName

When you create a session explicitly with gds.session.getOrCreate, note down the sessionId and set it as a configuration parameter for the gds.graph.project procedure when you project a new graph.

Syntax

CALL gds.session.getOrCreate(
  sessionName: String,
  memory: String,
  ttl: Duration
  cloudLocation: Map
) YIELD
  id: String,
  name: String,
  auraInstanceId: String,
  memory: String,
  status: String,
  creationTime: Datetime,
  host: String,
  expiryDate: Datetime,
  ttl: TemporalAmount,
  errorMessage: String

Table 3. Parameters
Name	Type	Optional	Description
sessionName	String	no	The name of the GDS Session to create or return.
memory	String	no	The size of the GDS Session, e.g. `4GB`, `8GB`, etc.
ttl	Duration	yes	The time to live of the GDS Session when no activity is recorded, e.g. `duration({days: 1})`, `duration({hours: 12})`, etc. The default value is 1 hour.

Table 4. Results
Name	Type	Description
`id`	String	The unique identifier of the GDS Session.
`name`	String	The name of the GDS Session.
`auraInstanceId`	String	The Aura instance ID to which the GDS Session is attached to.
`memory`	String	The size of the GDS Session, e.g. `4GB`, `8GB`, etc.
`status`	String	The status of the GDS Session, e.g. `Creating`, `Ready`, `Expired`, etc.
`creationTime`	Datetime	The time when the GDS Session was created.
`host`	String	The public host address of the GDS Session.
`expiryDate`	Datetime	The time when the GDS Session will definitely expire.
`ttl`	TemporalAmount	The time that is left until the GDS Session expires due to inactivity.
`errorMessage`	String	The error message, if the GDS Session could not be created or is in an unhealthy state.

Listing sessions

The gds.session.list procedure returns all the GDS Sessions that are available to the current Aura user.

Syntax

CALL gds.session.list(
  projectId: String,
  filterAuraInstanceId: boolean
) YIELD
  id: String,
  name: String,
  auraInstanceId: String,
  memory: String,
  status: String,
  creationTime: Datetime,
  host: String,
  expiryDate: Datetime,
  ttl: TemporalAmount,
  errorMessage: String

Table 5. Parameters
Name	Type	Optional	Default	Description
projectId	String	yes	""	The ID of the project to which the GDS Sessions belong. If not specified, all sessions of the Aura user are returned.
filterAuraInstance	String	yes	false	If set to `true`, only sessions that are attached to current Aura instance are returned. If not specified, all sessions of the Aura user are returned.

Table 6. Results
Name	Type	Description
`id`	String	The unique identifier of the GDS Session.
`name`	String	The name of the GDS Session.
`auraInstanceId`	String	The Aura instance ID to which the GDS Session is attached to.
`memory`	String	The size of the GDS Session, e.g. `4GB`, `8GB`, etc.
`status`	String	The status of the GDS Session, e.g. `Creating`, `Ready`, `Expired`, etc.
`creationTime`	Datetime	The time when the GDS Session was created.
`host`	String	The public host address of the GDS Session.
`expiryDate`	Datetime	The time when the GDS Session will definitely expire.
`ttl`	TemporalAmount	The time that is left until the GDS Session expires due to inactivity.
`errorMessage`	String	The error message, if the GDS Session could not be created or is in an unhealthy state.

Deleting sessions

The gds.session.delete procedure deletes a GDS Session with the given ID. If the session is not found, an error is raised.

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials
CALL gds.session.delete(
  'test-session_00000000-1111-2222-3333-0123456789ab'
)
YIELD deleted
RETURN deleted

Syntax

CALL gds.session.delete(
  name: String,
  projectId: String
) YIELD
  deleted: boolean

Table 7. Parameters
Name	Type	Optional	Default	Description
name	String	no	n/a	The name of the GDS Session to delete.
projectId	String	yes	""	The ID of the project to which the GDS Session belongs. If similar sessions exist in different projects an error is thrown that indicates to provide a project ID.

Table 8. Results
Name	Type	Description
deleted	Boolean	True, if the GDS Session was successfully deleted, false otherwise.

Limitations

When compared to the GDS plugin, the Cypher API for Aura Graph Analytics has some limitations.

Algorithms

The following algorithms are not supported:

Other procedures and functions

The Cypher API for Aura Graph Analytics 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:

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:

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:

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