<commit_before>[[ogm-neo4j]]

== Neo4j

http://www.neo4j.org[Neo4j] is a robust (fully ACID) transactional property graph database.
This kind of databases are suited for those type of problems that can be represented with a graph 
like social relationships or road maps for example.

At the moment only the support for the embedded Neo4j is included in OGM.

=== How to add Neo4j integration

.1. Add the dependencies to your project
If your project uses Maven you can add this to the pom.xml: 

[source, XML]
[subs="verbatim,attributes"]
----
<dependency>
    <groupId>org.hibernate.ogm</groupId>
    <artifactId>hibernate-ogm-neo4j</artifactId>
    <version>{hibernate-ogm-version}</version>
</dependency>
----
Alternatively you can find the required libraries in the distribution package on https://downloads.sourceforge.net/project/hibernate/hibernate-ogm/{hibernate-ogm-version}/hibernate-ogm-{hibernate-ogm-version}-dist.zip[SourceForge]

.2. Add the following properties:

[source, properties]
[subs="verbatim,attributes"]
----
hibernate.ogm.datastore.provider = neo4j_embedded
hibernate.ogm.neo4j.database_path = C:\example\mydb
----

=== Configuring Neo4j

The following properties are available to configure Neo4j support:

.Neo4j datastore configuration properties
hibernate.ogm.neo4j.database_path::
The absolute path representing the location of the Neo4j database. Example: `C:\neo4jdb\mydb`
hibernate.ogm.neo4j.configuration_resource_name (optional)::
Location of the Neo4j embedded properties file. It can be an URL, name of a classpath resource or file system path.
hibernate.schema_update.unique_constraint_strategy (optional)::
If set to `SKIP`, Hibernate OGM won't create any unique constraints on the nodes representing the entities.
This property won't affect the unique constraints generated for sequences.
Other possible values (defined on the `org.hibernate.tool.hbm2ddl.UniqueConstraintSchemaUpdateStrategy` enum) are `DROP_RECREATE_QUIETLY` and `RECREATE_QUIETLY`
but the effect will be the same (since Neo4j constraints don't have a name):
keep the existing constraints and create the missing one.
Default value is `DROP_RECREATE_QUIETLY`.

[NOTE]
====
When bootstrapping a session factory or entity manager factory programmatically,
you should use the constants defined on `org.hibernate.ogm.datastore.neo4j.Neo4jProperties`
when specifying the configuration properties listed above.

Common properties shared between stores are declared on `OgmProperties`
(a super interface of `Neo4jProperties`).

For maximum portability between stores, use the most generic interface possible.
====

[[ogm-neo4j-storage-principles]]
=== Storage principles

Hibernate OGM tries to make the mapping to the underlying datastore as natural as possible
so that third party applications not using Hibernate OGM can still read
and update the same datastore.

To make things simple, each entity is represented by a node,
each embedded object is also represented by a node.
Links between entities (whether to-one to to-many associations)
are represented by relationships between nodes.
Entity and embedded nodes are labelled `ENTITY` and `EMBEDDED` respectively.
<commit_msg>OGM-1089 Add documentation for Neo4j remote configuration<commit_after>[[ogm-neo4j]]

== Neo4j

http://www.neo4j.org[Neo4j] is a robust (fully ACID) transactional property graph database.
This kind of databases are suited for those type of problems that can be represented with a graph 
like social relationships or road maps for example.

Hibernate OGM can connect to an embedded Neo4j or a remote server.
The connection to the remote server can occur via the Bolt protocol or the HTTP API.

=== How to add Neo4j integration

.1. Add the dependencies to your project

If your project uses Maven you can add this to the pom.xml: 

[source, XML]
[subs="verbatim,attributes"]
----
<dependency>
    <groupId>org.hibernate.ogm</groupId>
    <artifactId>hibernate-ogm-neo4j</artifactId>
    <version>{hibernate-ogm-version}</version>
</dependency>
----

Alternatively you can find the required libraries in the distribution package on
https://downloads.sourceforge.net/project/hibernate/hibernate-ogm/{hibernate-ogm-version}/hibernate-ogm-{hibernate-ogm-version}-dist.zip[SourceForge]

.2. Use the following properties

If you want to use Neo4j in embedded mode:

====
[source, properties]
[subs="verbatim,attributes"]
----
hibernate.ogm.datastore.provider = neo4j_embedded
hibernate.ogm.neo4j.database_path = C:\example\mydb
----
====

If you want to connect to a remote server without authentication on localhost, you can use:

====
[source, properties]
[subs="verbatim,attributes"]
----
hibernate.ogm.datastore.provider = neo4j_bolt
----
====

or 

====
[source, properties]
[subs="verbatim,attributes"]
----
hibernate.ogm.datastore.provider = neo4j_http
----
====

The difference between `neo4j_bolt` and `neo4j_http` is that in the first case Hibernate OGM
will connect to the server using the Bolt protocol, in the second case it will use the HTTP interface.

You can select a different host, port and enable authentication with the following additional properties:

====
[source, properties]
[subs="verbatim,attributes"]
----
hibernate.ogm.datastore.provider = neo4j_bolt # or neo4j_http
hibernate.ogm.datastore.host = example.com:8989
hibernate.ogm.datastore.username = example_username
hibernate.ogm.datastore.password = <PASSWORD>
----
====

=== Configuring Neo4j

The following properties are available to configure Neo4j support:

.Neo4j datastore configuration properties
hibernate.ogm.neo4j.database_path::
The absolute path representing the location of the Neo4j database. Example: `C:\neo4jdb\mydb`
hibernate.ogm.neo4j.configuration_resource_name (optional)::
Location of the Neo4j embedded properties file. It can be an URL, name of a classpath resource or file system path.
hibernate.schema_update.unique_constraint_strategy (optional)::
If set to `SKIP`, Hibernate OGM won't create any unique constraints on the nodes representing the entities.
This property won't affect the unique constraints generated for sequences.
Other possible values (defined on the `org.hibernate.tool.hbm2ddl.UniqueConstraintSchemaUpdateStrategy` enum) are `DROP_RECREATE_QUIETLY` and `RECREATE_QUIETLY`
but the effect will be the same (since Neo4j constraints don't have a name):
keep the existing constraints and create the missing one.
Default value is `DROP_RECREATE_QUIETLY`.
hibernate.ogm.datastore.host (optional)::
The host name and the port to use when connecting to a remote server.
Default value for HTTP is `localhost:7474`.
Default value for Bolt is `localhost:7687`.
hibernate.ogm.datastore.username (optional)::
The authentication username for the remote server.
Hibernate OGM will try to authenticate only if this property is set.
hibernate.ogm.datastore.password (optional)::
The password to use when connecting remotely.

[NOTE]
====
When bootstrapping a session factory or entity manager factory programmatically,
you should use the constants defined on `org.hibernate.ogm.datastore.neo4j.Neo4jProperties`
when specifying the configuration properties listed above.

Common properties shared between stores are declared on `OgmProperties`
(a super interface of `Neo4jProperties`).

For maximum portability between stores, use the most generic interface possible.
====

[[ogm-neo4j-storage-principles]]
=== Storage principles

Hibernate OGM tries to make the mapping to the underlying datastore as natural as possible
so that third party applications not using Hibernate OGM can still read
and update the same datastore.

To make things simple, each entity is represented by a node,
each embedded object is also represented by a node.
Links between entities (whether to-one to to-many associations)
are represented by relationships between nodes.
Entity and embedded nodes are labelled `ENTITY` and `EMBEDDED` respectively.

{'fraction_non_alphanumeric': 0.08099570381602224, 'fraction_numerical': 0.009350518069244376, 'mean_word_length': 5.188428459734167, 'pattern_counts': {'":': 0, '<': 20, '<?xml version=': 0, '>': 20, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3750997', 'n_tokens_mistral': 2350, 'n_tokens_neox': 2168, 'n_words': 891}