4. py2neo.ext.batman – Batch & Manual Indexing

Maintained by: Nigel Small <nigel@py2neo.org>

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.

4.1. Batch Resource

class py2neo.ext.batman.BatchRunner(uri)[source]

Resource for batch execution.

run(batch)[source]

Execute a collection of jobs and return all results.

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

4.2. Batch Instances

class py2neo.ext.batman.Batch(graph)[source]

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

append(job)[source]

Add a job to this batch.

Parameters:job – A Job object to add to this batch.
Return type:Job
find(job)[source]

Find the position of a job within this batch.

graph = None

The graph with which this batch is associated

resolve(node)[source]

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

4.3. Manual Indexing

class py2neo.ext.batman.ManualIndexManager(graph)[source]
delete_index(content_type, index_name)[source]

Delete the entire index identified by the type and name supplied.

Parameters:
  • content_type – either Node or Relationship
  • index_name – the name of the index to delete
Raises:

LookupError – if the specified index does not exist

get_index(content_type, index_name)[source]

Fetch a specific index from the current database, returning an ManualIndex instance. If an index with the supplied name and content type does not exist, None is returned.

Parameters:
  • content_type – either Node or Relationship
  • index_name – the name of the required index
Returns:

an ManualIndex instance or None

get_indexed_node(index_name, key, value)[source]

Fetch the first node indexed with the specified details, returning None if none found.

Parameters:
  • index_name – the name of the required index
  • key – the index key
  • value – the index value
Returns:

a Node instance

get_indexed_relationship(index_name, key, value)[source]

Fetch the first relationship indexed with the specified details, returning None if none found.

Parameters:
  • index_name – the name of the required index
  • key – the index key
  • value – the index value
Returns:

a Relationship instance

get_indexes(content_type)[source]

Fetch a dictionary of all available indexes of a given type.

Parameters:content_type – either Node or Relationship
Returns:a list of ManualIndex instances of the specified type
get_or_create_index(content_type, index_name, config=None)[source]

Fetch a specific index from the current database, returning an ManualIndex instance. If an index with the supplied name and content type does not exist, one is created with either the default configuration or that supplied in config.

Parameters:
  • content_type – either Node or Relationship
  • index_name – the name of the required index
Returns:

a ManualIndex instance

get_or_create_indexed_node(index_name, key, value, properties=None)[source]

Fetch the first node indexed with the specified details, creating and returning a new indexed node if none found.

Parameters:
  • index_name – the name of the required index
  • key – the index key
  • value – the index value
  • properties – properties for the new node, if one is created (optional)
Returns:

a Node instance

class py2neo.ext.batman.ManualIndex(content_type, uri, name=None)[source]

Searchable database index which can contain either nodes or relationships.

add(key, value, entity)[source]

Add an entity to this index under the key:value pair supplied.

Note that while Neo4j indexes allow multiple entities to be added under a particular key:value, the same entity may only be represented once; this method is therefore idempotent.

Parameters:
  • key
  • value
  • entity
add_if_none(key, value, entity)[source]

Add an entity to this index under the key:value pair supplied if no entry already exists at that point.

If added, this method returns the entity, otherwise None is returned.

content_type

Return the type of entity contained within this index. Will return either Node or Relationship.

create(key, value, abstract)[source]

Create and index a new node or relationship using the abstract provided.

Parameters:
  • key
  • value
  • abstract
create_if_none(key, value, abstract)[source]

Create a new entity with the specified details within the current index, under the key:value pair supplied, if no such entity already exists. If creation occurs, the new entity will be returned, otherwise None will be returned.

get(key, value)[source]

Fetch a list of all entities from the index which are associated with the key:value pair supplied.

Parameters:
  • key
  • value
get_or_create(key, value, abstract)[source]

Fetch a single entity from the index which is associated with the key:value pair supplied, creating a new entity with the supplied details if none exists.

name

Return the name of this index.

query(query)[source]

Query the index according to the supplied query criteria, returning a list of matched entities.

The query syntax used should be appropriate for the configuration of the index being queried. For indexes with default configuration, this should be Apache Lucene query syntax.

remove(key=None, value=None, entity=None)[source]

Remove any entries from the index which match the parameters supplied. The allowed parameter combinations are:

key, value, entity
remove a specific entity indexed under a given key-value pair
key, value
remove all entities indexed under a given key-value pair
key, entity
remove a specific entity indexed against a given key but with any value
entity
remove all occurrences of a specific entity regardless of key and value
class py2neo.ext.batman.ManualIndexReadBatch(graph)[source]

Generic batch execution facility for data read requests,

get_indexed_nodes(index, key, value)[source]

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

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

Job

class py2neo.ext.batman.ManualIndexWriteBatch(graph)[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.

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

Add an existing node or relationship to an index.

Parameters:
  • cls – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • entity – node or relationship to add to the index
Returns:

Job

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 – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • entity – node or relationship to add to the index
Returns:

Job

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 – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • abstract – abstract node or relationship to create
Returns:

Job

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 – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • entity – node or relationship to add to the index
Returns:

Job

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 – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • abstract – abstract node or relationship to create
Returns:

Job

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 – the type of indexed entity
  • index – index or index name
  • key – index entry key
  • value – index entry value
  • entity – node or relationship to remove from the index
Returns:

Job

4.4. Jobs

class py2neo.ext.batman.Job(method, target, body=None)[source]

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.ext.batman.JobResult(batch, job_id, uri, status_code=None, location=None, content=None)[source]

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.

graph

The corresponding graph for this result.

Return type:py2neo.Graph
job

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.ext.batman.Target(entity, *segments)[source]

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.

uri_string

The fully resolved URI string for this target.

Return type:string
class py2neo.ext.batman.NodePointer(address)[source]

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.

4.4.1. Job Types

class py2neo.ext.batman.AddNodeLabelsJob(node, *labels)[source]
class py2neo.ext.batman.CreateNodeJob(**properties)[source]
class py2neo.ext.batman.CreatePathJob(*entities)[source]
class py2neo.ext.batman.CreateRelationshipJob(start_node, type, end_node, **properties)[source]
class py2neo.ext.batman.CreateUniquePathJob(*entities)[source]
class py2neo.ext.batman.CypherJob(statement, parameters=None)[source]
class py2neo.ext.batman.DeleteEntityJob(entity)[source]
class py2neo.ext.batman.DeletePropertiesJob(entity)[source]
class py2neo.ext.batman.DeletePropertyJob(entity, key)[source]
class py2neo.ext.batman.PullNodeLabelsJob(node)[source]
class py2neo.ext.batman.PullPropertiesJob(entity)[source]
class py2neo.ext.batman.PullRelationshipJob(relationship)[source]
class py2neo.ext.batman.PushNodeLabelsJob(node, labels)[source]
class py2neo.ext.batman.PushPropertiesJob(entity, properties)[source]
class py2neo.ext.batman.PushPropertyJob(entity, key, value)[source]
class py2neo.ext.batman.RemoveNodeLabelJob(entity, label)[source]

4.5. Exceptions

class py2neo.ext.batman.BatchError(message, batch, job_id, status_code, uri, location=None, **kwargs)[source]

Wraps a base py2neo.GraphError within a batch context.