neo4j/graph-data-science

= Neo4j Graph Data Science

image:https://github.com/neo4j/graph-data-science/actions/workflows/gradle_cipr.yml/badge.svg?branch=master[https://github.com/neo4j/graph-data-science/actions/workflows/gradle_cipr.yml] image:https://img.shields.io/maven-central/v/org.neo4j.gds/proc.svg?label=Maven%20Central[https://search.maven.org/search?q=g:%22org.neo4j.gds%22%20AND%20a:%22proc%22] https://neo4j.com/docs/graph-data-science/preview/installation/[image:https://img.shields.io/badge/Documentation-latest-blue[Documentation]] https://discord.gg/neo4j[image:https://img.shields.io/discord/787399249741479977?label=Chat&logo=discord&style=flat-square[Discord]] https://community.neo4j.com/[image:https://img.shields.io/website?down_color=lightgrey&down_message=offline&label=Forums&logo=discourse&style=flat-square&up_color=green&up_message=online&url=https%3A%2F%2Fcommunity.neo4j.com%2F[Forums online status]]

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 https://neo4j.com/graph-data-science-software/[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 https://neo4j.com/docs/graph-data-science/current/installation/[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:

.Compatibility matrix |=== |GDS version | Neo4j version | Java Version |GDS 2.13 | Neo4j 5.26 | Java 21 & Java 17 |===

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 https://neo4j.com/docs/graph-data-science/current/algorithms/pregel-api/#algorithms-pregel-api-example[docs]), we recommend starting with the https://github.com/neo4j/graph-data-science/tree/2.7/examples/pregel-bootstrap[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 https://github.com/neo4j/graph-data-science-client[here].

== Developing with OpenGDS

OpenGDS is also available on https://search.maven.org/search?q=g:org.neo4j.gds[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:

[source]

org.neo4j.gds core 2.13.9 ----

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

[source]

org.neo4j.gds algo-common 2.13.9 org.neo4j.gds algo 2.13.9 org.neo4j.gds alpha-algo 2.13.9 ----

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

[source]

org.neo4j.gds proc-common 2.13.9 org.neo4j.gds proc 2.13.9 org.neo4j.gds alpha-proc 2.13.9 org.neo4j.gds open-write-services 2.13.9 ----

== Building the library

Installing JDKs::

Install https://sdkman.io/[SKDMAN]

[source]

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

Install both JDK 11 and JDK 17 Temurin: [source]

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. https://docs.gradle.org/current/javadoc/org/gradle/jvm/toolchain/JvmVendorSpec.html[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 https://neo4j.com/docs/graph-data-science/current/installation/[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 link:CONTRIBUTING.md[contribution guidelines for this project].

== License

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