batch
The batching API allows users to specify a query that can be used by multiple workers to retrieve a portion of the results, as explained above. The query must be exactly the same (except from the batching parameters, of course) for all workers. The result is computed once by one worker and re-used by the rest of workers. The result is cached for 60 seconds since the last access. This is, every time a worker retrieves a portion of the result, the timer resets. After the timer goes off, the result will be re-computed if a worker issues the same query.
If the batch JSON object is empty, only the total number of elements will be returned. If either { { { "batches" OR "batch_size" } AND "batch_id" } OR "range" } is specified, a certain number of elements will be returned. All responses are ZERO-indexed. See "Batching" section below for more details.
- "batches": specify the number of desired batches. For example, if a response has 1000 elements as a result, and "batches" = 10, each batched response will have 100 elements. If the number of elements is not divisible by "batches", the last few batched responses will have 1 more item to cover all the results. For example, if a response has 998 elements as a result, and "batches" = 10, the first 2 batched response will have 99 elements and the last 8 batched responses will have 100 elements.
- "batch_size": specify the batch size that will be used. For example, if a response has 1000 elements as a result, and "batch_size" = 10, each batched response will have 10 elements and there will be 100 batches, with ids in the range [0, 99]. If the number of elements is not divisible by "batch_size", the last batch will have fewer elements than "batch_size". For example, if a response has 998 elements as a result, and "batch_size" = 10, each batched response will have 10 elements except for the last one that will have 8 elements and there will be 100 batches, with ids in the range [0, 99].
- "batch_id": specifies the batch to be retrieved. For example, if a response has 998 elements as a result, and "batches" = 10, there will be 10 batches, 2 of them with 99 elements each and 8 of them with 100 elements each. In this scenario, "batch_id" = 2 will return elements in the range [198, 297], and "batch_id" = 9 will return elements in the range [898, 997]. If "batch_size" = 10 is specified (instead of "batches"), each batch will have 10 elements except for the last one that will have 8 elements. In this scenario, "batch_id" = 2 will return elements in the range [20, 29], and "batch_id" = 99 will return elements in the range [990, 997].
- "range": specifies a range of the elements to be retrieved. For example, if a response has 998 elements, one can specify the desired "range" = [0, 99] to retrieve the first 100 elements. If the upper limit of the range is greater than the number of elements in the response, the number of elements to be retrieved will be truncated. This is, if a response has 998 elements and the specified range is [900, 999], the returned range will be [900, 997].
Note: The result of a command with batching cannot be used as a reference for a subsequent command. This is, "_ref" is not allowed in the command if the result block has batching.
Batch Examples
Execute batch query and retrieve the total number of elements:
[{
"FindEntity": {
"with_class": "PersonBatching_1",
"batch": {
},
"results": {
"list": ["name", "age"]
}
}
}]
Given that no parameter is specified in the block size, this query will be executed and only the total number of results will be returned.
Successful response:
[{
"FindEntity": {
"status": 0,
"batch": {
"total_elements": 100
},
"returned": 0
}
}]
Execute a batch query and retrieve the 18th batch:
[{
"FindEntity": {
"with_class": "PersonBatching_2",
"batch": {
"batches": 20,
"batch_id": 18
},
"results": {
"list": ["name", "age"]
}
}
}]
If the result has 100 elements, each batch has 5 elements. This will return elements in the range [90, 95]
Successful response:
[{
"FindEntity": {
"status": 0,
"batch": {
"batch_id": 18,
"batches": 20,
"end": 95,
"start": 90,
"total_elements": 100
},
"entities": [{
"age": 90,
"name": "Person_90"
}, {
"age": 91,
"name": "Person_91"
}, {
"age": 92,
"name": "Person_92"
}, {
"age": 93,
"name": "Person_93"
}, {
"age": 94,
"name": "Person_94"
}],
"returned": 5
}
}]
Execute a batch query and retrieve the 21th batch:
[{
"FindEntity": {
"with_class": "PersonBatching_3",
"batch": {
"batch_size": 20,
"batch_id": 3
},
"results": {
"list": ["name", "age"]
}
}
}]
If the result has 100 elements, this will return elements in the range [60, 80]
Successful response:
[{
"FindEntity": {
"status": 0,
"batch": {
"batch_size": 20,
"batch_id": 3,
"end": 80,
"start": 60,
"total_elements": 100
},
"entities": [{
"age": 60,
"name": "Person_60"
}, {
"age": 61,
"name": "Person_61"
}, {
"age": 62,
"name": "Person_62"
}, {
"age": 63,
"name": "Person_63"
}, {
"age": 64,
"name": "Person_64"
}, {
"age": 65,
"name": "Person_65"
}, {
"age": 66,
"name": "Person_66"
}, {
"age": 67,
"name": "Person_67"
}, {
"age": 68,
"name": "Person_68"
}, {
"age": 69,
"name": "Person_69"
}, {
"age": 70,
"name": "Person_70"
}, {
"age": 71,
"name": "Person_71"
}, {
"age": 72,
"name": "Person_72"
}, {
"age": 73,
"name": "Person_73"
}, {
"age": 74,
"name": "Person_74"
}, {
"age": 75,
"name": "Person_75"
}, {
"age": 76,
"name": "Person_76"
}, {
"age": 77,
"name": "Person_77"
}, {
"age": 78,
"name": "Person_78"
}, {
"age": 79,
"name": "Person_79"
}],
"returned": 20
}
}]
Execute a batch query and retrieve a range:
[{
"FindEntity": {
"with_class": "PersonBatching_4",
"batch": {
"range": [234, 286]
},
"results": {
"list": ["name", "age"]
}
}
}]
If the result has 250 elements (less than the upper limit of the range), this will return elements in the range [234, 249]
Successful response:
[{
"FindEntity": {
"status": 0,
"batch": {
"range": [234, 286],
"start": 234,
"end": 250,
"total_elements": 250
},
"entities": [{
"age": 234,
"name": "Person_234"
}, {
"age": 235,
"name": "Person_235"
}, {
"age": 236,
"name": "Person_236"
}, {
"age": 237,
"name": "Person_237"
}, {
"age": 238,
"name": "Person_238"
}, {
"age": 239,
"name": "Person_239"
}, {
"age": 240,
"name": "Person_240"
}, {
"age": 241,
"name": "Person_241"
}, {
"age": 242,
"name": "Person_242"
}, {
"age": 243,
"name": "Person_243"
}, {
"age": 244,
"name": "Person_244"
}, {
"age": 245,
"name": "Person_245"
}, {
"age": 246,
"name": "Person_246"
}, {
"age": 247,
"name": "Person_247"
}, {
"age": 248,
"name": "Person_248"
}, {
"age": 249,
"name": "Person_249"
}],
"returned": 16
}
}]