15.10. Cypher Shell

This section describes Neo4j Cypher Shell command-line interface (CLI) and how to use it.

This section describes the following:

15.10.1. About Cypher Shell CLI

Cypher Shell is a command-line tool that comes with the Neo4j installation. It can also be downloaded from Neo4j Download Center and installed separately.

Cypher Shell CLI is used to run queries and perform administrative tasks. It communicates via the encrypted binary protocol Bolt.

15.10.2. Syntax

The Cypher Shell CLI is located in the bin directory if installed as part of the product. The syntax is:

cypher-shell [-h] [-a ADDRESS] [-u USERNAME] [-p PASSWORD] [--encryption {true,false}] [{-d DATABASE,--database DATABASE}] [--fail-fast | --fail-at-end] [--format {verbose,plain}] [{--P PARAM,--param PARAM}] [--debug] [--non-interactive] [--sample-rows SAMPLE-ROWS] [--wrap {true,false}] [-v] [--driver-version] [{-f FILE,--file FILE}] [cypher]

Arguments

Argument Type Description Default value

cypher

Positional argument

An optional string of cypher to execute and then exit.

 

-h, --help

Optional argument

Show help message and exit.

 

--fail-fast

Optional argument

Exit and report failure on first error when reading from file.

 

--fail-at-end

Optional argument

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

 

--format {auto,verbose,plain}

Optional argument

Desired output format.

auto (default) 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.

plain displays data with minimal formatting.

--debug

Optional argument

Print additional debug information.

false

--non-interactive

Optional argument

Force non-interactive mode; only useful if auto-detection fails.

false

-v, --version

Optional argument

Print version of cypher-shell and exit.

false

-a ADDRESS, --address ADDRESS

Connection argument

Address and port to connect to.

neo4j://localhost:7687

-u USERNAME, --username USERNAME

Connection argument

Username to connect as. Can also be specified using environment variable NEO4J_USERNAME.

 

-p PASSWORD, --password PASSWORD

Connection argument

Password to connect with. Can also be specified using environment variable NEO4J_PASSWORD.

 

--encryption {true,false}

Connection argument

Whether the connection to Neo4j should be encrypted; must be consistent with Neo4j’s configuration.

true

Example 15.18. Invoke cypher-shell with username and password
$neo4j-home> bin/cypher-shell -u johndoe -p secret
Connected to Neo4j at neo4j://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 15.19. Invoke help
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
  :source   Interactively executes Cypher statements from a file
  :use      Set the active database

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

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 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"})

15.10.3. Query parameters

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

Example 15.22. 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

15.10.4. Transactions

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

Example 15.23. 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms
neo4j> :begin
neo4j# CREATE (:Person {name : 'Edward Mygma', alias : 'The Riddler' });

If you open 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

Go back to the first session and commit the transaction.

neo4j# :commit
0 rows available after 1 ms, consumed after another 0 ms
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"})                |
| (:Person {name: "Edward Mygma", alias: "The Riddler"})          |
+-----------------------------------------------------------------+
4 rows available after 1 ms, consumed after another 1 ms

neo4j>

15.10.5. Procedures

Cypher Shell supports running any procedures for which the current user is authorized.

Example 15.24. Call the dbms.showCurrentUser procedure
neo4j> CALL dbms.showCurrentUser();
+------------------------------+
| username | roles     | flags |
+------------------------------+
| "neo4j"  | ["admin"] | []    |
+------------------------------+

1 row available after 66 ms, consumed after another 2 ms
neo4j> :exit

15.10.6. Supported operating systems

You can use the Cypher Shell CLI via cmd on Windows systems, and bash on Unix systems.

Other shells may work as intended, but there is no test coverage to guarantee compatibility.