Aura Graph Analytics

Aura Graph Analytics 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.

There are three types of GDS Sessions:

Attached: the data source is a Neo4j AuraDB instance.
Self-managed: the data source is a self-managed Neo4j DBMS.
Standalone: the data source is not based on Neo4j.

The process of populating the session with data is called projection. Once populated, a GDS Session can run GDS workloads, such as algorithms and machine learning models. Results from these computations can be written back to the original source, using remote write-back in the Attached and Self-managed types.

For ready-to-run notebooks, see our tutorials on GDS Sessions for AuraDB, self-managed databases, and any other data source.

GDS Session management

The GdsSessions object is the API entry point to the following operations:

get_or_create: Create a new GDS Session, or connect to an existing one.
list: List all currently active GDS Sessions.
delete: Delete a GDS Session.

You need Neo4j Aura API credentials (CLIENT_ID and CLIENT_SECRET) to create a GdsSessions object. See the Aura documentation for instructions on how to create API credentials from your Neo4j Aura account. If your Aura user is part of multiple projects, the desired project ID must also be provided.

Creating a GdsSessions object:

from graphdatascience.session import GdsSessions, AuraAPICredentials

CLIENT_ID = "my-aura-api-client-id"
CLIENT_SECRET = "my-aura-api-client-secret"
PROJECT_ID = None

# Create a new GdsSessions object
sessions = GdsSessions(api_credentials=AuraAPICredentials(CLIENT_ID, CLIENT_SECRET, PROJECT_ID))

All available methods and parameters are listed in the API reference.

Creating a GDS Session

To create a GDS Session, use the get_or_create() method. It will create a new session if it does not exist, or connect to an existing one if it does. If the session options differ from the existing one, an error is thrown.

The return value of get_or_create() is an AuraGraphDataScience object. It offers a similar API to the GraphDataScience object, but it is configured to run on a GDS Session. As a convention, always use the variable name gds for the return value of get_or_create().

For the Self-managed and Standalone session types, a cloud_location parameter is required. Use sessions.available_cloud_locations() to list all valid cloud provider/region combinations supported by your Aura project.

Session expiration and deletion

When the session is created, an optional ttl parameter can be configured to set the time after which 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.

Maximum lifetime

A session can never be kept active for more than 7 days. Even if the session does not expire due to inactivity, it will still expire 7 days after its creation. This is a hard limit and cannot be changed.

Syntax

sessions.get_or_create(
    session_name: str,
    memory: SessionMemory | SessionMemoryValue | str,
    db_connection: Optional[DbmsConnectionInfo] = None,
    ttl: Optional[timedelta] = None,
    cloud_location: Optional[CloudLocation] = None,
    timeout: Optional[int] = None,
    neo4j_driver_config: Optional[dict[str, Any]] = None,
    arrow_client_options: Optional[dict[str, Any]] = None,
    show_progress: bool = True,
): AuraGraphDataScience

Table 1. Parameters:
Name	Type	Optional	Default	Description
`session_name`	`str`	no	`-`	Name of the session. Must be unique within the project.
`memory`	`SessionMemory`	no	`-`	Amount of memory available to the session.
`db_connection`	`DbmsConnectionInfo`	yes	`None`	Aura instance-id, username, and password to a Neo4j DBMS. Required for the Attached and Self-managed types. For self-managed, provide the URI instead of the instance-id. Alternatively to username and password, you can provide a `neo4j.Auth` object.
`ttl`	`datetime.timedelta`	yes	`1h`	Time-to-live for the session.
`cloud_location`	`CloudLocation`	yes	`None`	Aura-supported cloud provider and region where the GDS Session will run. The provider must be one of `"gcp"`, `"aws"`, or `"azure"`, and the region must be an Aura-supported region (e.g. `"europe-west1"`). Required for the Self-managed and Standalone types. Use `sessions.available_cloud_locations()` to list all valid provider/region combinations.
`timeout`	`int`	yes	`None`	Seconds to wait for the session to enter Ready state. If the time is exceeded, an error will be returned.
`neo4j_driver_config`	`dict[str, any]`	yes	`None`	Additional options passed to the Neo4j driver to the Neo4j DBMS. Only relevant if `db_connection` is specified.
`arrow_client_options`	`dict[str, any]`	yes	`None`	Additional options passed to the Arrow Flight Client used to connect to the Session.
`show_progress`	`bool`	yes	`True`	Whether the returned client should print its own job-progress bars (projection, algorithm execution, …).

Examples

Creating a GDS Session attached to an AuraDB instance:

from graphdatascience.session import DbmsConnectionInfo, SessionMemory

gds = sessions.get_or_create(
    session_name="my-attached-session", # Must be unique within the project
    memory=SessionMemory.m_4GB,
    db_connection=DbmsConnectionInfo(
        aura_instance_id="mydbid",
        username="my-user",
        password="my-password"
    ),
)

Creating a GDS Session for a self-managed Neo4j DBMS:

from graphdatascience.session import DbmsConnectionInfo, CloudLocation, SessionMemory

gds = sessions.get_or_create(
    session_name="my-self-managed-session", # Must be unique within the project
    memory=SessionMemory.m_4GB,
    db_connection=DbmsConnectionInfo(
        uri="neo4j://localhost",
        username="my-user",
        password="my-password"
    ),
    cloud_location=CloudLocation(provider="gcp", region="europe-west1"),
)

Creating a GDS Session without any Neo4j database:

from graphdatascience.session import CloudLocation, SessionMemory

gds = sessions.get_or_create(
    session_name="my-standalone-session", # Must be unique within the project
    memory=SessionMemory.m_4GB,
    cloud_location=CloudLocation(provider="gcp", region="europe-west1"),
)

Verifying the connection

To check the connection setup between the client and the Aura Graph Analytics session, you can use:

gds.verify_connectivity()

Providing custom TLS certificates

If the connection fails, it might be due to the TLS certificate. First, verify if the connection issue is indeed related to TLS.

Temporarily skips server verification during TLS

from graphdatascience.arrow_client.arrow_client_options_util import disable_server_verification

arrow_client_options = {}
disable_server_verification(arrow_client_options) # ONLY FOR TESTING
gds = sessions.get_or_create(
    ...,
    arrow_client_options=arrow_client_options
)
gds.verify_connectivity()

If this setup works, you should now enable server verificaton again an pass custom TLS certificates

Pass TLS certificates explicitly

from graphdatascience.arrow_client.arrow_client_options_util import set_tls_root_certs
import certifi

arrow_client_options = {}
custom_tls = certifi.contents() # example certificates to use
set_tls_root_certs(arrow_client_options, custom_tls)
gds = sessions.get_or_create(
    ...,
    arrow_client_options=arrow_client_options
)
gds.verify_connectivity()

Listing GDS Sessions

The list() method returns the name and size of memory of all currently active GDS Sessions.

Listing GDS Sessions:

sessions.list()

For a detailed description of the allowed parameters, see the API reference.

Deleting a GDS Session

Deleting a GDS Session will terminate the session and stop any running costs from accumulating further. Deleting a session will not affect the configured Neo4j data source. However, any data not written back to the Neo4j instance will be lost.

If you have an open connection to the session:

Deleting a GDS Session via an open client connection:

gds.delete()

Use the delete() method to delete a GDS Session.

Deleting a GDS Session via the GdsSessions object:

sessions.delete(session_name="my-new-session")

Estimating session memory

In order to help determine a good session size for a given workload, there is the estimate() function. By providing expected sizing of the graph and intended algorithm categories to be used, it will return an estimated size of the session.

Estimating the size of a GDS Session via the GdsSessions object:

from graphdatascience.session import AlgorithmCategory

memory = sessions.estimate(
    node_count=20,
    relationship_count=50,
    algorithm_categories=[AlgorithmCategory.CENTRALITY, AlgorithmCategory.NODE_EMBEDDING],
    node_label_count=1,
    node_property_count=1,
    relationship_property_count=1
)

Since specifying an algorithm category will returns the estimated memory of the most memory consuming algorithms of that category, suggested session sized can be much larger than your workload actually needs. If you know which algorithms you intend to run, pass them via the algorithms parameter instead to get a finer-grained estimate. Algorithm names are matched case-insensitively and the gds. prefix is optional.

Estimating the size of a GDS Session for individual algorithms:

memory = sessions.estimate(
    node_count=20,
    relationship_count=50,
    algorithms=["wcc", "degree"]
)

Algorithm configuration affects the estimate as well, so you can also pass a numeric configuration per algorithm. Algorithms without configuration map will use default values.

Estimating the size of a GDS Session for individual algorithms and their configuration:

memory = sessions.estimate(
    node_count=20,
    relationship_count=50,
    algorithms={"wcc": {}, "fast_rp": {"embedding_dimension": 1024}}
)

The algorithms and algorithm_categories parameters are exclusive cannot be combined.

For a detailed description of the allowed parameters, see the API reference.

Projecting graphs into a GDS Session

Once you have a GDS Session, you can project a graph into it. Aura Graph Analytics offers two projection methods when connected to a Neo4j databases: Native projections and Cypher projections. For more detailed information about projections see Graph Projection.

Only numeric node properties can be projected into a GDS Session. String properties such as name can instead be included when streaming results back, via the db_node_properties parameter (see Include node properties from Neo4j).

The following query creates an example graph in the Neo4j database, used by the examples on this page.

gds.run_cypher(
    """
    CREATE
      (anne: User {name: "Anne"}),
      (bill: User {name: "Bill"}),
      (catie: User {name: "Catie"}),
      (phone: Product {cost: 549}),
      (laptop: Product {cost: 1299}),
      (anne)-[:KNOWS]->(bill),
      (bill)-[:KNOWS]->(catie),
      (anne)-[:BOUGHT]->(phone),
      (bill)-[:BOUGHT]->(laptop)
    """
)

Native projections

Native projections allow you to efficiently project graphs directly from your underlying database storage into your GDS session. By bypassing query-based filtering, they offer the highest performance and scalability for bulk graph loading.

Native projection: