Quickstart

The design philosophy of the Python client is to mimic the GDS Cypher API in Python code. The Python client will translate the Python code written by the user to a corresponding Cypher query which it will then run on the Neo4j server using a Neo4j Python driver connection.

Import and setup

Use the Neo4j URI and credentials according to your setup.

The Python client has dedicated support for Aura Graph Analytics.

This example shows how to instantiate the GraphDataScience object using an Aura API key pair and AuraDB connection information.

from graphdatascience.session import DbmsConnectionInfo, GdsSessions, AuraAPICredentials, SessionMemory

sessions = GdsSessions(api_credentials=AuraAPICredentials(AURA_API_CLIENT_ID, AURA_API_CLIENT_SECRET))

# `NEO4J_URI` has the format "neo4j+s://xxxxxxxx.databases.neo4j.io".
# The credentials are for the AuraDB instance.
gds = sessions.get_or_create(
    session_name="my-session",
    memory=SessionMemory.m_4GB,
    db_connection=DbmsConnectionInfo(NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD),
)

If you are connecting to a Neo4j database with the GDS Plugin installed, or to an AuraDS instance.

from graphdatascience import GraphDataScience

# For example, in a local setup `NEO4J_URI` would be "neo4j://127.0.0.1:7687".
# For an AuraDS instance `NEO4J_URI` would be "neo4j+s://xxxxxxxx.databases.neo4j.io".
gds = GraphDataScience(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))

The client automatically detects whether it is connected to an AuraDS instance and, if so, applies the recommended non-default Python driver settings.

The GraphDataScience object needs the Neo4j database to be available upon construction, and uses the default neo4j database by default.

gds = GraphDataScience(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD), database="neo4j")

You can replace "neo4j" with a different database, or change the database after creating the GraphDataScience object:

gds.set_database("other-db")

Additional checks

Check the version of GDS library running on the server:

There is no server version in an Aura Graph Analytics session. You can check the network connection instead.

gds.verify_connectivity()

print(gds.server_version())

AuraDS instances always use the latest version of GDS.

Check if the GDS library running on the server has an enterprise license:

Aura Graph Analytics sessions always use an enterprise license.

print(gds.is_licensed())

AuraDS instances always use an enterprise license.

Usage example

The following example shows how to use the GraphDataScience object to:

Run a Cypher query to populate the Neo4j database.
Create a graph projection.
Run an algorithm on the graph.
Inspect the updated graph.

# Create a minimal example graph.
gds.run_cypher(
  """
  CREATE
    (m: City {name: "Malmö"}),
    (l: City {name: "London"}),
    (s: City {name: "San Mateo"}),
    (m)-[:FLY_TO]->(l),
    (l)-[:FLY_TO]->(m),
    (l)-[:FLY_TO]->(s),
    (s)-[:FLY_TO]->(l)
  """
)

# Create an in-memory graph called `neo4j-offices` and
# a `G_office` object representing the projected graph.
G_office, project_result = gds.graph.project.native(
    graph_name="my-graph",
    node_label_filter=["City"],
    relationship_type_filter=["FLY_TO"]
)

# Run the `mutate` mode of the PageRank algorithm.
mutate_result = gds.page_rank.mutate(G_office, tolerance=0.5, mutate_property="rank")

# Inspect the node properties of the projected graph to confirm that a new property has been created.
assert G_office.node_properties()["City"] == ["rank"]

# Create a minimal example graph.
gds.run_cypher(
  """
  CREATE
    (m: City {name: "Malmö"}),
    (l: City {name: "London"}),
    (s: City {name: "San Mateo"}),
    (m)-[:FLY_TO]->(l),
    (l)-[:FLY_TO]->(m),
    (l)-[:FLY_TO]->(s),
    (s)-[:FLY_TO]->(l)
  """
)

# Create an in-memory graph called `neo4j-offices` and
# a `G_office` object representing the projected graph.
G_office, project_result = gds.graph.project.native("neo4j-offices", node_projection="City", relationship_projection="FLY_TO")

# Run the `mutate` mode of the PageRank algorithm.
mutate_result = gds.page_rank.mutate(G_office, tolerance=0.5, mutate_property="rank")

# Inspect the node properties of the projected graph to confirm that a new property has been created.
assert G_office.node_properties()["City"] == ["rank"]

You can also use one of the datasets that comes with the library to get started. See the Datasets chapter for more on this.

Close open connections

# Delete the session to tear down the associated remote Aura Graph Analytics Session
# alternatively use sessions.delete(session_name="my-session")
gds.delete()

# Close any open connections in the underlying Neo4j driver's connection pool
gds.close()

The close method is also called automatically when the GraphDataScience object is deleted.