21.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]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 21.77. Starting Graph

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

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

Execute multiple operations in batch streaming

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