Running multi-line cypher script via CLI is a good middle level approach between starting out and a full deployment solution.

Quick Start for cypher-shell (TL;DR)

1. Fire up Neo4j Desktop (for Mac OS X) and run your database
2. Click “Manage” for the active database card then “Open Terminal” which will take you to the corresponding directory
3. Run $ bin/cypher-shell -a bolt://localhost:7687 -u username -p password replacing “username” and “password” with your db un and pw.
4. Alternatively, you can set the file path if you are running terminal from your code editor – $ /Users/username/Library/Application\ Support/Neo4j\ Desktop/Application/neo4jDatabases/database-xxxx-xxxx/installation-4.1.1/bin/cypher-shell -a bolt://localhost:7687 -u neo4j -p password
5. To run your multi-line script, save as a .cypher or .txt file, separating lines with semicolons
6. Run $ cat /<your file-path>/<script name>.cypher | bin/cypher-shell -u username -p password
7. Check your Neo4j Desktop Browser for corresponding updates

Key notes and some gotchas

• For Mac OS X, you’ll need to install Java 8
• For PC, it’s my understanding you’ll need PowerShell
• If you see something like zsh: command not found: cypher-shell you may be in the wrong directory you’re looking to be in your installation-<version> folder that contains bin or that bin folder
• If your script runs the same commands multiple times, change the naming conventions so you can identify errors – the logs will say line 6, but it could mean line 6 of any of your CQL blocks
• When troubleshooting, make sure you’re looking at info on “cypher-shell” NOT “neo4j-shell” which is deprecated.

When should you start using the command line?

When to use cypher-shell on local

When you’ve outgrown Neo4j Desktop Browser UI but aren’t ready for deployment with Neo4j Server

The Neo4j Desktop Browser UI is intended for local development when you’re starting out. At a certain point, you’re ready to deploy, and migrate from using a Desktop instance to a Server instance.

With Desktop UI, we’re limited to running one query at a time. Initially, this is fine. But pretty quickly you can get to a point of having outgrown single line commands, but not being ready for full blown deployment.

Where using cypher-shell shines

A couple situations where the Desktop browser UI can get time consuming and super inefficient:

1. when we’re trying to QA our data modeling to database writes loading data from multiple CSVs
2. when you want to map columns of data into different properties of different types of nodes and relationships between nodes
3. when you’re doing anything repetitive – as in the case with me wanting to load crawl data from different websites into Neo4j quickly and seamlessly

If you’re working from Neo4j Desktop UI exclusively, you’ll find yourself favoriting scripts, moving them around in folders, constantly hitting the play button, editing file paths, etc., as needed, basically looping manually through the same ten steps with minor variations running single line commands

If something doesn’t do what we wanted, there’s no “undo” button, we have to wipe the db with a “MATCH (n) DETACH DELETE n” and start over from step 1.

The reason for this post

Existing info on Neo4j Desktop from command line is a bit light

As a caveat, if I was a more experienced dev, this all might have been super easy and intuitive but it took some time so I wanted to document.

I’ve found Neo4j docs, dev community, tutorials, the whole ecosystem to be super robust. There’s A LOT.

In addition, Neo4j is now a mature technology with a long history of versions. Because of that lots of variations on similar info exists and if you’re just getting started with graphs, you might not have a clear picture on the context/history or what tutorials from what time periods correspond to what version(s) or scenarios.

Cypher-shell lets you get quickly up and running with multiple cypher commands for loading data

The example we’re using is loading data as nodes and relationships from multiple CSVs, with lots of empty cells, when we want to model data from CSV columns in a non-linear way.

A lot of tutorials exist to show you how to take a CSV, load each row as a node, each column as a property for those nodes, and then maybe load another CSV that uses the same identifier to add relationships for those nodes.

But often you want to take linear data within a CSV and model columns as properties of nodes or relationships, or related nodes.

What are the other options?

• There are a bunch of drivers
• You can import JSON data from a REST API
• You can load CSV data directly
• Neo4j ETL Tool is a one click install graph application, it’s best use case (from what I can tell) is for migrating/remodeling SQL data
• This how-to on migrating a relational database to Neo4j provides a good summary of options for transforming and loading very well

cypher-shell is perfecrt for PoCs

I’m still in PoC mode for the graph content audit, so running multi-line scripts from the command line is a good, lean way for me for my current purposes.

As soon as I get to a point where I want to any of the following, it will be time for me to move on to the Python Driver for Neo4j – which I’m already loving.:

• preprocess or mutate CSVs before loading into Neo4j
• load data directly from a Google Spreadsheet
• conditionally load scripts for different purposes

To get a great overview of some options for loading data and working with Cypher beyond desktop UI, check out William Lion’s 2017 talk, “Working With a Real-World Dataset in Neo4j – Import and Modeling” that’s available on Youtube.

It runs through loading json data a variety of ways, including via the Python driver and multi-line cypher through shell. Here’s that part of the video.

How to use cypher shell to run .cypher or .txt scripts

LOAD CSV in the Neo4j Desktop browser UI is great. But for testing purposes, since you can only run one query at a time, creating multi-query scripts with .cypher file extension and then running them on the command line can really speed up the process of running your tests and streamlining data imports.

From the docs, there is a comprehensive list of options, these are the ones we’ll need today:

cypher-shell [-h]
    [-a ADDRESS]
    [-u USERNAME]
    [-p PASSWORD]
    [{-d DATABASE,--database DATABASE}]
    [-v] 
    [{-f FILE,--file FILE}]
    [cypher]

Some starting notes

Old info on the web

A deprecated approach to running cypher from command line exists out there called “neo4j-shell.” If you see tutorials or snippets for that, ignore it and make sure anything you read/search references “cypher-shell.”

Dependencies

Of course, you’ll need Neo4j Desktop or Server (and either Community or Enterprise editions)- I read a few places that you needed Enterprise, this is not true.

At least for Mac OS X/Linux, JVM 1.8 is a dependency for running cypher-shell.

If you don’t have JDK8, you can download it from Oracle. JDK is Java Development Kit, JVM means Java Virtual Machine. As far as I understand, having the right version of JDK means a 1.8 instance of a JVM is spun up on the fly when running “cyper-shell”

Connecting to Neo4j database

To start, open Neo4j Desktop, choose your database and hit play to spin up your environment. From there, you’ll see the card for your selected database have a green circle showing it’s running and a browser window will pop up:

You can see our “es v3” card is “Active,” above and you’ll also notice our Neo4j Browser opens automatically, which we’ll get to next.

Get your coptions from Neo4j Desktop

To quickly find the info you’ll need for starting and using cypher-shell, start your database and click “Manage” on the active database.

This gives us a nice list of shortcut options:

This is worth taking note of. Most everything we need to run cypher-shell options is quickly accessible from the db card details, including:

• “Open Folder” (this will show you the following directory in Finder, you can grab and use in your CLI of choice)
• “Open Terminal” (this will take you to the following directory in Terminal, removes a step if you plan to use that)
• “Open Browser” (if you happen to close the browser, this is how you re-open
• In “Details” tab, the bolt port (with little copy icon button)
• In “Administration” tab, you can reset your db password if you forgot it

We also need our db username. By default this should be “neo4j” but if it isn’t, or you changed it and can’t remember, you can check in your browser window, which looks like this:

From top left database information icon, if you scroll to the bottom on the left-hand sidebar, you’ll see the “Connected as” “Username” as well as other connection and DBMS info:

Now that we know where everything is, we’re ready to run cypher-shell and connect to our db.

Open your CLI

On a Mac, you can use Terminal or your code editor’s command line interface.

Aside: I also read somewhere that on a PC, you’ll need PowerShell.

Let’s change directory into our target file path by either grabbing the file path when we hit “Open Folder:”

$ cd /Users/<your mac username>/Library/Application Support/Neo4j Desktop/Application/neo4jDatabases/database-xxxx-xxxx-xxxx/installation-3.5.14

You’ll also skip this step if you instead click, “Open Terminal.”

Once there you’ll need to know which database instance you want to connect to, for me this looked like:

Desktop/Application/neo4jDatabases/database-xxxx-xxxx/installation-3.5.14/data/databases/graph.db

To connect, we just need to run the following when in our ../Application/neo4jDatabases/database-xxxx-xxxx/installation-3.5.14 directory:

bin/cypher-shell
    [-a ADDRESS] # (defaults to bolt://localhost:7687)
    [-u USERNAME]
    [-p PASSWORD]

That will look something like this with your db credentials:

$ cypher-shell -a bolt://localhost:7687 -u neo4j -p password

Aside: If you get an alert that it couldn’t find any JVM 1.8s, go back up to the top of this tutorial and follow instructions to install.

If successful, you should see something like:

Connected to Neo4j 3.5.14 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.

At this point, we’re ready to roll. You can run any cypher command once you see the “neo4j >” in your CLI.

We can now run cypher from the command line as long as our command ends in a semicolon. Let’s test by running “create (n) return n;”

$ create (n) return n;
+----+
| n |
+----+
| () |
+----+

1 row available after 83 ms, consumed after another 10 ms
Added 1 nodes

Now we go over to our blank db and look for the node:

We did it! Now we can really cruise.

Running multi-line scripts with cypher-shell

Let’s take all our cypher statements, load them into a code editor and save the file with a .cypher extension. Then we can run multiple queries without executing them one by one.

Here’s the format:

$ cat /<your-file-path>/<script-name>.cypher | bin/cypher-shell -u username -p password

Even though we are running a series of statements, they still get piped in one by one synchronously.

Dealing with errors

If you have an error in your third block, the first two blocks still execute. Then, when you get an error, Neo4j is great at telling you the line and column for the error’d query, but not great at telling you the line in your file. Instead it tells you the line number counting zero as the beginning of the errored query.

For example, this error is on line 113 of my file, but cypher-shell returns the line as 6 because it’s the sixth line from the start of that third statement.

Invalid use of MATCH inside FOREACH (line 6, column 9 (offset: 201))
"        MATCH (u:URL {address: sfia.`Address`})"
         ^

So you’ll want to account for the offset to find the location of the issue when troubleshooting. And if you’re like me and re-using lines, you’ll want to vary your naming conventions so you don’t get tripped up finding the issue.

Hope that helps!