Cypher

Cypher is to Neo4j as SQL is to relational databases. It is a declarative language that provides facilities to query and manipulate data within a graph database using a syntax which is both quick to learn and easy to read.

Note

In py2neo 1.6.0, execution functions in the cypher module were deprecated and replaced by the CypherQuery class from the neo4j module. From version 1.6.1 onwards, the entire cypher module has been repurposed and now contains new support for Cypher transactions, as introduced in Neo4j 2.0.

Cypher Transactions

Cypher transactions were introduced in Neo4j 2.0 and allow multiple statements to be executed within a single server transaction.

from py2neo import cypher

session = cypher.Session("http://localhost:7474")
tx = session.create_transaction()

# send three statements to for execution but leave the transaction open
tx.append("MERGE (a:Person {name:'Alice'}) "
          "RETURN a")
tx.append("MERGE (b:Person {name:'Bob'}) "
          "RETURN b")
tx.append("MATCH (a:Person), (b:Person) "
          "WHERE a.name = 'Alice' AND b.name = 'Bob' "
          "CREATE UNIQUE (a)-[ab:KNOWS]->(b) "
          "RETURN ab")
tx.execute()

# send another three statements and commit the transaction
tx.append("MERGE (c:Person {name:'Carol'}) "
          "RETURN c")
tx.append("MERGE (d:Person {name:'Dave'}) "
          "RETURN d")
tx.append("MATCH (c:Person), (d:Person) "
          "WHERE c.name = 'Carol' AND d.name = 'Dave' "
          "CREATE UNIQUE (c)-[cd:KNOWS]->(d) "
          "RETURN cd")
tx.commit()
class py2neo.cypher.Session(uri=None)[source]

A Session is the base object from which Cypher transactions are created and is instantiated using a root service URI. If unspecified, this defaults to the DEFAULT_URI.

>>> from py2neo import cypher
>>> session = cypher.Session("http://arthur:excalibur@camelot:9999")
create_transaction()[source]

Create a new transaction object.

>>> from py2neo import cypher
>>> session = cypher.Session()
>>> tx = session.create_transaction()
Returns:new transaction object
Return type:Transaction
execute(statement, parameters=None)[source]

Execute a single statement and return the results.

class py2neo.cypher.Transaction(uri)[source]

A transaction is a transient resource that allows multiple Cypher statements to be executed within a single server transaction.

append(statement, parameters=None)[source]

Append a statement to the current queue of statements to be executed.

Parameters:
  • statement – the statement to execute
  • parameters – a dictionary of execution parameters
commit()[source]

Send all pending statements to the server for execution and commit the transaction.

Returns:list of results from pending statements
execute()[source]

Send all pending statements to the server for execution, leaving the transaction open for further statements.

Returns:list of results from pending statements
finished[source]

Indicates whether or not this transaction has been completed or is still open.

Returns:True if this transaction has finished, False otherwise
rollback()[source]

Rollback the current transaction.

class py2neo.cypher.Record(producer, values)

A single row of a Cypher execution result, holding a sequence of named values.

columns

The column names defined for this record.

Returns:tuple of column names
values

The values stored in this record.

Returns:tuple of values
exception py2neo.cypher.TransactionError(message)[source]

Raised when an error occurs while processing a Cypher transaction.

exception py2neo.cypher.TransactionFinished[source]

Raised when actions are attempted against a finished Transaction.

Classic Cypher Execution

class py2neo.neo4j.CypherQuery(graph_db, query)[source]

A reusable Cypher query. To create a new query object, a graph and the query text need to be supplied:

>>> from py2neo import neo4j
>>> graph_db = neo4j.GraphDatabaseService()
>>> query = neo4j.CypherQuery(graph_db, "CREATE (a) RETURN a")
execute(**params)[source]

Execute the query and return the results.

Parameters:params
Returns:
Return type:CypherResults
execute_one(**params)[source]

Execute the query and return the first value from the first row.

Parameters:params
Returns:
run(**params)[source]

Execute the query and discard any results.

Parameters:params
stream(**params)[source]

Execute the query and return a result iterator.

Parameters:params
Returns:
Return type:IterableCypherResults
string[source]

The text of the query.

class py2neo.neo4j.CypherResults(response)[source]

A static set of results from a Cypher query.

columns[source]

Column names.

data[source]

List of result records.

class py2neo.neo4j.IterableCypherResults(response)[source]

An iterable set of results from a Cypher query.

query = graph_db.cypher.query("START n=node(*) RETURN n LIMIT 10")
for record in query.stream():
    print record[0]

Each record returned is cast into a namedtuple with names derived from the resulting column names.

Note

Results are available as returned from the server and are decoded incrementally. This means that there is no need to wait for the entire response to be received before processing can occur.

close()[source]

Close results and free resources.

columns[source]

Column names.

Table Of Contents

Previous topic

Batches

Next topic

Object-Graph Mapping (OGM)

This Page