GDS Sessions

class graphdatascience.session.gds_sessions.GdsSessions

Primary API class for managing GDS sessions hosted in Neo4j Aura.

__init__(api_credentials: AuraAPICredentials) → None

Create a new instance of the GdsSessions class.

Parameters:

api_credentials (AuraAPICredentials) – The Aura API credentials used for establishing a connection.

Return type:

None

available_cloud_locations() → list[CloudLocation]

Retrieves the list of available cloud locations in Aura.

Returns:

list[CloudLocation]: The list of available cloud locations.

Return type:

list[CloudLocation]

delete(*, session_name: str | None = None, session_id: str | None = None) → bool

Delete a GDS session either by name or id. :param session_name: the name of the session to delete :param session_id: the id of the session to delete

Returns:

True iff a session was deleted as a result of this call.

Return type:

bool

Parameters:

  • session_name (str | None)

  • session_id (str | None)

estimate(node_count: int, relationship_count: int, algorithm_categories: list[AlgorithmCategory] | list[str] | None = None, node_label_count: int = 0, node_property_count: int = 0, relationship_property_count: int = 0, algorithms: list[str] | dict[str, dict[str, Any]] | None = None) → SessionMemory

Estimates the memory required for a session with the given node and relationship counts.

Parameters:

  • node_count (int) – Number of nodes.

  • relationship_count (int) – Number of relationships.

  • algorithm_categories (list[AlgorithmCategory] | list[str] | None) – The algorithm categories to consider. Cannot be combined with algorithms.

  • node_label_count (int) – Number of node labels.

  • node_property_count (int) – Number of node properties.

  • relationship_property_count (int) – Number of relationship properties.

  • algorithms (list[str] | dict[str, dict[str, Any]] | None) – The individual algorithms to consider, which gives a finer-grained estimate than algorithm_categories. Either a list of algorithm names, such as [“wcc”, “degree”], or a mapping from algorithm name to its configuration, such as {“wcc”: {}, “fastRP”: {“embedding_dimension”: 1024}}. Algorithm names are matched case-insensitively and the gds. prefix is optional. Configuration values must be numeric. Cannot be combined with algorithm_categories.

Returns:

The estimated memory required for the session.

Return type:

SessionMemory

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

Retrieves an existing session with the given session name and database connection, or creates a new session if one does not exist.

If the session is close to expiration, a warning will be raised. If the session failed, an exception will be raised.

Parameters:

  • session_name (str) – The name of the session.

  • memory (SessionMemory | SessionMemoryValue | str) – The size of the session specified by memory.

  • db_connection (DbmsConnectionInfo | None) – The database connection information.

  • ttl (datetime.timedelta | None) – The session’s time to live after inactivity.

  • cloud_location (CloudLocation | None) – The cloud location where the GDS Session will run. Must be a CloudLocation(provider, region) with a supported provider (“gcp”, “aws”, or “azure”) and an Aura-supported region (e.g. “europe-west1”). Required for the Self-managed and Standalone session types; must not be provided for Attached sessions. Use available_cloud_locations() to list all valid provider/region combinations.

  • timeout (int | None) – Optional timeout (in seconds) when waiting for session to become ready. If unset the method will wait forever. If set and session does not become ready an exception will be raised. It is user responsibility to ensure resource gets cleaned up in this situation.

  • neo4j_driver_config (dict[str, Any] | None) – Optional configuration for the Neo4j driver to the Neo4j DBMS. Only relevant if db_connection is specified..

  • arrow_client_options (dict[str, Any] | None) – Optional configuration for the Arrow Flight client. The key call_timeout sets the per-call RPC timeout in seconds (default 30s).

  • show_progress (bool) – Whether the returned client should print its own job-progress bars (projection, algorithm execution, …). Defaults to True.

Returns:

AuraGraphDataScience: The session.

Return type:

AuraGraphDataScience

list(instance_id: str | None = None, list_only_owned: bool = False, include_deleted: bool = False, start_date: datetime | None = None, end_date: datetime | None = None) → list[SessionInfo]

Retrieves the list of GDS sessions visible by the user associated by the given api-credentials.

Parameters:

  • instance_id (str | None) – Optional filter for sessions attached to one AuraDB instance.

  • list_only_owned (bool) – Optional filter to list only sessions owned by the authenticated user.

  • include_deleted (bool) – Optional flag to include deleted sessions.

  • start_date (datetime | None) – Optional lower bound for session creation timestamp.

  • end_date (datetime | None) – Optional upper bound for session creation timestamp.

Returns:

A list of SessionInfo objects representing the GDS sessions.

Return type:

list[SessionInfo]

class graphdatascience.session.gds_sessions.AuraAPICredentials

Represents the credentials required for accessing the Aura API.

client_id

The client ID for authentication.

Type:

str

client_secret

The client secret for authentication.

Type:

str

project_id

The project ID for authentication. Needed if a client belongs to multiple projects.

Type:

str | None

__init__(client_id: str, client_secret: str, project_id: str | None = None) → None
Parameters:

  • client_id (str)

  • client_secret (str)

  • project_id (str | None)

Return type:

None

static from_env() → AuraAPICredentials

Create an AuraApi instance from environment variables. The environment variables are: - CLIENT_ID - CLIENT_SECRET - PROJECT_ID

Return type:

AuraAPICredentials

class graphdatascience.session.gds_sessions.SessionInfo

Represents information about a session.

id

The ID of the session.

Type:

str

name

The name of the session.

Type:

str

memory

The size of the session.

Type:

str

instance_id

The ID of the AuraDB instance the session is attached to.

Type:

str | None

status

The status of the session.

Type:

str

expiry_date

The date the session expires. This is a fixed limit regardless of the user-defined TTL.

Type:

datetime.datetime | None

created_at

The date the session was created.

Type:

datetime.datetime

user_id

The Aura console user-id of the user who created the session.

Type:

str

cloud_location

The provider and region in which the session is located at.

Type:

CloudLocation | None

ttl

The time until the session is deleted if unused. The TTL gets renewed on every activity. Rounded down to the nearest minute.

Type:

datetime.timedelta | None

errors

The list of errors related to the session.

Type:

list[SessionErrorData]

termination_reason

The reason the session was terminated, if it has been deleted.

Type:

str | None

__init__(id: str, name: str, memory: SessionMemoryValue, instance_id: str | None, status: str, expiry_date: datetime | None, created_at: datetime, user_id: str, cloud_location: CloudLocation | None, ttl: timedelta | None = None, errors: list[SessionErrorData] | None = None, termination_reason: str | None = None) → None
Parameters:
Return type:

None