20.19. Batch operations

Batch operations lets you execute multiple API calls through a single HTTP call. This improves performance for large insert and update operations significantly.

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 no changes will be applied.

Important

You cannot use this resource to execute Cypher queries with USING PERIODIC COMMIT.

Execute multiple operations in batch

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.

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:

Figure 20.77. Starting Graph

Starting-Graph-execute-multiple-operations-in-batch.svg

Figure 20.78. Final Graph

Example request

POST http://localhost:7474/db/data/batch
Accept: application/json; charset=UTF-8
Content-Type: application/json

[ {
  "method" : "PUT",
  "to" : "/node/130/properties",
  "body" : {
    "age" : 1
  },
  "id" : 0
}, {
  "method" : "GET",
  "to" : "/node/130",
  "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/130/properties"
}, {
  "id" : 1,
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 130,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/130/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/130/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/130/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/130/relationships",
    "labels" : "http://localhost:7474/db/data/node/130/labels",
    "traverse" : "http://localhost:7474/db/data/node/130/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/130/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/130/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/130/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/130",
    "incoming_relationships" : "http://localhost:7474/db/data/node/130/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/130/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/130/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 1
    }
  },
  "from" : "/node/130"
}, {
  "id" : 2,
  "location" : "http://localhost:7474/db/data/node/132",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 132,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/132/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/132/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/132/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/132/relationships",
    "labels" : "http://localhost:7474/db/data/node/132/labels",
    "traverse" : "http://localhost:7474/db/data/node/132/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/132/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/132/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/132/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/132",
    "incoming_relationships" : "http://localhost:7474/db/data/node/132/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/132/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/132/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 1
    }
  },
  "from" : "/node"
}, {
  "id" : 3,
  "location" : "http://localhost:7474/db/data/node/133",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 133,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/133/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/133/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/133/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/133/relationships",
    "labels" : "http://localhost:7474/db/data/node/133/labels",
    "traverse" : "http://localhost:7474/db/data/node/133/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/133/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/133/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/133/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/133",
    "incoming_relationships" : "http://localhost:7474/db/data/node/133/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/133/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/133/relationships/in/{-list|&|types}",
    "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.

Figure 20.79. Final Graph

Final-Graph-Refer-to-items-created-earlier-in-the-same-batch-job.svg

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/123",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 123,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/123/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/123/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/123/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/123/relationships",
    "labels" : "http://localhost:7474/db/data/node/123/labels",
    "traverse" : "http://localhost:7474/db/data/node/123/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/123/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/123/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/123/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/123",
    "incoming_relationships" : "http://localhost:7474/db/data/node/123/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/123/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/123/relationships/in/{-list|&|types}",
    "data" : {
      "name" : "bob"
    }
  },
  "from" : "/node"
}, {
  "id" : 1,
  "location" : "http://localhost:7474/db/data/node/124",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 124,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/124/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/124/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/124/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/124/relationships",
    "labels" : "http://localhost:7474/db/data/node/124/labels",
    "traverse" : "http://localhost:7474/db/data/node/124/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/124/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/124/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/124/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/124",
    "incoming_relationships" : "http://localhost:7474/db/data/node/124/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/124/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/124/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 12
    }
  },
  "from" : "/node"
}, {
  "id" : 3,
  "location" : "http://localhost:7474/db/data/relationship/34",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 34,
      "type" : "KNOWS"
    },
    "start" : "http://localhost:7474/db/data/node/123",
    "property" : "http://localhost:7474/db/data/relationship/34/properties/{key}",
    "self" : "http://localhost:7474/db/data/relationship/34",
    "end" : "http://localhost:7474/db/data/node/124",
    "type" : "KNOWS",
    "properties" : "http://localhost:7474/db/data/relationship/34/properties",
    "data" : {
      "since" : "2010"
    }
  },
  "from" : "http://localhost:7474/db/data/node/123/relationships"
}, {
  "id" : 4,
  "location" : "http://localhost:7474/db/data/index/relationship/my_rels/since/2010/34",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 34,
      "type" : "KNOWS"
    },
    "start" : "http://localhost:7474/db/data/node/123",
    "property" : "http://localhost:7474/db/data/relationship/34/properties/{key}",
    "self" : "http://localhost:7474/db/data/relationship/34",
    "end" : "http://localhost:7474/db/data/node/124",
    "type" : "KNOWS",
    "properties" : "http://localhost:7474/db/data/relationship/34/properties",
    "data" : {
      "since" : "2010"
    },
    "indexed" : "http://localhost:7474/db/data/index/relationship/my_rels/since/2010/34"
  },
  "from" : "/index/relationship/my_rels"
} ]

Execute multiple operations in batch streaming

Figure 20.80. Final Graph

Example request

POST http://localhost:7474/db/data/batch
Accept: application/json
Content-Type: application/json
X-Stream: true

[ {
  "method" : "PUT",
  "to" : "/node/166/properties",
  "body" : {
    "age" : 1
  },
  "id" : 0
}, {
  "method" : "GET",
  "to" : "/node/166",
  "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/166/properties",
  "body" : null,
  "status" : 204
}, {
  "id" : 1,
  "from" : "/node/166",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 166,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/166/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/166/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/166/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/166/relationships",
    "labels" : "http://localhost:7474/db/data/node/166/labels",
    "traverse" : "http://localhost:7474/db/data/node/166/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/166/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/166/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/166/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/166",
    "incoming_relationships" : "http://localhost:7474/db/data/node/166/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/166/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/166/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 1
    }
  },
  "status" : 200
}, {
  "id" : 2,
  "from" : "/node",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 168,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/168/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/168/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/168/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/168/relationships",
    "labels" : "http://localhost:7474/db/data/node/168/labels",
    "traverse" : "http://localhost:7474/db/data/node/168/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/168/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/168/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/168/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/168",
    "incoming_relationships" : "http://localhost:7474/db/data/node/168/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/168/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/168/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 1
    }
  },
  "location" : "http://localhost:7474/db/data/node/168",
  "status" : 201
}, {
  "id" : 3,
  "from" : "/node",
  "body" : {
    "extensions" : { },
    "metadata" : {
      "id" : 169,
      "labels" : [ ]
    },
    "paged_traverse" : "http://localhost:7474/db/data/node/169/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/169/relationships/out",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/169/relationships/out/{-list|&|types}",
    "create_relationship" : "http://localhost:7474/db/data/node/169/relationships",
    "labels" : "http://localhost:7474/db/data/node/169/labels",
    "traverse" : "http://localhost:7474/db/data/node/169/traverse/{returnType}",
    "all_relationships" : "http://localhost:7474/db/data/node/169/relationships/all",
    "all_typed_relationships" : "http://localhost:7474/db/data/node/169/relationships/all/{-list|&|types}",
    "property" : "http://localhost:7474/db/data/node/169/properties/{key}",
    "self" : "http://localhost:7474/db/data/node/169",
    "incoming_relationships" : "http://localhost:7474/db/data/node/169/relationships/in",
    "properties" : "http://localhost:7474/db/data/node/169/properties",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/169/relationships/in/{-list|&|types}",
    "data" : {
      "age" : 1
    }
  },
  "location" : "http://localhost:7474/db/data/node/169",
  "status" : 201
} ]

The Neo4j Manual v3.1.0-SNAPSHOT20.19. Batch operations