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.

You can now use the Cypher API inside an AuraDB without Aura API credentials.

Projecting a graph

Cypher projections

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)
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { memory: '2GB' } (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)
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.

Native projections

Aura Graph Analytics supports xref:management-ops/graph-creation/graph-project.adoc[native projections] with a limited feature set.

CALL gds.graph.project(
  graphName: String,
  nodeLabels: String or List,
  relationshipTypes: String or List,
  configuration: Map
) YIELD
  graphName: String,
  nodeProjection: Map,
  nodeCount: Integer,
  relationshipProjection: Map,
  relationshipCount: Integer,
  projectMillis: Integer

Table 1. Parameters
Name	Type	Optional	Description
graphName	String	no	The name under which the graph is stored in the catalog.
nodeLabels	String, List	no	One or more node labels to include in the projection. Can be `*` to project all nodes.
relationshipTypes	String, List	no	One or more relationship types to include in the projection. Can be `*` to project al relationships. Can be an empty list to project no relationships.
configuration	Map	no	Additional parameters to configure the native projection.

Table 2. Configuration
Name	Type	Default	Optional	Description
nodeProperties	String, List	{}	yes	The node properties to load from nodes that match any of the labels specified in `nodeLabels`.
relationshipProperties	String, List	{}	yes	The relationship properties to load from relationships that match any of the types specified in `relationshipTypes`.
undirectedRelationshipTypes	List	[]	yes	The relationship types that should be projected as undirected.
inverseIndexedRelationshipTypes	List	[]	yes	The relationship types for which an inverse index wil be generated.
readConcurrency	Integer	All available cores	yes	The number of concurrent threads used for creating the graph.
batchSize	Integer	16000	yes	The size of each batch of data send to the session.
jobId	String	Generated internally	yes	An ID that can be provided to more easily track the projection’s progress.
sessionId	String	null	yes	The session in which the graph will be projected.
memory	String	null	yes	The size of the GDS Session, e.g. `4GB`, `8GB`, etc.
ttl	Duration	1h	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 3. Results
Name	Type	Description
graphName	String	The name under which the graph is stored in the catalog.
nodeProjection	Map	The node projections used to project the graph.
nodeCount	Integer	The number of nodes stored in the projected graph.
relationshipProjection	Map	The relationship projections used to project the graph.
relationshipCount	Integer	The number of relationships stored in the projected graph.
projectMillis	Integer	Milliseconds for projecting the graph.

The following query will create a new session and project the graph into it. In this case the memory parameter is required to determine the size of the newly created session.

Project a graph into a new GDS Session

CALL gds.graph.project(
  'g',
  '*',
  '*',
  {
    memory: '2GB'
  }
) YIELD nodeCount, relationshipCount, projectMillis

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

CALL gds.graph.project(
  'g',
  '*',
  '*',
  {
    sessionId: '00000000-11111111'
  }
) YIELD nodeCount, relationshipCount, projectMillis

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

CALL gds.pageRank.stream('g')

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

CALL gds.session.getOrCreate(
  'test-session',
  '2GB',
  duration({minutes: 30})
)
YIELD name
RETURN name

Table 4. Results
name
"test-session"

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 5. 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 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.

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 7. 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 user are returned. Note, this is only relevant if authenticated via Aura API credentials.

Table 8. 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 sessionName. If the session is not found, an error is raised.

CALL gds.session.delete(
  'test-session'
)
YIELD deleted
RETURN deleted

Table 9. Results
deleted
true

Syntax

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

Table 10. 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 11. Results
Name	Type	Description
deleted	Boolean	True, if the GDS Session was successfully deleted, false otherwise.

Retrieving session information for a graph

The gds.graph.sessionInfo function returns information about the GDS Session that is associated with a projected graph. It can be used to retrieve information required for the sessionName parameter of most gds.model procedures.

Syntax

RETURN gds.graph.sessionInfo(graphName: String): Map

Table 12. Parameters
Name	Type	Optional	Default	Description
graphName	String	no	n/a	The name of the graph for which the GDS Session information will be returned.

Returns a Map value with two entries:

Table 13. Results
Name	Type	Description
`sessionName`	String	The name of the GDS Session the graph is projected in.
`sessionId`	String	The id of the GDS Session the graph is projected in.

Estimating session size

The gds.session.estimate procedure estimates the memory required for a GDS Session based on the size and shape of your graph. Use it to determine an appropriate session size before creating a session.

Syntax

CALL gds.session.estimate(
  nodeCount: Integer,
  relationshipCount: Integer,
  configuration: Map
) YIELD
  estimatedMemory: String,
  recommendedSize: String

Table 14. Parameters
Name	Type	Optional	Default	Description
nodeCount	Integer	no	n/a	The number of nodes in the graph.
relationshipCount	Integer	no	n/a	The number of relationships in the graph.
configuration	Map	yes	{}	Optional configuration map. See the configuration keys below.

Table 15. Configuration keys
Name	Type	Optional	Default	Description
nodeLabelCount	Integer	yes	0	The number of distinct node labels in the graph.
nodePropertyCount	Integer	yes	0	The number of node properties in the graph.
relationshipPropertyCount	Integer	yes	0	The number of relationship properties in the graph.
algorithmCategories	List of String	yes	[]	The categories of algorithms you plan to run in the session. Providing this helps produce a more tailored estimate. See the valid values below.

The following values are accepted for algorithmCategories (case-insensitive; hyphens and underscores are interchangeable):

centrality
community-detection
similarity
path-finding
node-embedding
machine-learning

Table 16. Results
Name	Type	Description
`estimatedMemory`	String	The estimated memory required for the session, e.g. `1.6GB`.
`recommendedSize`	String	The recommended session size to request, e.g. `2GB`. This is the smallest available tier that covers the estimated memory.

Limitations

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

If you use Aura Graph Analytics via the GDS Python client, some of these limitations might not apply. See the Python client docs for more information.

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

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.linkprediction.adamicAdar
gds.linkprediction.commonNeighbors
gds.linkprediction.preferentialAttachment
gds.linkprediction.resourceAllocation
gds.linkprediction.sameCommunity
gds.linkprediction.totalNeighbors
gds.splitRelationships

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
gds.util.nodeProperty

Explicit authentication to the Aura API

When executing Cypher queries directly within an AuraDB instance, you are automatically authorized to create and manage your own Aura Graph Analytics sessions, and you do not need to provide explicit API credentials.

Explicit authentication via Aura API credentials is required in only two specific scenarios:

Project-wide administration (Cypher): You are using Cypher and need to manage lifecycle operations (such as listing or deleting) for all sessions within the broader Aura Console Project, rather than just the sessions created by your specific logged-in database user. In this case, you must use the gds.aura.api.credentials() function in each Cypher query.
Using the Python client: If you are orchestrating sessions using the dedicated GDS Python library, the client requires Aura API credentials to authenticate with the control plane. For instructions, see the Neo4j Graph Data Science Client documentation.

It is good practice to use query parameters for sensitive data such as credentials. This also removes the need to enter the same strings multiple times.

In the Aura console, you can set query parameters within the Query tool. For other environments, see the Cypher manual.

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.

If you are operating in this admin context, you must include the credentials function in every query that interacts with the session. For example, if you created a graph using explicit credentials, attempting to run an algorithm in a new query without passing them again will fail.

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 17. 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 18. Results
Name	Type	Description
-	-	Always returns `null`.