neo4k

Table of Contents

Motivation and Design Guide
- Intended Use-Cases
- Use-Cases Definitely NOT Considered
User Guide
- Maven
- Gradle
Getting Started
Developers Guide

Neo4j wrapper for Kotlin, supporting same interface for embedded and bolt drivers.

Motivation and Design Guide

Create a Kotlin friendly wrapper for accessing Neo4j
Support Neo4j Embedded and Bolt drivers directly
Same neo4j interface working with Embedded or Bolt drivers
No other frameworks (no Spring or neo4j-ogm)
Apoc library helpers for graph data hydration from SQL, CSV, and JSON sources
Exploring simpler syntax sugar ways to increase productivity of working with Neo4j cypher queries and responses

Intended Use-Cases

Easy way to add Neo4j capabilities (primarily embedded) into a micro-service for graph hydration and querying.

At this time the objective is for low risk use-cases, such as caching data in a GraphQL server or allowing for simple analytics/reporting (i.e. given read access to multiple databases)

Use-Cases Definitely NOT Considered

Large scale or high performance data graph projects
Master of truth production database use

At this time the project is not focused or mature enough to be used for mission critical 'master of truth' production use-cases. Do so at your own risk.

User Guide

Maven

    <dependency>
        <groupId>me.roybailey</groupId>
        <artifactId>neo4k-api</artifactId>
        <version>0.2.0</version>
    </dependency>

Gradle

implementation("me.roybailey:neo4k-api:0.2.0")

Getting Started

Table 1. Design Concepts and Noteworthy Classes

Noteworthy Class/Concept	Description
`CypherDsl`	common cypher commands or cypher construction utilities (can be used independently of everything else with dependency `neo4k-dsl`)
`QueryStatement`	utility object for loading cypher queries from AsciiDoc/Markdown or regular text files
`Neo4jService`	the low-level neo4j driver interface, through which all cypher is executed
`Neo4jServiceRecord`	the low-level neo4j record returned from running cypher queries, standardised for both embedded and bolt responses

Creating an embedded instance of a Neo4j Service

Create an embedded instance using the file:// uri.

    // load propoerties for neo4j service
    val options = Neo4jServiceOptions(
                        neo4jUri = "file://./target/neo4j/Neo4jServiceEmbeddedTest-{timestamp}",
                        boltPort = 7987
                    )
    vak neo4jService = Neo4jService.getInstance(options)

The embedded service reads neo4j specific properties from /neo4j.conf on the classpath. Below are some examples of what might be in this config file. See Neo4j documentation for complete list.

# these properties allow us to control the transaction log handling, reduce disk space usage
dbms.tx_log.rotation.retention_policy=1 files
dbms.checkpoint.interval.time=1m
dbms.memory.heap.initial_size=2000

# these properties are not used by Neo4j but are custom properties to activate bolt connector to embedded database
# when active it means you can access your embedded database from a local Noe4j Browser session
# neo4j.bolt.connector.port=7887

apoc.jdbc.TESTH2.url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1

apoc.import.file.enabled=true

Creating a remote bolt instance of Neo4j Service

Create a remote bolt instance using the bolt:// uri

    // load propoerties for neo4j service
    val options = Neo4jServiceOptions(
                        neo4jUri = "bolt://localhost",
                        boltPort = 7987
                    )
    vak neo4jService = Neo4jService.getInstance(options)

Options for configuring Neo4j Service adaptor

Table 2. Neo4jService Options

Properties	Description	Example value
`neo4jUri`	the neo4j connection uri (either starting `file:` for embedded or `bolt:` for remote connection	e.g. `bolt://localhost:7987`
`boltPort`	port to connect to bolt or to expose embedded to bolt (for viewing embedded via Neo4j browser)	e.g. `7987`
`username`	neo4j username (required for bolt connections)	e.g. `neo4j`
`password`	neo4j password (required for bolt connections)	e.g default from neo4j install is `neo4j`
`neo4jProcedures`	neo4j procedures to register (embedded) or verify (bolt)
`ignoreErrorOnDrop`	ignores errors from cypher commands that try to drop indexes that don’t exist
`ignoreProcedureNotFound`	ignores failed neo4j procedure registrations or verifications

Connecting to the embedded instance from Neo4j Browser

make sure you are running in embedded mode and assign a unique port e.g. boltPort=7987
run command :server disconnect in the neo4j browser
enter bolt://<machine>:<port> in the connection URL field e.g. bolt://localhost:7987
leave username and password blank

This should get you connected to your running embedded database and allow you to query it using the browser.

`CypherDsl`

CypherDsl Documentation

`QueryStatement` utilities

Utility object for loading cypher queries from AsciiDoc/markdown or regular text files. For example…

        val statements:List<QueryStatement> = QueryStatement.parseQueryScriptStatements("""

            // query movie by title
            match (m:Movie { title: ${'$'}title }

            // query movie by title since released date
            match (m:Movie { title: ${'$'}title }
            where m.released > ${'$'}released

            // Create indexes
            CREATE INDEX ON :Product(productID);
            CREATE INDEX ON :Category(categoryID);

        """.trimIndent())

Above statements list has 4 entries, one for each cypher statement. Parser uses comments (becomes the description) or semi-colons to separate statements.

Developers Guide

Table 3. Modules

Module	Description
`neo4k-testdata`	CSV and JSON test data generator module. Generates test data files for loading through Cypher. Internal only, outputs files to `testdata/generator` folder.
`neo4k-dsl`	Cypher DSL. Cypher construction kit for loading from AsciiDoc/Markdown/Text files, or constructing in code with DSL like blocks.
`neo4k-api`	Main Embedded and Bolt service adaptor and result processing objects.
`neo4k-reporting`	Reporting module for processing results and converting into CSV/PDF/XLS reports.
`neo4k-springboot`	Working example of pulling it all together into a springboot application.

Neo4jService adaptor is intended to standardise across Bolt and Embedded drivers and therefore the project needs an instance of Neo4j to be running for the build. This is so all the capabilities can be tested against both embedded and bolt instances.

The project uses Neo4j TestContainer to create an instance of Neo4j Graph Database during the build, for testing bolt compatibility.

Standard test suites are captured in interfaces (with default implementations) so that different drivers can be tested to pass the exact same tests. See neo4k-api test packages.

Installing and configuring Neo4j graph database

If you wish to play with your own remote instance of Neo4j using some of the tests you’ll need to configure it correctly.

Install your own instance of Neo4j Graph Database (check for compatible version used in project)
Suggest changing the Neo4j Graph Database port to something else e.g. 7987 (open conf/neo4j.conf or Manage > Settings in your Neo4j Desktop project)
Add the apoc jar into the neo4j plugins folder (you can get the version from the pom.xml and copy the jar from the local maven repository)
Add the h2 database jar into the neo4j plugins folder (you can get the version from the pom.xml and copy the jar from the local maven repository)
Comment out the setting to restrict import folder access

Warning : Database will be cleared with every test, hence the project should not use the default port

Installing h2 database plugin

Find the neo4j database instance plugins folder e.g.

cp ~/.m2/repository/com/h2database/h2/1.4.196/h2-1.4.196.jar <neo4j-installation-folder>/plugins

If you’re using an instance of Neo4j Desktop, goto your graph project and select 'manage' from the graph instance. At the top there is an 'Open Folder' button, which will take you to the installation folder and you should find 'plugins' folder under there.

Note : if you get an error after adding the h2 jar to the plugins folder, check the neo4j.log file for errors. Could be you need an older version of h2 to run on the Neo4j JVM version.

Configuring the Neo4j remote instance for testing Bolt support

In the remote Neo4j database instance, there are several settings you need to override to allow the tests to pass. You do this by editing the conf/neo4j.conf in your installation folder, or through 'Manage' > 'Settings' in your designated Neo4j Desktop Project.

Change the bolt port (recommend changing the others to avoid clashes with default installations you might have elsewhere)

dbms.connector.bolt.listen_address=:7987
dbms.connector.http.listen_address=:7974
dbms.connector.https.listen_address=:7973

Allow import files to be accessed from anywhere by commenting out the restriction setting.

# This setting constrains all `LOAD CSV` import files to be under the `import` directory. Remove or comment it out to
# allow files to be loaded from anywhere in the filesystem; this introduces possible security problems. See the
# `LOAD CSV` section of the manual for details.
# dbms.directories.import=import

Building the project

mvn clean install

roybailey / neo4k Goto Github PK

neo4k's Introduction