results

The results object specifies which properties, expression values, counts, and aggregates a Find* command returns. Use list to select properties, expressions to compute output values, or all_properties to return every property. Use count to count matches before offset and limit.

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] expressions: An object mapping output names to value expressions from the constraint grammar. Values appear beside listed properties in every returned entity or connection; missing expression values appear explicitly as JSON null. Names follow ordinary property naming rules and must be distinct ignoring case. They cannot overlap list, including wildcard selections. Expressions cannot accompany all_properties or group. Names are output aliases, not properties that other expressions can reference.
• [optional] all_properties: Boolean that specifies that all the properties associated with the object will be retrieved. Cannot accompany list or expressions.
• [optional] count: Boolean requesting the number of objects matching the constraints before pagination. Can accompany list and expressions.
• [optional] sum: can be used to request sum of the values retrieved for the given property key. The value can be a single property key or a list of property keys. The result will sum all the values of type Number.
• [optional] average: can be used to request average of the values retrieved for the given property key. The value can be a single property key or a list of property keys. The result will average all the values of type Number or DateTime.
• [optional] min: can be used to request min of the values retrieved for the given property key. The value can be a single property key or a list of property keys.
• [optional] max: can be used to request max of the values retrieved for the given property key. The value can be a single property key or a list of property keys.
• [optional] group: can be used to group the results together based on the specified property’s values. See below for further details.

If group_by_source is set to True and the results parameter has any of these specified: count, sum, average, min, max and group, query returns with an error.

Examples

Get "name" and "format" properties of all the objects

[{
    "FindImage": {
        "results": {
            "list": ["name", "format"]
        }
    }
}]

Return text search scores and other computed values alongside a property:

[{
    "FindEntity": {
        "with_class": "Person",
        "results": {
            "list": ["name"],
            "expressions": {
                "nameScore": {"isimilarity": ["$name", "alen"]},
                "displayName": {"upper": "$name"}
            }
        }
    }
}]

Return only the number of results

[{
    "FindImage": {
        "results": {
            "count": true
        }
    }
}]

Return the average age

[{
    "FindEntity": {
        "with_class": "Person",
        "results": {
            "average": "age"
        }
    }
}]

Return the sum of "number_of_cars" for all matching entities

[{
    "FindEntity": {
        "with_class": "Person",
        "results": {
            "sum": "number_of_cars"
        }
    }
}]

Return the minimum and maximum age

[{
    "FindEntity": {
        "with_class": "Person",
        "results": {
            "min": "age",
            "max": "age"
        }
    }
}]

Return the minimum and maximum age, height, and weight

[{
    "FindEntity": {
        "with_class": "Person",
        "results": {
            "min": ["height", "weight", "age"],
            "max": ["height", "weight", "age"]
        }
    }
}]

Return the first 150 objects sorted by email

[{
    "FindEntity": {
        "with_class": "Person",
        "sort": "email",
        "limit": 150,
        "results": {
            "list": ["name"]
        }
    }
}]

Grouping results

group statement groups results that have the same values for specified properties. group is often used with aggregate functions (count, sum, average, min, max) to group the result-set by one or more properties.

[{
    "FindImage": {
        "constraints": {
            "year_captured": [">=", 1870]
        },
        "blobs": false,
        "results": {
            "group": ["year_captured"]
        }
    }
}]

Response

[{
    "FindImage": {
        "groups": [{
            "_group_class": "_Image",
            "_group_count": 8,
            "year_captured": 1874
        }, {
            "_group_class": "_Image",
            "_group_count": 17,
            "year_captured": 1875
        }, {
            "_group_class": "_Image",
            "_group_count": 25,
            "year_captured": 1876
        }],
        "returned": 0,
        "status": 0
    }
}]

Grouping with multiple properties

[{
    "FindImage": {
        "constraints": {
            "year_captured": [">=", 1870]
        },
        "sort": [{
            "key": "year_captured"
        }, {
            "key": "event"
        }],
        "results": {
            "group": ["year_captured", "event"]
        },
        "blobs": true
    }
}]

Response:

[{
    "FindImage": {
        "blobs_start": 0,
        "groups": [{
            "_group_class": "_Image",
            "_group_count": 8,
            "event": "April Festival",
            "year_captured": 1874
        }, {
            "_group_class": "_Image",
            "_group_count": 9,
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "_group_class": "_Image",
            "_group_count": 8,
            "event": "June Festival",
            "year_captured": 1875
        }, {
            "_group_class": "_Image",
            "_group_count": 17,
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "_group_class": "_Image",
            "_group_count": 8,
            "event": "June Festival",
            "year_captured": 1876
        }],
        "returned": 50,
        "status": 0
    }
}]

Sorting on the grouping properties and aggregate function sum.

[{
    "FindImage": {
        "constraints": {
            "year_captured": [">=", 1870]
        },
        "blobs": false,
        "sort": [{
            "key": "event"
        }, {
            "key": "year_captured"
        }],
        "results": {
            "group": ["year_captured", "event"],
            "sum": "number_of_people"
        }
    }
}]

Response:

[{
    "FindImage": {
        "groups": [{
            "_group_class": "_Image",
            "_group_count": 8,
            "_group_sum": {
                "number_of_people": 240
            },
            "event": "April Festival",
            "year_captured": 1874
        }, {
            "_group_class": "_Image",
            "_group_count": 9,
            "_group_sum": {
                "number_of_people": 288
            },
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "_group_class": "_Image",
            "_group_count": 17,
            "_group_sum": {
                "number_of_people": 830
            },
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "_group_class": "_Image",
            "_group_count": 8,
            "_group_sum": {
                "number_of_people": 388
            },
            "event": "June Festival",
            "year_captured": 1875
        }, {
            "_group_class": "_Image",
            "_group_count": 8,
            "_group_sum": {
                "number_of_people": 240
            },
            "event": "June Festival",
            "year_captured": 1876
        }],
        "returned": 0,
        "status": 0
    }
}]

Multiple aggregate functions

[{
    "FindImage": {
        "constraints": {
            "year_captured": [">=", 1870]
        },
        "blobs": false,
        "results": {
            "group": ["event"],
            "sum": ["number_of_people"],
            "average": "exposure"
        }
    }
}]

Response:

[{
    "FindImage": {
        "groups": [{
            "_group_avg": {
                "exposure": 0.5
            },
            "_group_class": "_Image",
            "_group_count": 34,
            "_group_sum": {
                "number_of_people": 1358
            },
            "event": "April Festival"
        }, {
            "_group_avg": {
                "exposure": 2
            },
            "_group_class": "_Image",
            "_group_count": 16,
            "_group_sum": {
                "number_of_people": 628
            },
            "event": "June Festival"
        }],
        "returned": 0,
        "status": 0
    }
}]