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” | “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, and “batches” = 10, each batched response will have 100 elements. If, for example, a response has 998 elements as a result, and “batches” = 10, there will be 9 batches with 99 elements and the last batch with 107 elements. Each batch contains floor(elements / batches), except the last batch that contains: elements - batch_size * (batches - 1)).

  • “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]. The last batch may contain more elements than batch_size, depending on the total number of elements.

  • “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 with 99 elements each, except the last. In this scenario, “batch_id” = 2 will return elements in the range [199, 296], and “batch_id” = 9 will return elements in the range [792, 891]. If “batch_size” = 10 is specified (instead of “batches”), each batch will have 10 elements. In this scenario, “batch_id” = 2 will return elements in the range [20, 29], and “batch_id” = 9 will return elements in the range [90,99].

  • “range”: specifies a range of the elements to be retrieved. For example, if a response has 998 elements, once can specify the desire “range” = [0,99], retrieving 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:

"FindCommand": {
    "constraints": {
        ...
    },
    "batch": {},
    "results": {
        "list": [...],
    }
}

# 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.
//
# The Response will be in the form:

"FindCommand": {
    "batch": {
        "total_elements": 1000
    }
}

Execute a batch query and retrieve the 18th batch:

"FindCommand": {
    "constraints": {
        ...
    },
    "batch": {
        "batches": 20,
        "batch_id": 18
    },
    "results": {
        "list": [...]
    }
}
# If the result has 1000 elements, each batch has 50 elements.
# This will return elements in the range [900, 949]
//
# The Response will be in the form:

"FindCommand": {
    "batch": {
        "batch_id": 18,
        "batches": 20
    },
    "entities": {
        ...
    },
    "returned": 50
}

Execute a batch query and retrieve the 21th batch:

"FindCommand": {
    "constraints": {
        ...
    },
    "batch": {
        "batch_size": 20,
        "batch_id": 21
    },
    "results": {
        ...
    }
}
# If the result has 1000 elements,
# this will return elements in the range [420, 439]
# The Response will be in the form:

"FindCommand": {
    "batch": {
        "batch_size": 20,
        "batch_is": 21
    },
    "entities": {
        ...
    },
    "returned": 20
}

Execute a batch query and retrieve a range:

"FindCommand": {
    "constraints": {
        ...
    },
    "batch": {
        "range": [134, 286]
    },
    "results": {
        ...
    }
}

# If the result has 250 elements (less than the upper limit of the range),
# this will return elements in the range [134, 249]
# The Response will be in the form:

"FindCommand": {
    "batch": {
        "range": [134, 286]
    },
    "entities": {
        ...
    },
    "returned": 116
}