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"})

Many types of comparisons can be made with operator suffixes. By appending the opeartor suffix you change the operator used in Cypher expression.

Description

Suffix

Operator

Example

Explicit Equal

__exact

=

matcher.match(“Person”, name__exact=”Kevin Bacon”) MATCH (_:Person) WHERE name = “Kevin Bacon” RETURN _

Not Equal

__not

<>

matcher.match(“Person”, name__not=”Rick Astley”) MATCH (_:Person) WHERE _.name <> “Rick Astley” RETURN _

Greater than

__gt

>

matcher.match(“Person”, born__gt=1985) MATCH (_:Person) WHERE _.born > 1985 RETURN _

Greater than or equal to

__gte

>=

matcher.match(“Person”, born__gte=1965) MATCH (_:Person) WHERE _.born >= 1965 RETURN _

Less than

__lt

<

matcher.match(“Person”, born__lt=1965) MATCH (_:Person) WHERE _.born < 1965 RETURN _

Less than or equal to

__lte

<=

matcher.match(“Person”, born__lte=1965) MATCH (_:Person) WHERE _.born <= 1965 RETURN _

Starts with

__startswith

STARTS WITH

matcher.match(“Person”, name__startswith=”Kevin”) MATCH (_:Person) WHERE _.name STARTS WITH “Kevin” RETURN _

Ends with

__endswith

ENDS WITH

matcher.match(“Person”, name__endswith=”Smith”) MATCH (_:Person) WHERE _.name ENDS WITH “Smith” RETURN _

Contains

__contains

CONTAINS

matcher.match(“Person”, name__contains=”James”) MATCH (_:Person) HWERE _.name CONTAINS “James” RETURN _

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