Neo4j Graph Data Science: graph algorithms as Cypher procedures

Algorithms that run inside the database

The Neo4j Graph Data Science library is a plugin for the Neo4j graph database, and the README describes its contents in one sentence: GDS comprises graph algorithms, graph transformations, and machine learning pipelines, operated via Cypher procedures from within a Neo4j DBMS.

That last clause is the design decision. The algorithms are not a client library you call over a driver, and they are not a separate compute cluster you ship samples to. They are procedures inside the database, so a graph projection, an algorithm run and a write-back all happen against the same engine and the same transaction, and the queries look like the rest of Cypher rather than like a different API.

The library is the successor of the Neo4j Graph Algorithms library, so the algorithms that existed there, things like centrality, community detection and similarity, are the same family with a new home and a new set of capabilities around them.

The project is Java, the default branch is 2.13, and the release history is a calendar-version scheme: 2026.07.0 in August 2026, 2026.08.1 in September and 2026.09.0 later that month, with the last push on 2026-10-09. The licence metadata in the repository is a custom classification, which is the expected shape for a project with a mixed open and closed distribution, and the README covers both halves below.

The documentation is at the current documentation path for the library, with a separate preview path, and the README links a Discord server and the community forums.

Installing it is a JAR in a directory

The installation instructions are short because the packaging is a plugin.

The latest releases can always be found on the Neo4j Graph Data Science download page. To install the plugin into a Neo4j DBMS you place the downloaded JAR file in the plugins directory of your Neo4j database and restart the database. If you use Neo4j Desktop you can simply add the Graph Data Science library on the plugins page of your project. One caveat is called out: preview releases are not automatically made available in Neo4j Desktop and have to be installed manually.

The compatibility matrix is the thing to check before anything else, and it has one row in the README:

| GDS version | Neo4j version | Java Version | | GDS 2.13 | Neo4j 5.26 | Java 21 & Java 17 |

So the current line expects a recent Neo4j and a modern JVM, and there is one branch per GDS generation, which is why the default branch is named 2.13 rather than master.

That matrix also explains the build instructions later in the README, which look inconsistent with it at first glance. The development build targets an older Neo4j by default, so a developer working on the next release and a user installing a released plugin are compiling against different database versions, and the build toolchain has to be chosen accordingly.

OpenGDS: the open half and the closed half

The most important paragraph in the README concerns who gets what.

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, and Neo4j GDS is available to download and use under the constraints of its license. However, the sources in this repository can also be assembled into a fully functioning library, which the project calls OpenGDS, and OpenGDS is available to build, use, and extend under the constraints of the GNU Public License version 3.0.

So there are two products with different terms. The commercial distribution is the open sources plus closed components, under the vendor's licence. The open build is the same sources assembled into a library you can extend under the GPL v3, and it is published to Maven Central under the org.neo4j.gds group, so you can add it to your own project as a dependency.

The module layout is what you depend on. For the most basic set of features, like graph loading and the graph representation, you need the core module:

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

The algorithms are split across three modules, and the comments in the dependency block say what each one is for:

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

with algo for the productised algorithms and alpha-algo for some alpha algorithms. The procedures follow the same three-way split, proc-common for the basic procedure infrastructure, proc for the productised algorithm procedures and alpha-proc for the alpha ones, and there is a fourth module, open-write-services, described as required by the write execution modes, because it provides the various exporters.

That structure is a good guide to what you are depending on. If you only project graphs, core is enough. If you run algorithms, you pull in algo and proc. If you write results back, you pull in the exporters as well.

The Pregel API, and the bootstrap project to start from

The way to extend the library is the Pregel API, and the README tells you where to start.

To build your own algorithms using the Pregel API, the recommendation is to start with the pregel-bootstrap project in the examples directory of the repository. The Pregel API is the layer that turns a graph algorithm into a set of parallel vertex and edge computations, and the bootstrap project is a working example of the whole shape, from the computation framework through to the procedure that exposes it to Cypher.

There is one note attached to it, and it is the kind of note that saves a confusing afternoon. The module on master depends on the unpublished version of this library, and the GDS version can be changed in the build.gradle of the pregel-bootstrap module.

That is a consequence of the two-product structure. The master branch is where the next release is being developed, and the version in the build file points at an artifact that has not been published yet, so a fresh clone of the examples does not resolve against Maven Central until you either point the build at a published version or build the library yourself from the sources in this repository, which is exactly what the OpenGDS section describes.

The examples directory holds two projects, pregel-bootstrap and pregel-example, and they cover the two cases: writing a new algorithm from the bootstrap, and seeing a complete one worked out.

A Python client that mimics the Cypher API

The library comes with a Python client called graphdatascience, and the README describes what it is for in three sentences.

It enables users to write pure Python code to project graphs, run algorithms, and define and use machine learning pipelines in GDS. The API is designed to mimic the GDS Cypher procedure API in Python code, and it abstracts the necessary operations of the Neo4j Python driver to offer a simpler surface.

The mimicry is the useful part. If you know the Cypher procedure API, the Python client does not ask you to learn a second model of the same thing, and the mapping from a procedure call to a Python call is close enough to be obvious. For a team that has pipelines in Cypher and scripts in Python, that consistency removes a category of friction.

Two constraints are stated. The client is only guaranteed to work with GDS versions 2.0 and later, so a project on the previous generation of the library is out of scope, and the source code lives in a separate repository, the graph-data-science-client, rather than here. That separation is sensible, because a client and a database plugin release on their own cadences, and a Python package that had to be version-locked to the Java plugin would be painful to distribute.

The final detail is about the surface the client offers. It covers projection, running algorithms and defining machine learning pipelines, which is the same three-part structure the library itself has, and it is the three parts you would use in that order: get the graph in, compute on it, and persist the results.

Building it: SDKMAN, two JDKs and the Gradle wrapper

The build section is a practical recipe, and it is worth following exactly, because the toolchain choice is part of the build.

Install SDKMAN:

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

Then install both JDK 11 and JDK 17 Temurin:

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

The notes explain the rest. Those versions were the latest when the notes were written, and sdk list java shows what is available now. You do not need to set them as the default JDK, because the Gradle toolchain mechanism selects the right one per task. If you want to opt out of Temurin, you can override javaLanguageVendor and javaLanguageVersion in your project-local gradle.properties, with the caveat that the overridden versions have to be installed locally.

OpenGDS uses Gradle, and Gradle is shipped with the repository using the Gradle Wrapper, so any task can be run as ./gradlew TASK from the repository root.

The last point is the one that reconciles the build with the compatibility matrix. By default the build targets Neo4j version 4.4.x, which is defined in public/gradle/dependencies.gradle, so you either select JDK 11 or, if you want a different target, adjust the dependency and the toolchain. The current release line wants Neo4j 5.26 on Java 21 or 17, and the development build has not caught up with that, which is why a developer needs both JDKs installed.

The module list is the architecture

The top-level listing is long, and it is a map of the library rather than a list of files.

The core is split into core/, core-api/, core-utils/, core-write/ and core-test-utils/, with the test helpers in core-test-utils/ and the write path separated from the read path. The algorithm side is algo/, algo-common/, algo-params/, algo-test/ and alpha/, and the procedure side mirrors it. Then there is ml/ for the machine learning pipelines, collections/ with its generator and a memory estimation module, and concurrency/ with a concurrency validation API, plus executor/ and io/ for the machinery that runs the work.

The graph handling is spread across several modules with revealing names: graph-construction/, graph-dimensions/, graph-projection-api/, graph-sampling/ and graph-schema-api/, and two projection implementations, native-projection/ and legacy-cypher-projection/, which is the difference between pushing a graph into the native engine and projecting it through Cypher queries.

Around those are the supporting layers: model-catalog-api/, metrics-api/, memory-estimation/ and memory-usage/, licensing/, logging/, neo4j-adapter/, neo4j-api/, neo4j-log-adapter/ and neo4j-settings/, plus config-api/, defaults-and-limits-configuration/, cypher-aggregation/, gds-values/ and the compatibility/ and dependencies/ directories.

And then the parts that are about the project rather than the code: algorithm-specifications/, which is how the library documents what each algorithm should compute, doc/ and doc-test/ and doc-test-tools/, applications/, annotations/, the code generators for collections and config, the examples/ directory with the two Pregel projects, and the build files themselves.

Taken together, the module count tells you what kind of project this is. It is not a collection of algorithms, it is an engine for running algorithms inside a database, with the graph representation, the concurrency model, the memory accounting and the projection layers each isolated behind an API.

Editorial conclusion

Adopt OpenGDS, the open build of the Graph Data Science library, if you need the algorithms inside Neo4j and cannot accept the closed components in the commercial distribution, because the sources in this repository assemble into a working library that you can extend. Do not expect the open build to be identical to the product, since the distributed library also contains a suite of closed sources, and the version of the algorithm set you get from the open build is the one in the source tree rather than the one in the download. Before you start, check the compatibility matrix, where GDS 2.13 pairs with Neo4j 5.26 on Java 21 or 17, and read the build notes, because the default build targets Neo4j 4.4 and the Gradle toolchain has to be configured to match the Neo4j you run.

Frequently asked questions

Official sources

1. Issues
2. neo4j/graph-data-science on GitHub
3. Project website
4. README
5. Releases