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¶
4.2. Batch Instances¶
-
class
py2neo.ext.batman.
Batch
(graph)[source]¶ A collection of
Job
objects that can be submitted to aBatchRunner
. 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
-
graph
= None¶ The graph with which this batch is associated
-
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
orRelationship
- index_name – the name of the index to delete
Raises: LookupError – if the specified index does not exist
- content_type – either
-
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
orRelationship
- index_name – the name of the required index
Returns: an
ManualIndex
instance orNone
- content_type – either
-
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
orRelationship
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
orRelationship
- index_name – the name of the required index
Returns: a
ManualIndex
instance- content_type – either
-
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
orRelationship
.
-
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,
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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.
-
-
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 aBatch
submission.-
content
= None¶ The response content for this job.
-
graph
¶ The corresponding graph for this result.
Return type: py2neo.Graph
-
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.
-