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.

3.1. Node Matching

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)
>>> matcher.match("Person", name="Keanu Reeves").first()
(_224:Person {born:1964,name:"Keanu Reeves"})

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

>>> 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

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.

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

Base matcher for selecting nodes that fulfil a specific set of criteria.

Parameters:graphGraph object on which to perform matches
__getitem__(identity)[source]

Return a node by identity.

__len__()[source]

Return the number of nodes matched.

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]

Immutable set of node selection criteria.

__iter__()[source]

Iterate through all matching nodes.

__len__()[source]

Return the number of nodes matched.

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

3.2. Relationship Matching

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

Base matcher for selecting relationships that fulfil a specific set of criteria.

Parameters:graphGraph object on which to perform matches
__getitem__(identity)[source]

Return a relationship by identity.

__len__()[source]

Return the number of relationships matched.

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]

Immutable set of relationship selection criteria.

__iter__()[source]

Iterate through all matching relationships.

__len__()[source]

Return the number of relationships matched.

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 relationships.

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

Order by the fields or field expressions specified.

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

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

Skip the first amount relationships in the result.

Parameters:amount – number of relationships to skip
Returns:refined RelationshipMatch 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 relationship within a condition expression, use the underscore character _. For example:

match.where("_.weight >= 30")

Simple property equalities can also be specified:

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

refined RelationshipMatch object