Server extensions

Server extensions allow new surfaces to be created in the REST API. Use them if you want more fine-grained control over your application's interactions with Neo4j than Cypher provides.

To know more about how to write and test your extensions please read the Neo4j unmanaged server extensions documentation.

Keep in mind

Please be careful with server extensions. You will be able to deploy JAX-RS classes to the server, and it’s easy to consume lots of heap space and degrade performance.

We highly encourage to test your server extensions in staging environments before uploading them into production.

Once you have written or downloaded an extension, you will need to pack it in a compressed file. As part of the compressed file you’ll need to add a neo4j-server.properties file, where you’ll put all the needed configuration for your extension, such as where Neo4j will look for it.

org.neo4j.server.thirdparty_jaxrs_classes=com.graphaware.server=/graphaware
dbms.unmanaged_extension_classes=com.graphaware.server=/graphaware

Further considerations

Please take the following considerations into account while preparing your server extension to be uploaded:d

  • Supported formats are zip, tar, cpio, gz, bz2 and xz.
  • There is a size limit of 100MB for Hobby and Standard databases and 500MB for Performance and higher.
  • A file can contain multiple .jar files in the top-level directory.
  • Only files with jar format or neo4j-server.properties are extracted, the rest will be ignored. *
  • If a neo4j-server.properties file is found, its content is added to the neo4j-server.properties of the Neo4j process.
  • neo4j-server.properties can contain $PLUGIN_ROOT, which will be replaced with the path of the plug-in. This can be used to reference files in the archive.

Note

Graphaware extensions use a neo4j.properties file instead of a neo4j-server.properties file for their configuration. GrapheneDB takes care of this for you automatically. Read more in Graphaware extensions section.

Adding server extensions

Follow these instructions to add a new server extension to your database:

  1. Navigate to the Extensions tab of your database dashboard, and click on the New server extension button from the dropdown menu New extension.
  2. Name your extension in order to be able to identify it afterwards.
  3. Select the compressed file from your local path and click.
  4. Do not close your browser window! The upload will stop if you close your browser. If the upload fails, you can click on the Retry button to start it again.
  5. When the upload completes successfully, you will see a new row in your Extensions list with the status ENABLED - PENDING.
  1. Before the extension can be available for use, it is necessary to restart the database. To perform this operation, click on the Apply changes button.
  2. A new window will show you a list of the changes you are going to perform. Please review them and click on Apply changes.

Once the changes are applied, you will see the final status (ENABLED or DISABLED) in the list.

Note

Server extensions and stored procedures are shown together in your Extensions list.

Remove unmanaged server extensions

To remove an unmanaged server extension

  • Navigate to the Extensions tab of your database dashboard
  • Disable the server extension if it isn’t already disabled
    Click on the Remove link next to the extension.

Only disabled extensions can be removed. Make sure the extension is disabled before removing it.

Danger

This action cannot be undone and will delete your server extension permanently.

GraphAware server extensions

GraphAware is a Neo4j Solution Partner that specializes in Neo4j consultancy, training, and development. They develop open-source tools and generic graph database extensions. Below, you can find more specific information about how to integrate GraphAware extensions.

Downloading GraphAware extensions

First, be sure to download a compatible version of the extension for your database. You can see all the available versions by clicking on the Older Versions link. For example, if your database is running Neo4j 2.2.4, you will need to look for a 2.2.4 version of the GraphAware extension.

Configure your GraphAware extension

Please read the extension readme file carefully. This file will contain all of the needed instructions on how to configure the extension properly.

GraphAware extensions use neo4j.properties instead of neo4j-server.properties because their extensions work both in Server as well as in Embedded mode. Luckily, you don't have to worry about selecting the right file format, because when a GraphAware plugin is detected, GrapheneDB will automatically use the appropriate properties file.

Before uploading to GrapheneDB, please ensure you have packaged the extension tarball, the neo4j.properties file, and the framework tarball (if it's required) in a valid format (zip, tar, cpio, gz, bz2 or xz).

Add your GraphAware extension

Follow the steps described in Server extensions to upload and enable the GraphAware extension.

Spatial server extension

Neo4j Spatial is a library of utilities for Neo4j that facilitates the enabling of spatial operations on data. You can learn more about Spatial from the source page: https://github.com/neo4j-contrib/spatial

Adding Spatial in Neo4j 3.0 and later

If your Neo4j version is 3.0 or later you’ll need to add it to GrapheneDB as a stored procedure. Please follow these steps:

  • Download a compatible version of Spatial. The Spatial version indicates the version of Neo4j which the extension is compatible with.
  • Navigate to the Extensions tab of your database dashboard. From the New extension drop-down menu, click on the New stored procedure button.
  • Name your stored procedure in order to be able to identify it afterwards. For example Spatial v304.
  • Select the previous downloaded Spatial .jar file from your local path and click on Add stored procedure.
  • Do not close the browser window! The upload will stop if you close your browser. If the upload fails, you can click on the Retry button to start it again.
  • When the upload completes successfully, you will see a new row in your Extensions list with the status ENABLED - PENDING.
  • Before the Spatial stored procedure can be available for use, it is necessary to restart the
    database. To perform this operation, click on the Apply changes button
  • A new window will show you a list of the changes you are going to perform. Please review them and click on Apply changes.

To check if you’ve added Spatial successfully to your database, you can list the available spatial procedures within Neo4j using the query CALL spatial.procedures

Adding Spatial in Neo4j < 3.0

If your Neo4j version is older than 3.0, you’ll need to add it to GrapheneDB as a server extension. Please follow these steps:

  • Download a compatible version of Spatial and compress the .jar file. The Spatial version indicates the version of Neo4j which the extension is compatible with.
  • Navigate to the Extensions tab of your database dashboard. From the New extension drop-down menu, click on the New server extension button.
  • Name your server extension in order to be able to identify it afterward. For example Spatial v0.15.2.
  • Select the previous downloaded compressed spatial file from your local path and click on Add server extension.
  • Do not close the browser window! The upload will stop if you close your browser. If the upload fails, you can click on the Retry button to start it again.
  • When the upload completes successfully, you will see a new row in your Extensions list with the status ENABLED - PENDING.
  • Before the Spatial stored procedure can be available for use, it is necessary to restart the database. To perform this operation, click on the Apply changes button.
  • A new window will show you a list of the changes you are going to perform. Please review them and click on Apply changes.

For some older versions of Neo4j, GrapheneDB comes out of the box with the Spatial server extension installed.

If you want to use it, you need to enable it from your Extensions area by clicking first on Enable and then on Apply changes.