Getting Started

Inside IPython, load the extension:

%load_ext cypher

And then you are reay to go by using the %cypher line magic:

%cypher MATCH (a)-[]-(b) RETURN a, b

Some Cypher queries can be very long, in those cases the cell magic, %%cypher comes in handy:

%%cypher
create
    // Nodes
    (Neo:Crew {name:'Neo'}),
    (Morpheus:Crew {name: 'Morpheus'}),
    (Trinity:Crew {name: 'Trinity'}),
    // Relationships
    (Neo)-[:KNOWS]->(Morpheus),
    (Neo)-[:LOVES]->(Trinity);

Connections

By default ipython-cypher will connect to <http://localhost:7474/db/data>, but the connection string can be passed at the beginning, and referenced later on:

%%cypher https://me:mypw@myhost:7474/db/data
match (n) return n limit 1

After that, the same connection can be reused by adding the pair username and host, as in username@hostname, as the connection string:

%%cypher me@myhost
match (n) return n limit 1

Assigning alias to connections is also available, and some times, can be even better:

%%cypher https://long.host.ec2.machin.com:7474/db/data as test1
match (n) return n limit 1

Once is set, can be used as usual:

%%cypher test1
match (n) return n limit 1

In order to change the default connection string, the environment variables NEO4J_URI or NEO4J_URL can be used. In the future, to change the default connection there will be an IPython option to set it, and even a config file to define all your Neo4j servers. Soon!

Integration with Python

Queries results can be stored in a variable and then converted to other formats:

results = %cypher MATCH (a)-[]-(b) RETURN a, b

When necessary, parameters are retrieved from the current namespace:

name = "Trinity"
%cypher MATCH (a)-[]-(b) WHERE a.name={name} RETURN a, b

Furthermore, the %cypher line magic can be used in-line with Python code:

for i in range(1, 5):
    %cypher match (n) return n, n.name limit {i}

Pandas & NetworkX

Results can be converted to a Pandas DataFrame by calling the funcion get_dataframe():

results.get_dataframe()

The same can be achieved by using the lazy loading property .dataframe, but in this case default values for the creation of the DataFrame will be used:

results.dataframe

And the same applies for NetworkX MultiDiGraph. By default it will create a MultiDiGraph, but some options, such as if the graph should be directed or not, can be passed:

results.get_graph()
results.graph

These options are only functional when pandas and networkx packages are installed.

Plotting

However, we don’t always need the full power of Pandas when we just want to take a quick look at the data. For those use cases, and if matplotlib is installed, ipython-cypher includes several handy functions:

• .bar(), will plot a bar chart trying its bets guesses.
• .pie(), the same for pie charts.
• .plot(), with the deafault matplotlib line bar, but supporint the passing of any keyword argument to the matplotlib.plot function.
• .draw(), will try to draw a simple NetworkX graph if the package is installed.

Dump

Other times, just generating a simple CSV is required, and ipython-cypher includes a function to export the results of a specific query:

results.csv(filename="filename.csv")

Options

The next parameters can set by using IPython Notebook config system, CypherMagic, or by passing arguments to the run() function when using ipython-cypher outside of IPython.

• auto_html (<bool>).

  Return a D3 representation of the graph instead of regular result sets (default: False).

• auto_limit (<int>).

  Automatically limit the size of the returned result sets (default: 0).

• auto_networkx (<bool>).

  Return NetworkX MultiDiGraph instead of regular result sets (default: False).

• auto_pandas (<bool>).

  Return Pandas DataFrame instead of regular result sets (default: False).

• data_contents (<bool>).

  Bring extra data to render the results as a graph (default: True).

• display_limit (<int>).

  Automatically limit the number of rows displayed (full result set is still stored, default: 0).

• feedback (<bool>).

  Print number of rows affected (default: True).

• rest (<bool>).

  Return full REST representations of objects inside the result sets (default: False).

• short_errors (<bool>).

  Don’t display the full traceback on Neo4j errors (default: True).

• style (<unicode>).

  Set the table printing style to any of prettytable’s defined styles (currently DEFAULT, MSWORD_FRIENDLY, PLAIN_COLUMNS, RANDOM, default: u'DEFAULT').

Usage out of IPython

ipython-cypher can also be easily used outside IPython. The main function that makes this possible is cypher.run(), that takes a Cypher query string, and optional parameters for the query in a dictionary. By default, http://localhost:7474/db/data will be used, but a URL connection string to a Neo4j instance, or a cypher.run.Connection object can be passed as the last parameter:

import cypher

cypher.run("MATCH (a)-[]-(b) RETURN a, b")