3. py2neo.matching – Entity matching

The py2neo.matching module provides functionality to match nodes and relationships according to certain criteria. For each entity type, a Matcher class and a Match class are provided. The Matcher can be used to perform a basic selection, returning a Match that can be evaluated or further refined.

A simple node selection may match on label and property name:

>>> from py2neo import Graph, NodeMatcher
>>> graph = Graph()
>>> matcher = NodeMatcher(graph)
>>> matcher.match("Person", name="Keanu Reeves").first()
[(_224:Person {born:1964,name:"Keanu Reeves"})]

For a more complex selection, the match can be refined with a _WHERE_ clause, using an underscore character to refer to the matched entity:

>>> list(matcher.match("Person").where("_.name =~ 'K.*'"))
[(_57:Person {born: 1957, name: 'Kelly McGillis'}),
 (_80:Person {born: 1958, name: 'Kevin Bacon'}),
 (_83:Person {born: 1962, name: 'Kelly Preston'}),
 (_224:Person {born: 1964, name: 'Keanu Reeves'}),
 (_226:Person {born: 1966, name: 'Kiefer Sutherland'}),
 (_243:Person {born: 1957, name: 'Kevin Pollak'})]

Orders and limits can also be applied:

>>> list(matcher.match("Person").where("_.name =~ 'K.*'").order_by("_.name").limit(3))
[(_224:Person {born: 1964, name: 'Keanu Reeves'}),
 (_57:Person {born: 1957, name: 'Kelly McGillis'}),
 (_83:Person {born: 1962, name: 'Kelly Preston'})]

If only a count of matched entities is required, the length of a match can be evaluated:

>>> len(matcher.match("Person").where("_.name =~ 'K.*'"))
6
class py2neo.matching.NodeMatcher(graph)[source]

A NodeMatcher can be used to locate nodes that fulfil a specific set of criteria. Typically, a single node can be identified passing a specific label and property key-value pair. However, any number of labels and any condition supported by the Cypher WHERE clause is allowed.

For a simple match by label and property:

>>> from py2neo import Graph, NodeMatcher
>>> graph = Graph()
>>> matcher = NodeMatcher(graph)
>>> matched = matcher.match("Person", name="Keanu Reeves")
>>> list(matched)
[(f9726ea:Person {born:1964,name:"Keanu Reeves"})]

For a more comprehensive match using Cypher expressions, the NodeMatch.where() method can be used for further refinement. Here, the underscore character can be used to refer to the node being filtered:

>>> matched = matcher.match("Person").where("_.name =~ 'J.*'", "1960 <= _.born < 1970")
>>> list(matched)
[(a03f6eb:Person {born:1967,name:"James Marshall"}),
 (e59993d:Person {born:1966,name:"John Cusack"}),
 (c44901e:Person {born:1960,name:"John Goodman"}),
 (b141775:Person {born:1965,name:"John C. Reilly"}),
 (e40244b:Person {born:1967,name:"Julia Roberts"})]

The underlying query is only evaluated when the selection undergoes iteration or when a specific evaluation method is called (such as NodeMatch.first()). This means that a NodeMatch instance may be reused before and after a data changes for different results.

__getitem__(identity)[source]

Return a node by identity.

get(identity)[source]

Create a new NodeMatch that filters by identity and returns the first matched Node. This can essentially be used to match and return a Node by ID.

matcher.get(1234)

If no such Node is found, py:const:None is returned instead. Contrast with matcher[1234] which raises a KeyError if no entity is found.

match(*labels, **properties)[source]

Describe a basic node match using labels and property equality.

Parameters:
  • labels – node labels to match
  • properties – set of property keys and values to match
Returns:

NodeMatch instance

class py2neo.matching.NodeMatch(graph, labels=frozenset(), conditions=(), order_by=(), skip=None, limit=None)[source]

An immutable set of node match criteria.

__iter__()[source]

Iterate through all matching nodes.

first()[source]

Evaluate the match and return the first Node matched or None if no matching nodes are found.

Returns:a single matching Node or None
limit(amount)[source]

Limit to at most amount nodes.

Parameters:amount – maximum number of nodes to return
Returns:refined NodeMatch object
order_by(*fields)[source]

Order by the fields or field expressions specified.

To refer to the current node within a field or field expression, use the underscore character _. For example:

match.order_by("_.name", "max(_.a, _.b)")
Parameters:fields – fields or field expressions to order by
Returns:refined NodeMatch object
skip(amount)[source]

Skip the first amount nodes in the result.

Parameters:amount – number of nodes to skip
Returns:refined NodeMatch object
where(*conditions, **properties)[source]

Refine this match to create a new match. The criteria specified for refining the match consist of conditions and properties. Conditions are individual Cypher expressions that would be found in a WHERE clause; properties are used as exact matches for property values.

To refer to the current node within a condition expression, use the underscore character _. For example:

match.where("_.name =~ 'J.*")

Simple property equalities can also be specified:

match.where(born=1976)
Parameters:
  • conditions – Cypher expressions to add to the WHERE clause
  • properties – exact property match keys and values
Returns:

refined NodeMatch object

class py2neo.matching.RelationshipMatcher(graph)[source]

A RelationshipMatcher can be used to locate relationships that fulfil a specific set of criteria.

__getitem__(identity)[source]

Return a relationship by identity.

get(identity)[source]

Create a new RelationshipMatch that filters by identity and returns the first matched Relationship. This can essentially be used to match and return a Relationship by ID.

matcher.get(1234)

If no such Relationship is found, py:const:None is returned instead. Contrast with matcher[1234] which raises a KeyError if no entity is found.

match(nodes=None, r_type=None, **properties)[source]

Describe a basic relationship match…

Parameters:
  • nodes – Sequence or Set of start and end nodes (None means any node); a Set implies a match in any direction
  • r_type
  • properties – set of property keys and values to match
Returns:

RelationshipMatch instance

class py2neo.matching.RelationshipMatch(graph, nodes=None, r_type=None, conditions=(), order_by=(), skip=None, limit=None)[source]
__iter__()[source]

Iterate through all matching relationships.

first()[source]

Evaluate the selection and return the first Relationship selected or None if no matching relationships are found.

Returns:a single matching Relationship or None
limit(amount)[source]

Limit to at most amount nodes.

Parameters:amount – maximum number of nodes to return
Returns:refined NodeMatch object
order_by(*fields)[source]

Order by the fields or field expressions specified.

To refer to the current node within a field or field expression, use the underscore character _. For example:

match.order_by("_.name", "max(_.a, _.b)")
Parameters:fields – fields or field expressions to order by
Returns:refined NodeMatch object
skip(amount)[source]

Skip the first amount nodes in the result.

Parameters:amount – number of nodes to skip
Returns:refined NodeMatch object
where(*conditions, **properties)[source]

Refine this match to create a new match. The criteria specified for refining the match consist of conditions and properties. Conditions are individual Cypher expressions that would be found in a WHERE clause; properties are used as exact matches for property values.

To refer to the current node within a condition expression, use the underscore character _. For example:

match.where("_.name =~ 'J.*")

Simple property equalities can also be specified:

match.where(born=1976)
Parameters:
  • conditions – Cypher expressions to add to the WHERE clause
  • properties – exact property match keys and values
Returns:

refined NodeMatch object