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.- 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
- 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
- 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
- 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.
- property 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.
- property 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.
- property 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.
- property 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.PullNodeLabelsJob(node)[source]¶
- raw_result = True¶
Indicates whether or not the result should be interpreted as raw data.
- class py2neo.ext.batman.PullPropertiesJob(entity)[source]¶
- raw_result = True¶
Indicates whether or not the result should be interpreted as raw data.