API: Batch

The Neo4j batch resource is designed to allow multiple REST calls to be passed to the server in a single request and be executed in a single transaction. While this remains a good choice for some legacy use cases, many are better served by a Cypher transaction instead.

Batches offer a limited capability to refer to one job from another within the same batch. This can be useful when building a batch that creates both nodes and relationships between those new nodes. Note though that certain combinations of such cross-referencing are not possible, particularly when creating nodes within a legacy index.

Labels and schema indexes are also poorly supported by the batch facility and it is recommended to use Cypher transactions instead when working with these.

Batch Resource

class py2neo.batch.BatchResource

Resource for batch execution.


Post a batch of jobs to the server and receive a raw response.

Parameters:batch – A Batch of jobs.
Return type:httpstream.Response

Execute a collection of jobs and discard any response. Note that as the response is discarded, any errors returned will be hidden.

Parameters:batch – A Batch of jobs.

Execute a collection of jobs and yield results as received.

Parameters:batch – A Batch of jobs.
Return type:generator

Execute a collection of jobs and return all results.

Parameters:batch – A Batch of jobs.
Return type:list

Batch Instances

class py2neo.batch.Batch(graph)

A collection of Job objects that can be submitted to a BatchResource. References to previous jobs are only valid within the same batch and will not work across batches.


Add a job to this batch.

Parameters:job – A Job object to add to this batch.
Return type:Job

Find the position of a job within this batch.

graph = None

The graph with which this batch is associated


Convert any references to previous jobs within the same batch into NodePointer objects.

class py2neo.batch.PullBatch(graph)

A batch of pull jobs.


Append an entity to the list to be pulled.

Parameters:entity – An entity such as a py2neo.Node.

Pull details to all entities in this batch from their remote counterparts.

class py2neo.batch.PushBatch(graph)

A batch of push jobs.


Append an entity to the list to be pushed.

Parameters:entity – An entity such as a py2neo.Node.

Push details from all entities in this batch to their remote counterparts.


class py2neo.batch.Job(method, target, body=None)

A single request for inclusion within a Batch.

body = None

The request payload.

finished = False

Indicates whether the job has been submitted.

graph = None

The graph for which this job is intended (optional).

method = None

The HTTP method for the request.

raw_result = False

Indicates whether or not the result should be interpreted as raw data.

target = None

A Target object used to determine the destination URI.

class py2neo.batch.JobResult(batch, job_id, uri, status_code=None, location=None, content=None)

The result returned from the server for a single Job following a Batch submission.

batch = None

The Batch from which this result was returned.

content = None

The response content for this job.


The corresponding graph for this result.

Return type:py2neo.Graph

The original job behind this result.

Return type:Job
job_id = None

The unique ID for this job within the batch.

location = None

The Location header returned for this job (if included).

status_code = None

The status code returned for this job.

uri = None

The URI destination of the original job.

class py2neo.batch.Target(entity, *segments)

A callable target for a batch job. This may refer directly to a URI or to an object that can be resolved to a URI, such as a py2neo.Node.

entity = None

The entity behind this target.

segments = None

Additional path segments to append to the resolved URI.


The fully resolved URI string for this target.

Return type:string
class py2neo.NodePointer(address)

Pointer to a Node object. This can be used in a batch context to point to a node not yet created.

address = None

The address or index to which this pointer points.

Job Types

class py2neo.batch.AddNodeLabelsJob(node, *labels)
class py2neo.batch.CreateNodeJob(**properties)
class py2neo.batch.CreatePathJob(*entities)
class py2neo.batch.CreateRelationshipJob(start_node, rel, end_node, **properties)
class py2neo.batch.CreateUniquePathJob(*entities)
class py2neo.batch.CypherJob(statement, parameters=None)

A Cypher execution job for inclusion within a batch. Consider using Cypher transactions instead of batched Cypher jobs.

class py2neo.batch.DeleteEntityJob(entity)
class py2neo.batch.DeletePropertiesJob(entity)
class py2neo.batch.DeletePropertyJob(entity, key)
class py2neo.batch.PullNodeLabelsJob(node)
class py2neo.batch.PullPropertiesJob(entity)
class py2neo.batch.PullRelationshipJob(relationship)
class py2neo.batch.PushNodeLabelsJob(node, labels)
class py2neo.batch.PushPropertiesJob(entity, properties)
class py2neo.batch.PushPropertyJob(entity, key, value)
class py2neo.batch.RemoveNodeLabelJob(entity, label)


class py2neo.batch.BatchError(message, batch, job_id, status_code, uri, location=None, **kwargs)

Wraps a base py2neo.GraphError within a batch context.