Batches

Py2neo interacts with Neo4j via its REST API interface and so every interaction requires a separate HTTP request to be sent. However, when working at scale, for tasks such as bulk data loading, communication can be prohibitively slow using this step-by-step approach.

Batches allow multiple requests to be grouped and sent together, cutting down on network traffic and latency. Such requests also have the advantage of being executed within a single transaction.

Unfortunately, it is not practical to mix both read and write operations into a single batch due to restrictions within the underlying implementation. For this reason, py2neo provides two separate batch classes: ReadBatch and WriteBatch. The latter is the more comprehensive, as can be seen below.

class py2neo.neo4j.ReadBatch(graph_db)[source]

Generic batch execution facility for data read requests,

append_cypher(query, params=None)

Append a Cypher query to this batch. Resources returned from Cypher queries cannot be referenced by other batch requests.

Parameters:
  • query (str) – Cypher query
  • params (dict) – query parameters
Returns:

batch request object

Return type:

_Batch.Request

clear()

Clear all requests from this batch.

get_indexed_nodes(index, key, value)[source]

Fetch all nodes indexed under a given key-value pair.

Parameters:
  • index (str or Index) – index name or instance
  • key (str) – key under which nodes are indexed
  • value – value under which nodes are indexed
Returns:

batch request object

stream()

Execute the batch on the server and return iterable results. This method allows handling of results as they are received from the server.

Returns:iterable results
Return type:BatchResponseList
submit()

Execute the batch on the server and return a list of results. This method blocks until all results are received.

Returns:result records
Return type:list
class py2neo.neo4j.WriteBatch(graph_db)[source]

Generic batch execution facility for data write requests. Most methods return a BatchRequest object that can be used as a reference in other methods. See the create method for an example of this.

add_labels(node, *labels)[source]

Add labels to a node.

Parameters:
  • node – node to which to add labels
  • labels (str) – text labels
Returns:

batch request object

add_to_index(cls, index, key, value, entity)[source]

Add an existing node or relationship to an index.

Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • entity (concrete or reference) – node or relationship to add to the index
Returns:

batch request object

add_to_index_or_fail(cls, index, key, value, entity)[source]

Add an existing node or relationship uniquely to an index, failing the entire batch if such an entry already exists.

Warning

Uniqueness modes for legacy indexes have been broken in recent server versions and therefore this method may not work as expected.

Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • entity (concrete or reference) – node or relationship to add to the index
Returns:

batch request object

append_cypher(query, params=None)

Append a Cypher query to this batch. Resources returned from Cypher queries cannot be referenced by other batch requests.

Parameters:
  • query (str) – Cypher query
  • params (dict) – query parameters
Returns:

batch request object

Return type:

_Batch.Request

clear()

Clear all requests from this batch.

create(abstract)[source]

Create a node or relationship based on the abstract entity provided. For example:

batch = WriteBatch(graph_db)
a = batch.create(node(name="Alice"))
b = batch.create(node(name="Bob"))
batch.create(rel(a, "KNOWS", b))
results = batch.submit()
Parameters:abstract (abstract) – node or relationship
Returns:batch request object
create_in_index_or_fail(cls, index, key, value, abstract=None)[source]

Create a new node or relationship and add it uniquely to an index, failing the entire batch if such an entry already exists.

Warning

Uniqueness modes for legacy indexes have been broken in recent server versions and therefore this method may not work as expected.

Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • abstract – abstract node or relationship to create
Returns:

batch request object

create_path(node, *rels_and_nodes)[source]

Construct a path across a specified set of nodes and relationships. Nodes may be existing concrete node instances, abstract nodes or None but references to other requests are not supported.

Parameters:
  • node (concrete, abstract or None) – start node
  • rels_and_nodes (concrete, abstract or None) – alternating relationships and nodes
Returns:

batch request object

delete(entity)[source]

Delete a node or relationship from the graph.

Parameters:entity (concrete or reference) – node or relationship to delete
Returns:batch request object
delete_properties(entity)[source]

Delete all properties from a node or relationship.

Parameters:entity (concrete or reference) – node or relationship from which to delete properties
Returns:batch request object
delete_property(entity, key)[source]

Delete a single property from a node or relationship.

Parameters:
  • entity (concrete or reference) – node or relationship from which to delete property
  • key (str) – property key
Returns:

batch request object

get_or_add_to_index(cls, index, key, value, entity)[source]

Fetch a uniquely indexed node or relationship if one exists, otherwise add an existing entity to the index.

Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • entity (concrete or reference) – node or relationship to add to the index
Returns:

batch request object

get_or_create_in_index(cls, index, key, value, abstract=None)[source]

Fetch a uniquely indexed node or relationship if one exists, otherwise create a new entity and add that to the index.

Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • abstract – abstract node or relationship to create
Returns:

batch request object

get_or_create_path(node, *rels_and_nodes)[source]

Construct a unique path across a specified set of nodes and relationships, adding only parts that are missing. Nodes may be existing concrete node instances, abstract nodes or None but references to other requests are not supported.

Parameters:
  • node (concrete, abstract or None) – start node
  • rels_and_nodes (concrete, abstract or None) – alternating relationships and nodes
Returns:

batch request object

remove_from_index(cls, index, key=None, value=None, entity=None)[source]

Remove any nodes or relationships from an index that match a particular set of criteria. Allowed parameter combinations are:

key, value, entity
remove a specific node or relationship indexed under a given key-value pair
key, entity
remove a specific node or relationship indexed against a given key and with any value
entity
remove all occurrences of a specific node or relationship regardless of key or value
Parameters:
  • cls (Node or Relationship) – the type of indexed entity
  • index (Index or str) – index or index name
  • key (str) – index entry key
  • value – index entry value
  • entity (concrete or reference) – node or relationship to remove from the index
Returns:

batch request object

remove_label(node, label)[source]

Remove a label from a node.

Parameters:
  • node – node from which to remove labels (can be a reference to another request within the same batch)
  • label (str) – text label
Returns:

batch request object

run()

Execute the batch on the server and discard the results. If the batch results are not required, this will generally be the fastest execution method.

set_labels(node, *labels)[source]

Replace all labels on a node.

Parameters:
  • node – node on which to replace labels (can be a reference to another request within the same batch)
  • labels (str) – text labels
Returns:

batch request object

set_properties(entity, properties)[source]

Replace all properties on a node or relationship.

Parameters:
  • entity (concrete or reference) – node or relationship on which to set properties
  • properties (dict) – properties
Returns:

batch request object

set_property(entity, key, value)[source]

Set a single property on a node or relationship.

Parameters:
  • entity (concrete or reference) – node or relationship on which to set property
  • key (str) – property key
  • value – property value
Returns:

batch request object

stream()

Execute the batch on the server and return iterable results. This method allows handling of results as they are received from the server.

Returns:iterable results
Return type:BatchResponseList
submit()

Execute the batch on the server and return a list of results. This method blocks until all results are received.

Returns:result records
Return type:list

Previous topic

Indexes

Next topic

Cypher

This Page