results

Defines the information returned in the JSON response as a result of a Find* command. results has the following parameters, represented as fields in the JSON object:

Parameters

  • [optional] list: specifies the properties of the object that will be returned. The JSON object will list the properties as key-value pairs, respecting the types.
  • [optional] all_properties: Boolean that specifies that all the properties associated with the object will be retrieved. If “true”, list is ignored.
  • [optional] count: Boolean that specified that only a count of the objects is expected. 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 property key is considered. The property type can be either Integer or Float, an error will be returned otherwise.
  • [optional] average: can be used to request average of the values retrieved for the given property key. Only one property key is considered. The property type can be either Integer or Float, an error will be returned otherwise.
  • [optional] sort_by: 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. When limit is specified, “list”, “average”, and “sum” are computed on the limited number of results.
  • [optional] groupby: can be used so that the results can be grouped together based on the given property’s values. See below for further details.

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.

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": true
}


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


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


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

# Return only the first 150 objects, and sort them by email, sort descinding
"results": {
    "list": ["name", "format"],
    "sort" : {
        "key": "email",
        "order": "descending"
    },
    "limit": 150,
}

Group By

“groups” replaces objects/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. “*” 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.

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