Neo4j Connector

Neo4j Connector v4.0

Anypoint Connector for Neo4j provides the capability to execute CQL statements and run basic operations, such as create, update, delete, and select nodes against a Neo4j Graph database instance.

Release Notes: Neo4j Connector Release Notes
Exchange: Neo4j Connector

Before You Begin

To use this information, you need to be familiar with Neo4j, Mule, Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

You need login credentials to test your connection to your target resource.

For software requirements and compatibility information, see the Connector Release Notes.

POM File Information

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-neo4j-connector</artifactId>
  <version>4.0.0</version>
  <classifier>mule-plugin</classifier>
</dependency>

Replace 4.0.0 with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

Metadata

Version 4.0.0 Enhancement: The Neo4j connector now provides comprehensive metadata resolution for improved Anypoint Studio experience.

Neo4j connector metadata is based on the following premises:

Dynamic Label Discovery: Labels are automatically discovered from the database using native Cypher queries
Sample-Based Field Resolution: Metadata fields are generated from actual node properties in the database
Comprehensive Type Mapping: All node properties are included in metadata, not just constraint fields
BOLT-Only Operation: All metadata resolution uses the BOLT connection (no REST API required)

For optimal metadata experience: * Ensure sample data exists in your Neo4j database for the labels you plan to use * The connector will display all properties found in sample nodes for comprehensive field suggestions * Metadata is generated dynamically and reflects the actual data structure in your database

Add the Connector to a Studio Project

Anypoint Studio provides two ways to add the connector to your Studio project: from the Exchange button in the Studio taskbar or from the Mule Palette view.

Add the Connector Using Exchange

In Studio, create a Mule project.
Click the Exchange icon (X) in the upper-left of the Studio task bar.
In Exchange, click Login and supply your Anypoint Platform username and password.
In Exchange, search for "neo4j".
Select the connector and click Add to project.
Follow the prompts to install the connector.

Add the Connector in Studio

In Studio, create a Mule project.
In the Mule Palette view, click (X) Search in Exchange.
In Add Modules to Project, type "neo4j" in the search field.
Click this connector’s name in Available modules.
Click Add.
Click Finish.

Configure in Studio

Drag a Neo4j operation to the Studio Canvas.

Select the operation.

List of available operations in Studio for Neo4j connector

Name	Description
Execute	Execute any CQL statement against DB.
Create Node	Create a node with a specific initial label. Optionally, properties for the node can be added.
Select Nodes	Query nodes with a specific label. Optionally, properties used as filter can be provided.
Update Nodes	Modified properties for one or multiple nodes with a specific label. Optional Properties can be added as search filter criteria.
Delete Nodes	Delete one or multiples nodes based on a specific label. This lets you delete nodes with inbound/outbound relationships. Optional Properties can be added as search filter criteria.

Name

Description

Execute

Execute any CQL statement against DB.

Create Node

Create a node with a specific initial label. Optionally, properties for the node can be added.

Select Nodes

Query nodes with a specific label. Optionally, properties used as filter can be provided.

Update Nodes

Modified properties for one or multiple nodes with a specific label. Optional Properties can be added as search filter criteria.

Delete Nodes

Delete one or multiples nodes based on a specific label. This lets you delete nodes with inbound/outbound relationships. Optional Properties can be added as search filter criteria.

Note: The Neo4j connector’s basic operations can filter nodes by only one label in its query. If you want to filter in a query by multiple labels, use the Execute operation with a proper CQL statement.

Configure the Global element for the connector.

Field	Description
Username	Enter the username to log in with.
Password	Enter the corresponding password.
BOLT URL	Bolt endpoint URL. Version 4.0.0: This is the only required connection parameter.

Field

Description

Username

Enter the username to log in with.

Password

Enter the corresponding password.

BOLT URL

Bolt endpoint URL. Version 4.0.0: This is the only required connection parameter.

Use Case: Node Basic CRUD

Studio flow with Listener, Transform Message, Create node, Select nodes, Delete node, and Transform Message

Create a new Mule Project in Anypoint Studio and set your Neo4j environment properties in src/main/resources/automation-credentials.properties.
```
config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDOPOINT>
```
Drag an HTTP connector onto the canvas and configure it with the default values.
Drag a Transform Message onto the canvas and create a flowVar called params with the following code:
```
%dw 2.0
%output application/json
---
{
	"name":"Tom Hanks",
	"born": 1956
}
```
Drag the Neo4j connector onto the canvas and configure a new global element according to the table below:

Parameter Value

Username

${neo4j.username}

Password

${neo4j.password}

BOLT URL

${neo4j.boltUrl}
```
<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
	<neo4j:connection username="${config.username}"
	password="${config.password}"
	boltUrl="${config.boltUrl}" />
</neo4j:config>
```
In the Properties Editor, configure:

Parameter Value

Display Name

Create node

Connector Configuration

Neo4j__Basic_Authentication

Operation

Create node

Label

Person

Parameters Reference

#[payload]

Note: Click Test Connection to confirm that Mule can connect with the Neo4j instance. If the connection is successful, click OK to save the configuration. Otherwise, review or correct any invalid parameters and test again.
Drag a Neo4j connector onto the canvas, in the Properties Editor, configure the parameters:

Parameter Value

Operation

Select nodes

Label

Person
Drag a Neo4j connector onto the canvas, in the Properties Editor, configure the parameters:

Parameter Value

Operation

Delete nodes

Label

Person

Parameter	Value
Username	`${neo4j.username}`
Password	`${neo4j.password}`
BOLT URL	`${neo4j.boltUrl}`

Parameter	Value
Display Name	Create node
Connector Configuration	Neo4j__Basic_Authentication
Operation	Create node
Label	Person
Parameters Reference	`#[payload]`

Parameter	Value
Operation	Select nodes
Label	Person

Parameter	Value
Operation	Delete nodes
Label	Person

Drag an Transform Message onto the canvas.

%dw 2.0
%output application/json
---
payload

Save the changes and deploy the project as a Mule Application. Open a browser and make a request to the following URL:
```
http://localhost:8081/CRUD
```
If the node was successfully created and deleted, information displays in a JSON format:
```
{"born":1956,"name":"Tom Hanks"}
```

Create a Node with Multiple Labels

Studio flow with Listener, Transform Message, Create node, Select node, and Transform Message

Create a new Mule Project in Anypoint Studio and set your Neo4j environment properties in src/main/resources/automation-credentials.properties.
```
config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDOPOINT>
```
Drag an HTTP connector onto the canvas and configure it with the default values.

Drag a Transform Message onto the canvas and create two flowVars with the following code:

Variable-create

%dw 2.0
%output application/json
---
"CREATE (a:ACTOR:PERSON { name:\"Tom Hanks\", born:1956 })"

Variable-select

%dw 2.0
%output application/json
---
"MATCH (a:ACTOR:PERSON) RETURN a"

Drag the Neo4j connector onto the canvas and configure a new Global Element according to the table below:

Parameter Value

Username

${neo4j.username}

Password

${neo4j.password}

BOLT URL

${neo4j.boltUrl}
```
<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
	<neo4j:connection username="${config.username}"
	password="${config.password}"
	boltUrl="${config.boltUrl}" />
</neo4j:config>
```

Parameter	Value
Username	`${neo4j.username}`
Password	`${neo4j.password}`
BOLT URL	`${neo4j.boltUrl}`

In the Properties Editor, configure:

Parameter Value

Parameter	Value
Display Name	Create node (advanced)
Connector Configuration	Neo4j__Basic_Authentication
Operation	Execute
Query	`#[vars.create]`
Parameters Reference	`#[payload]`

Display Name

Create node (advanced)

Connector Configuration

Neo4j__Basic_Authentication

Operation

Execute

Query

#[vars.create]

Parameters Reference

#[payload]

Create node properties configuration window

Click Test Connection to confirm that Mule can connect with the Neo4j instance. If the connection is successful, click OK to save the configuration. Otherwise, review or correct any invalid parameters and test again.

Drag a Neo4j connector onto the canvas, in the Properties Editor, configure the parameters:

Parameter Value

Display Name

Select node (Multi-label)

Operation

Execute

Query

#[vars.select]
Drag a Transform Message onto the canvas.
Drag a Logger onto the canvas.
Save the changes and deploy the project as a Mule Application. Open a browser and make a request to the following URL:
```
http://localhost:8081/createNodeMultiLabel
```
If the node was successfully created and deleted, information displays in a JSON format:
```
[{"a":{"born":1956,"name":"Tom Hanks"}}]
```

Parameter	Value
Display Name	Select node (Multi-label)
Operation	Execute
Query	`#[vars.select]`

Use Case: XML

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:neo4j="http://www.mulesoft.org/schema/mule/neo4j"
	xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
	xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
	http://www.mulesoft.org/schema/mule/http
	http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
	http://www.mulesoft.org/schema/mule/ee/core
	http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
	http://www.mulesoft.org/schema/mule/neo4j
	http://www.mulesoft.org/schema/mule/neo4j/current/mule-neo4j.xsd">
	<http:listener-config name="HTTP_Listener_config"
	doc:name="HTTP Listener config" basePath="/" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
		<neo4j:connection username="${config.username}"
		 password="${config.password}" boltUrl="${config.boltUrl}" />
	</neo4j:config>
	<flow name="CRUD" >
		<http:listener doc:name="Listener"
		 config-ref="HTTP_Listener_config" path="/CRUD"/>
		<ee:transform doc:name="Transform Message" >
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
	"name":"Tom Hanks",
	"born": "1956"
}]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<neo4j:create-node label="Person" doc:name="Create node"
		 config-ref="Neo4j_Config" input="#[payload]"/>
		<neo4j:select-nodes label="Person" doc:name="Select nodes"
		 config-ref="Neo4j_Config" input="#[payload]"/>
		<neo4j:delete-nodes label="Person" doc:name="Delete nodes"
		 config-ref="Neo4j_Config" parameters="#[payload]"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
	<flow name="createNodeWithMultiLabels">
		<http:listener doc:name="Listener"
		config-ref="HTTP_Listener_config"
		path="/createNodeMultiLabel"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{

}]]></ee:set-payload>
			</ee:message>
			<ee:variables >
				<ee:set-variable variableName="select" ><![CDATA[%dw 2.0
output application/json
---
"MATCH (a:ACTOR:PERSON) RETURN a"]]></ee:set-variable>
				<ee:set-variable variableName="create" ><![CDATA[%dw 2.0
output application/json
---
"CREATE (a:ACTOR:PERSON { name:\"Tom Hanks\", born:1956 })"]]></ee:set-variable>
			</ee:variables>
		</ee:transform>
		<neo4j:execute doc:name="Create node (advanced)" config-ref="Neo4j_Config" input="#[payload]">
			<neo4j:query ><![CDATA[#[vars.create]]]></neo4j:query>
		</neo4j:execute>
		<neo4j:execute doc:name="Select node (Multi-label)"  config-ref="Neo4j_Config">
			<neo4j:query ><![CDATA[#[vars.select]]]></neo4j:query>
		</neo4j:execute>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
</mule>

Upgrading from Version 3.x

Important: Version 4.0.0 contains breaking changes. If you are upgrading from version 3.x, see Neo4j Connector Upgrade and Migration Guide for detailed migration instructions.

Key Changes in Version 4.0.0: * REST URL parameter removed: Only BOLT URL is required for configuration * Enhanced metadata resolution: Comprehensive field suggestions in Anypoint Studio * Minimum requirements updated: Neo4j 4.4+, JDK 17+, Mule Runtime 4.9.0+ * Modern Neo4j driver: Upgraded to Neo4j Java Driver 5.28.8 * Code quality enhancements: Improved error handling, modern Java 17+ features, and better internal architecture