results

Defines the information expected in the returned JSON response object when querying for something using Find* calls.

Parameters

  • [optional] list: can be used when specifies the properties of the object that need to be returned. The JSON object will list the properties as key-value pairs, respecting the types.

  • [optional] count: is provided as “count”: “” to indicate an empty value. It returns the total number of objects that matched the search condition.

  • [optional] sum: can be used to request sum of the values retrieved for the given property key. Only one key is considered. The returned type can be an Integer or Float. This call will return error if the property is not an integer or float value.

  • [optional] average: can be used to request average of the values retrieved for the given property key. Only one key is considered. The returned type can be an Integer or Float. This call will return error if the property is not an integer or float value.

  • [optional] sort: specifies that we should sort the results by the first key provided. Once sorted, all operations on that particular find will happen on the sorted order by the key.

  • [optional] limit: specifies the maximum number of elements that will be returned. This is applied to all but the “count” option when specified.

  • [optional] return_blob: specifies whether you want a blob as a result of this call or not. Typically applies to images, videos, descriptors but can also be used for entities that were stored with a blob. Default is false for entities and true for others. e.g. a blob will be returned unless this is set to false when asking for results in FindImage, FindVideo, FindDescriptors but not with FindEntity where the default is false.

  • [optional] batch: request for the response to be batched. If the batch block 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 elements are ZERO-indexed. See “Range Examples” below for more details.

    • “batches”: specify the number of batches that the server will generate. For example, if a response has 1000 elements as a result, 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 100 elements and 1 batch with 98 elements. Each batch contains ceil(elements / batches), except the last batch that contains: elements - ( (batches - 1) * ceil(elements / batches))
    • “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].
    • “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 (each batch will have an id in the range [0,9]). In this scenario, “batch_id” = 2 will return elements in the range [200, 299], and “batch_id” = 9 will return elements in the range [900, 998]. If “batch_size” = 10 is specified (instead of “batches”), each bach 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].

While all the keywords listed above are optional, exactly one of ‘list’, ‘count’, ‘sum’, or ‘average’ must be specified if a “result” block is used. If no results block is specified for a Find call, only a success or failure status is returned and the results of the query are cached on the server if the local id is provided in the function call.

When sort is specified, it takes precedence over the other operations. So list will be returned in the sorted order based on the chosen key. From a performance point of view, sort makes the query traverse all the results matching the constraints before sorting.

When limit is specified, list, average, or sum are computed on the limited number of results.

Example

# Get "name" and "format" properties for the first 150 results
"results": {
    "list": ["name", "format"],
    "limit": 150,
}


# Return only the number of results
"results": {
    "count": "", # Empty string. Any other string as value will be ignored.
}


# Return only the first 2 instances, and average the value of those 2.
"results": {
    "average": "age",
    "limit" : 2 # only average first 2
}


# Returns the sum of the "number_of_cars" properties for all entities
"results": {
    "sum": "number_of_cars",
}


# Return only the first 150 instances, and sort them by email
"results": {
    "list": ["name", "format"],
    "sort" : "email",
    "limit": 150,
}

Range Example

Execute batch query and retrieve the total number of elements:

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

# Given that no parameter is specified in the block size,
# this quiery 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": {
        ...
    },
    "results": {
        "list": [...]
        "batch": {
            "batches": 20,
            "batch_id": 18
        }
    }
}
# 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": {
        ...
    },
    "results": {
        "batch": {
            "batch_size": 20,
            "batch_id": 21
        }
    }
}
# 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": {
        ...
    },
    "results": {
        "batch": {
            "range": [134, 286]
        }
    }
}
# 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": 162
}