# Querying Neo4J

The function `neo4j_query()` can be used to send a query to a local or remote Neo4J server. This function uses `cypher-shell` to send the query to Neo4J, and so the `cypher-shell` executable needs to be installed and available locally. See the `README` file for further information on configuration of the `cypher-shell` executable.

`neo4j_query()` takes the following arguments:

- `con` should be a list containing three elements: `address`, which should be the bolt address of the Neo4J server, and `uid` and `pwd` as login credentials
- `qry` should be a character string representing the query to be sent to Neo4J
- `shell_path` should be the full path to the `cypher-shell` executable. The default value assumes that `cypher-shell` is already in the system path. Use `path.expand()` if necessary.
- `database` specifies the database to be queried if not the default database. (For multitenancy Neo4J installations).
- `encryption` is the encryption option passed to `cypher-shell`. This may be required as explicitly `'true'` or `'false'` for older installations.

Example, assuming a local Neo4J instance running the movies graph:

    library(neo4jshell)

    neo4j_local <- list(address = "bolt://localhost", uid = "neo4j", pwd = "password")
    CQL <- 'MATCH (p1:Person {name: "Kevin Bacon"})-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(p2:Person)
            RETURN p2.name AS Name, m.title AS Title'
    cypher_path <- path.expand("~/neo4j-community-4.0.4/bin/cypher-shell")
    neo4j_query(con = neo4j_local, qry = CQL, shell_path = cypher_path)

This query should return this dataframe:

    #>         Name          Title
    #> 1 Ron Howard    Frost/Nixon
    #> 2 Rob Reiner A Few Good Men
    #> 3 Ron Howard      Apollo 13

`neo4j_query()` accepts multiple query statements separated by `;`. The function returns one of the following:

- A dataframe of results if the query is a read query. If there were multiple statements, only the results of the final statement will display.
- A message indicating successful execution if the query is a write query.
- An error message if an error occurred. If there were multiple statements, the response for all statements will be displayed.

### Note for Windows users

Paths to executable files that are provided as arguments to functions may need to be provided with appropriate extensions (eg `cypher-shell.bat`).