Neo4j Graph Data Science

This repository hosts the open sources of the Neo4j Graph Data Science (GDS) library. The GDS library is a plugin for the Neo4j graph database. GDS comprises graph algorithms, graph transformations, and machine learning pipelines, operated via Cypher procedures from within a Neo4j DBMS.

The Neo4j Graph Data Science library is the successor of the Neo4j Graph Algorithms library.

Downloading and installing releases

The latest releases of Neo4j Graph Data Science can always be found at the Neo4j Graph Data Science Download Page. To install the plugin into a Neo4j DBMS place the downloaded JAR file it in the plugins directory of your Neo4j database and restart the database. For further instructions, see our documentation.

If you are using Neo4j Desktop you can simply add the Graph Data Science library on the plugins page of your project.

When installing GDS manually, please refer to the below compatibility matrix:

Table 1. Compatibility matrix (italicized version is in development)

GDS version	Neo4j version	Java Version
GDS 2.12.x (preview)	Neo4j 5.25.0	Java 21 & Java 17
	Neo4j 5.24.0
GDS 2.11.x	Neo4j 5.24.0	Java 21 & Java 17
	Neo4j 5.23.0
GDS 2.10.x	Neo4j 5.24.0	Java 21 & Java 17
	Neo4j 5.23.0
	Neo4j 5.22.0
GDS 2.9.x	Neo4j 5.23.0	Java 21 & Java 17
	Neo4j 5.22.0
	Neo4j 5.21.0, 5.21.1, 5.21.2
	Neo4j 5.20.0
	Neo4j 5.19.0
	Neo4j 5.18.0, 5.18.1
	Neo4j 5.17.0
GDS 2.8.x	Neo4j 5.22.0	Java 21 & Java 17
	Neo4j 5.21.0, 5.21.1, 5.21.2
	Neo4j 5.20.0
	Neo4j 5.19.0
	Neo4j 5.18.0, 5.18.1
	Neo4j 5.17.0
	Neo4j 5.16.0
GDS 2.7.x	Neo4j 5.21.0, 5.21.1, 5.21.2	Java 21 & Java 17
	Neo4j 5.20.0
	Neo4j 5.19.0
	Neo4j 5.18.0, 5.18.1
	Neo4j 5.17.0
	Neo4j 5.16.0
GDS 2.6.x	Neo4j 5.20.0	Java 21 & Java 17
	Neo4j 5.19.0
	Neo4j 5.18.0, 5.18.1
	Neo4j 5.17.0
	Neo4j 5.16.0
	Neo4j 5.15.0
	Neo4j 5.14.0
	Neo4j 4.4.9 - 4.4.38	Java 11

Note	Preview releases are not automatically made available in Neo4j Desktop. They need to be installed manually.

OpenGDS

The Neo4j Graph Data Science library as built and distributed by Neo4j includes the sources in this repository as well a suite of closed sources. Neo4j GDS is available to download and use under the constraints of its license.

However, the sources in this repository can be also be assembled into a fully functioning library, which we call OpenGDS. OpenGDS is available to build, use, and extend under the constraints of the GNU Public License version 3.0.

Using the Pregel API

To build your own algorithms using the Pregel API (see at docs), we recommend starting with the pregel-bootstrap project.

Note	The module on master depends on the unpublished version of this library. The GDS version can be changed in the build.gradle of the pregel-bootstrap module.

Python client

The library comes with a Python client called graphdatascience. It enables users to write pure Python code to project graphs, run algorithms, as well as define and use machine learning pipelines in GDS.

The API is designed to mimic the GDS Cypher procedure API in Python code. It abstracts the necessary operations of the Neo4j Python driver to offer a simpler surface.

graphdatascience is only guaranteed to work with GDS versions 2.0+.

You can find the graphdatascience source code here.

Developing with OpenGDS

OpenGDS is also available on Maven Central. If you want to include the OpenGDS in your own project you can simply add it as a dependency.

For the most basic set of features, like graph loading and the graph representation, you need to include the core module:

<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>core</artifactId>
  <version>2.12.0</version>
</dependency>

The algorithms are located in the algo-common, algo and alpha-algo modules:

<!-- Contains the basic algorithm infrastructure -->
<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>algo-common</artifactId>
  <version>2.12.0</version>
</dependency>

<!-- Contains the productized algorithms -->
<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>algo</artifactId>
  <version>2.12.0</version>
</dependency>

<!-- Contains some alpha algorithms -->
<dependency>
    <groupId>org.neo4j.gds</groupId>
    <artifactId>alpha-algo</artifactId>
    <version>2.12.0</version>
</dependency>

The procedures are located in the proc-common, proc and alpha-proc modules:

<!-- Contains the basic procedure infrastructure -->
<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>proc-common</artifactId>
  <version>2.12.0</version>
</dependency>

<!-- Contains the productized algorithm procedures -->
<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>proc</artifactId>
  <version>2.12.0</version>
</dependency>

<!-- Contains some alpha algorithm procedures-->
<dependency>
    <groupId>org.neo4j.gds</groupId>
    <artifactId>alpha-proc</artifactId>
    <version>2.12.0</version>
</dependency>

<!-- Required by the write execution modes, this artifact is responsible for providing the various exporters -->
<dependency>
  <groupId>org.neo4j.gds</groupId>
  <artifactId>open-write-services</artifactId>
  <version>2.12.0</version>
</dependency>

Building the library

Installing JDKs

Install SKDMAN

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

Install both JDK 11 and JDK 17 Temurin:

sdk install java 11.0.19-tem
sdk install java 17.0.7-tem

Note	These versions were the latest at the time of writing these notes. To see a list of the available versions you can run sdk list java.

Note	You do not need to set them as default JDK

If you want to opt out of Temurin, you can override javaLanguageVendor and javaLanguageVersion in your project-local gradle.properties. List of Gradle supported language vendors

Note	The javaLanguageVendor and javaLanguageVersion overrides have to be installed locally on your system.

OpenGDS uses the build tool Gradle. Gradle is shipped with this repository using the Gradle Wrapper. This means you can simply run any Gradle task by running ./gradlew TASK from the repository root.

By default we build against Neo4j version 4.4.x, which is defined in public/gradle/dependencies.gradle. Therefore, you either select JDK 11 or if you want to run with JDK 17, you add -Pneo4jVersion=5.1.0.

Running tests

To run all tests you can simply run ./gradlew check

Packaging the library

To package the library you can run ./gradlew :open-packaging:shadowCopy. This will create a bundled JAR called open-gds-VERSION.jar in the directory build/distributions/. To use the bundled JAR in Neo4j, place the JAR file in the plugins directory of your Neo4j database and restart the database. For further instructions, see our documentation.

Preview of the documentation

A preview of the latest documentation can be found at https://neo4j.com/docs/graph-data-science/preview/.

Contributing

Please report any bugs, concerns, or other questions as GitHub issues to this repository.

For more information see the contribution guidelines for this project.

License

OpenGDS is licensed under the GNU Public License version 3.0. All content is copyright © Neo4j Sweden AB.