3. py2neo.selection – Node Selection

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

An immutable set of node selection criteria.

first()[source]

Evaluate the selection and return the first Node selected or None if no matching nodes are found.

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

Limit the selection to at most amount nodes.

Parameters:amount – maximum number of nodes to select
Returns:refined selection 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:

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

Skip the first amount nodes in the result.

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

Create a new selection based on this selection. The criteria specified for refining the selection 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:

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

Simple property equalities can also be specified:

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

refined selection object

class py2neo.selection.NodeSelector(graph)[source]

A NodeSelector 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 selection by label and property:

>>> from py2neo import Graph, NodeSelector
>>> graph = Graph()
>>> selector = NodeSelector(graph)
>>> selected = selector.select("Person", name="Keanu Reeves")
>>> list(selected)
[(f9726ea:Person {born:1964,name:"Keanu Reeves"})]

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

>>> selected = selector.select("Person").where("_.name =~ 'J.*'", "1960 <= _.born < 1970")
>>> list(selected)
[(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 NodeSelection.first()). This means that a NodeSelection instance may be reused before and after a data changes for different results.

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

Describe a basic node selection using labels and property equality.

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

NodeSelection instance