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] 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 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].
  • [optional] “groupby” = “<property key>”: can be used so that the results can be grouped together based on the given property’s values. Code example shows how the entities/connections will be presented.

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.

Tip: You can specify “list” = [ “*” ] to access all the properties in searched entities or connections.

Examples

# 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,
}

Group By

“groups” replaces entities/connections in the JSON response structure. The aggregation operations like “sum”, and “average” will work within groups for the given property keys. Count per group (“_groupcount”) and number of groups (“returned”) are returned by default. One could also request properties that are known to have the same value across all entities in a group. If they are not, the behavior is undefined (or usually the first matching entities’ property value). “returned” will indicate the number of total groups.

groupby exceptions: Currently we do not sort on group values. We will add that support in the future. Group by on connection queries is implemented but not tested. “*” carries no meaning in the list here and might return an error. If a groupby property is not defined for some entities in the list, it returns an error. Even if blobs are set to true in FindImage etc, they won’t be returned with groupby. groupby does not currently apply to FindFrames or to FindBoundingBox.

# When "groupby" is used within the results blocks of say FindEntity,
# the entities will be presented in groups with a new hierarchy as below
"groups": [
    {
        "_groupvalue" : <value of the property being grouped on>,
        "_groupcount" : <number of entities in that group>,
        # <other requested properties with their values that should be the same across all entities in that group>,
        # <aggregates as in sum(<keyname>): <sum> >
    }
]

Batching

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.

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": {
        ...
    },
    "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
}