19.17. Batch operations
Execute multiple operations in batch
This lets you execute multiple API calls through a single HTTP call, significantly improving performance for large insert and update operations.
The batch service expects an array of job descriptions as input, each job description describing an action to be performed via the normal server API.
This service is transactional. If any of the operations performed fails (returns a non-2xx HTTP status code), the transaction will be rolled back and all changes will be undone.
Each job description should contain a to
attribute, with a value
relative to the data API root (so http://localhost:7474/db/data/node becomes
just /node), and a method
attribute containing HTTP verb to use.
Optionally you may provide a body
attribute, and an id
attribute to
help you keep track of responses, although responses are guaranteed to be
returned in the same order the job descriptions are received.
The following figure outlines the different parts of the job descriptions:
Example request
-
POST
http://localhost:7474/db/data/batch
-
Accept:
application/json; charset=UTF-8
-
Content-Type:
application/json
[ { "method" : "PUT", "to" : "/node/32/properties", "body" : { "age" : 1 }, "id" : 0 }, { "method" : "GET", "to" : "/node/32", "id" : 1 }, { "method" : "POST", "to" : "/node", "body" : { "age" : 1 }, "id" : 2 }, { "method" : "POST", "to" : "/node", "body" : { "age" : 1 }, "id" : 3 } ]
Example response
-
200:
OK
-
Content-Type:
application/json; charset=UTF-8
[ { "id" : 0, "from" : "/node/32/properties" }, { "id" : 1, "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/32/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/32/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/32/relationships/out", "traverse" : "http://localhost:7474/db/data/node/32/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/32/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/32/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/32/relationships/all", "self" : "http://localhost:7474/db/data/node/32", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/32/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/32/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/32/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/32/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/32/relationships", "data" : { "age" : 1 } }, "from" : "/node/32" }, { "id" : 2, "location" : "http://localhost:7474/db/data/node/33", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/33/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/33/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/33/relationships/out", "traverse" : "http://localhost:7474/db/data/node/33/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/33/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/33/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/33/relationships/all", "self" : "http://localhost:7474/db/data/node/33", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/33/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/33/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/33/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/33/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/33/relationships", "data" : { "age" : 1 } }, "from" : "/node" }, { "id" : 3, "location" : "http://localhost:7474/db/data/node/34", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/34/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/34/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/34/relationships/out", "traverse" : "http://localhost:7474/db/data/node/34/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/34/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/34/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/34/relationships/all", "self" : "http://localhost:7474/db/data/node/34", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/34/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/34/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/34/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/34/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/34/relationships", "data" : { "age" : 1 } }, "from" : "/node" } ]
Refer to items created earlier in the same batch job
The batch operation API allows you to refer to the URI returned from a created resource in subsequent job descriptions, within the same batch call.
Use the {[JOB ID]}
special syntax to inject URIs from created resources
into JSON strings in subsequent job descriptions.
Example request
-
POST
http://localhost:7474/db/data/batch
-
Accept:
application/json; charset=UTF-8
-
Content-Type:
application/json
[ { "method" : "POST", "to" : "/node", "id" : 0, "body" : { "name" : "bob" } }, { "method" : "POST", "to" : "/node", "id" : 1, "body" : { "age" : 12 } }, { "method" : "POST", "to" : "{0}/relationships", "id" : 3, "body" : { "to" : "{1}", "data" : { "since" : "2010" }, "type" : "KNOWS" } }, { "method" : "POST", "to" : "/index/relationship/my_rels", "id" : 4, "body" : { "key" : "since", "value" : "2010", "uri" : "{3}" } } ]
Example response
-
200:
OK
-
Content-Type:
application/json; charset=UTF-8
[ { "id" : 0, "location" : "http://localhost:7474/db/data/node/24", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/24/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/24/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/24/relationships/out", "traverse" : "http://localhost:7474/db/data/node/24/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/24/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/24/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/24/relationships/all", "self" : "http://localhost:7474/db/data/node/24", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/24/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/24/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/24/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/24/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/24/relationships", "data" : { "name" : "bob" } }, "from" : "/node" }, { "id" : 1, "location" : "http://localhost:7474/db/data/node/25", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/25/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/25/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/25/relationships/out", "traverse" : "http://localhost:7474/db/data/node/25/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/25/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/25/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/25/relationships/all", "self" : "http://localhost:7474/db/data/node/25", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/25/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/25/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/25/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/25/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/25/relationships", "data" : { "age" : 12 } }, "from" : "/node" }, { "id" : 3, "location" : "http://localhost:7474/db/data/relationship/7", "body" : { "extensions" : { }, "start" : "http://localhost:7474/db/data/node/24", "property" : "http://localhost:7474/db/data/relationship/7/properties/{key}", "self" : "http://localhost:7474/db/data/relationship/7", "properties" : "http://localhost:7474/db/data/relationship/7/properties", "type" : "KNOWS", "end" : "http://localhost:7474/db/data/node/25", "data" : { "since" : "2010" } }, "from" : "http://localhost:7474/db/data/node/24/relationships" }, { "id" : 4, "location" : "http://localhost:7474/db/data/index/relationship/my_rels/since/2010/7", "body" : { "extensions" : { }, "start" : "http://localhost:7474/db/data/node/24", "property" : "http://localhost:7474/db/data/relationship/7/properties/{key}", "self" : "http://localhost:7474/db/data/relationship/7", "properties" : "http://localhost:7474/db/data/relationship/7/properties", "type" : "KNOWS", "end" : "http://localhost:7474/db/data/node/25", "data" : { "since" : "2010" }, "indexed" : "http://localhost:7474/db/data/index/relationship/my_rels/since/2010/7" }, "from" : "/index/relationship/my_rels" } ]
Execute multiple operations in batch streaming
Example request
-
POST
http://localhost:7474/db/data/batch
-
Accept:
application/json
-
Content-Type:
application/json
-
X-Stream:
true
[ { "method" : "PUT", "to" : "/node/109/properties", "body" : { "age" : 1 }, "id" : 0 }, { "method" : "GET", "to" : "/node/109", "id" : 1 }, { "method" : "POST", "to" : "/node", "body" : { "age" : 1 }, "id" : 2 }, { "method" : "POST", "to" : "/node", "body" : { "age" : 1 }, "id" : 3 } ]
Example response
-
200:
OK
-
Content-Type:
application/json; charset=UTF-8
[ { "id" : 0, "from" : "/node/109/properties", "body" : null, "status" : 204 }, { "id" : 1, "from" : "/node/109", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/109/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/109/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/109/relationships/out", "traverse" : "http://localhost:7474/db/data/node/109/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/109/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/109/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/109/relationships/all", "self" : "http://localhost:7474/db/data/node/109", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/109/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/109/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/109/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/109/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/109/relationships", "data" : { "age" : 1 } }, "status" : 200 }, { "id" : 2, "from" : "/node", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/110/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/110/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/110/relationships/out", "traverse" : "http://localhost:7474/db/data/node/110/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/110/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/110/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/110/relationships/all", "self" : "http://localhost:7474/db/data/node/110", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/110/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/110/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/110/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/110/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/110/relationships", "data" : { "age" : 1 } }, "location" : "http://localhost:7474/db/data/node/110", "status" : 201 }, { "id" : 3, "from" : "/node", "body" : { "extensions" : { }, "paged_traverse" : "http://localhost:7474/db/data/node/111/paged/traverse/{returnType}{?pageSize,leaseTime}", "labels" : "http://localhost:7474/db/data/node/111/labels", "outgoing_relationships" : "http://localhost:7474/db/data/node/111/relationships/out", "traverse" : "http://localhost:7474/db/data/node/111/traverse/{returnType}", "all_typed_relationships" : "http://localhost:7474/db/data/node/111/relationships/all/{-list|&|types}", "property" : "http://localhost:7474/db/data/node/111/properties/{key}", "all_relationships" : "http://localhost:7474/db/data/node/111/relationships/all", "self" : "http://localhost:7474/db/data/node/111", "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/111/relationships/out/{-list|&|types}", "properties" : "http://localhost:7474/db/data/node/111/properties", "incoming_relationships" : "http://localhost:7474/db/data/node/111/relationships/in", "incoming_typed_relationships" : "http://localhost:7474/db/data/node/111/relationships/in/{-list|&|types}", "create_relationship" : "http://localhost:7474/db/data/node/111/relationships", "data" : { "age" : 1 } }, "location" : "http://localhost:7474/db/data/node/111", "status" : 201 } ]