10.9. Cypher Shell

This section describes the Neo4j Cypher Shell.

Cypher Shell is a command-line tool that is installed as part of the product. You can connect to a Neo4j database and use Cypher to query data, define schema or perform administrative tasks. Cypher Shell exposes explicit transactions allowing multiple operations to be grouped and applied or rolled back together. Cypher Shell communicates via the encrypted binary protocol Bolt.

10.9.1. Invoking Cypher Shell

Cypher Shell is located in the bin directory and is invoked with a set of arguments.

cypher-shell [-h] [-a ADDRESS] [-u USERNAME] [-p PASSWORD] [--encryption {true,false}] [--format {verbose,plain}] [--debug] [--non-interactive] [-v] [--fail-fast | --fail-at-end] [cypher]

Arguments

Positional arguments:

 

cypher

An optional string of cypher to execute and then exit.

Optional arguments:

 

-h, --help

Show help message and exit.

--fail-fast

Exit and report failure on first error when reading from file (this is the default behavior).

--fail-at-end

Exit and report failures at end of input when reading from file.

--format {auto,verbose,plain}

Desired output format. auto displays results in tabular format if you use the shell interactively and with minimal formatting if you use it for scripting. verbose displays results in tabular format and prints statistics and plain displays data with minimal formatting (default: auto).

--debug

Print additional debug information (default: false).

--non-interactive

Force non-interactive mode; only useful if auto-detection fails (default: false).

-v, --version

Print version of cypher-shell and exit (default: false).

Connection arguments:

 

-a ADDRESS, --address ADDRESS

Address and port to connect to (default: bolt://localhost:7687).

-u USERNAME, --username USERNAME

Username to connect as. Can also be specified using environment variable NEO4J_USERNAME (default: ).

-p PASSWORD, --password PASSWORD

Password to connect with. Can also be specified using environment variable NEO4J_PASSWORD (default: ).

--encryption {true,false}

Whether the connection to Neo4j should be encrypted; must be consistent with Neo4j’s configuration (default: true).

Example 10.14. Invoke Cypher Shell with username and password
$neo4j-home> bin/cypher-shell -u johndoe -p secret
Connected to Neo4j at bolt://localhost:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j>
Example 10.15. Invoke help from within Cypher Shell
neo4j> :help
Available commands:
  :begin    Open a transaction
  :commit   Commit the currently open transaction
  :exit     Exit the logger
  :help     Show this help message
  :history  Print a list of the last commands executed
  :param    Set the value of a query parameter
  :params   Prints all currently set query parameters and their values
  :rollback Rollback the currently open transaction

For help on a specific command type:
    :help command
Example 10.16. Execute a query from within Cypher Shell
neo4j> MATCH (n) RETURN n;
+-----------------------------------------------------------------+
| n                                                               |
+-----------------------------------------------------------------+
| (:Person {name: "Bruce Wayne", alias: "Batman"})                |
| (:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]}) |
+-----------------------------------------------------------------+
Example 10.17. Invoke Cypher Shell with a Cypher script from the command line

Below is the contents of a file called examples.cypher:

MATCH (n) RETURN n;

MATCH (batman:Person {name: 'Bruce Wayne'}) RETURN batman;

Invoke the 'examples.cypher' script from the command-line. All the examples in the remainder of this section will use the --format plain flag for a simple output.

$neo4j-home> cat examples.cypher | bin/cypher-shell -u neo4j -p secret --format plain
n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
batman
(:Person {name: "Bruce Wayne", alias: "Batman"})

10.9.2. Query parameters

Cypher Shell supports querying based on parameters. This is often used while scripting.

Example 10.18. Use parameters within Cypher Shell

Set the parameter 'thisAlias' to 'Robin' using the ':param' keyword. Check the parameter using the ':params' keyword.

neo4j> :param thisAlias => 'Robin'
neo4j> :params
:param thisAlias => 'Robin'

Now use the parameter 'thisAlias' in a Cypher query. Verify the result.

neo4j> CREATE (:Person {name : 'Dick Grayson', alias : {thisAlias} });
Added 1 nodes, Set 2 properties, Added 1 labels
neo4j> MATCH (n) RETURN n;
n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
(:Person {name: "Dick Grayson", alias: "Robin"})

10.9.3. Transactions

Cypher Shell supports explicit transactions. Transaction states are controlled using the keywords :begin, :commit, and :rollback:

Example 10.19. Use fine-grained transaction control

Start a transaction in your first Cypher Shell session:

neo4j> MATCH (n) RETURN n;
n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
(:Person {name: "Dick Grayson", alias: "Robin"})
neo4j> :begin
neo4j# CREATE (:Person {name : 'Edward Mygma', alias : 'The Riddler' });
Added 1 nodes, Set 2 properties, Added 1 labels

If you now open up a second Cypher Shell session, you will notice no changes from the latest CREATE statement:

neo4j> MATCH (n) RETURN n;
n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
(:Person {name: "Dick Grayson", alias: "Robin"})

Go back to the first session and commit the transaction:

neo4j# :commit
neo4j> MATCH (n) RETURN n;
n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
(:Person {name: "Dick Grayson", alias: "Robin"})
(:Person {name: "Edward Mygma", alias: "The Riddler"})
neo4j>

10.9.4. Procedures

Cypher Shell supports running any procedures for which the current user is authorized. Here, we are using the natively built-in procedure dbms.showCurrentUser().

Example 10.20. Call a procedure from within Cypher Shell
neo4j> CALL dbms.showCurrentUser();
username, roles, flags
"johndoe", ["admin"], []
neo4j> :exit