docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/neo4j-graphoutput.adoc

////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
:documentationPath: /pipeline/transforms/
:language: en_US
:description: The Graph Output transform lets you map input fields automatically to a graph model.

= image:transforms/icons/neo4j_graph_output.svg[Neo4j Graph Output transform Icon, role="image-doc-icon"] Neo4j Graph Output

[%noheader,cols="3a,1a", role="table-no-borders" ]
|===
|
== Description

The Graph Output transform lets you map input fields automatically to a graph model.

The algorithm used to update your graph takes null values for fields mapped to primary properties of nodes into account.
These will not merge on these nodes, nor will it create or update relationships to these nodes.

|
== Supported Engines
[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
!===
!Hop Engine! image:check_mark.svg[Supported, 24]
!Spark! image:check_mark.svg[Supported, 24]
!Flink! image:check_mark.svg[Supported, 24]
!Dataflow! image:check_mark.svg[Supported, 24]
!===
|===

== Limitations

* Updates across unknown nodes `()--()` are not supported

== Modeling tips

* Try a modeler like https://neo4j.solutions/cypher-workbench[Cypher Workbench] or https://arrows.app[Arrows] and import the result into a Graph Model.
* Keep your models as simple as possible.
* Make sure that every defined node has a primary key field
* Limit yourself to one primary key field per node

== Execution tips

* Make sure that every node primary key has an index.
Use the provided button in the graph model editor to generate the Neo4j Index and Constraint actions which will handle this for you.

== Notable options

|===
|Option |Description
|Transform name|the name for this transform in the pipeline
|Neo4j connection|the Neo4j connection to write the graph to
|Graph model|the xref:metadata-types/neo4j/neo4j-graphmodel.adoc[Neo4j graph model] to use
|Batch size (rows)|batch size to use for writing data to Neo4j
|Create indexes?|create Neo4j indexes before running this transform
|Return graph data?|return graph data returned by Neo4j
|Graph output field name|the name of the field to write the graph data to (if `Return graph data?` is enabled)
|Validate against model?|validate the data against the model.
This will check if indexes are created for a field that is flagged as primary/indexed, see if a property flagged as mandatory is available when a node is updated and so on.
Uniqueness is best validated by a constraint on the property.
Use the provided button to generate the "Neo4j Constraint" action.
|Allow out of order updates?|If out of order updates are allowed, this transform generates unwind statements.
Otherwise, standard batch updates are used.
The updates are grouped per distinct generated cypher statement.

|Field to property mappings tab
|On this tab you can specify where you want the input fields to end up in the graph.
Based on your selections for this mapping the appropriate Cypher Merge statements will be executed.
You can map fields to node and relationship properties.
For the very specific cases when you want to create relationships between 2 nodes with the same label (self relationships) you can specify to which node your mapping goes: the source or target node.

|Field to relationship mappings tab
|Sometimes you want to select a relationship in your graph model based on input data.
Here are the 4 different types of relationship mappings you can apply to steer this behavior:

* `No mapping` : the line is ignored

* `Do not update relationships between specified nodes`: you can specify the source and target node labels between you don't want to update any relationships

* `Update specific relationship using field value`: You can specify the field to look at and the value to consider for the relationship you want to select.

* `Update all relationships between the specified nodes (Default)`: all the relationships between the specified source and target node, as defined in the graph model are updated (merged and properties updated).

|Node label mappings tab
|In case you want to select specific labels from the ones specified in the graph model you can create mapping entries in this tab.
Here are the node mapping types:

* `Select all defined labels (default)`: when matching/merging nodes all the labels from the graph model are selected.

* `Use a field value to select a specific label`: for the specified node we look at the input field you like and if it matches the value the label is selected to match/merge on.

* `Add the specified label if a field contains a specific value`: for the node that is selected, set the selected label if a field contains a specific value.

* `Select the first label`: for the specified node we only use the first label from the graph model to match/merge on.
|===