.. _results: results ======= The **results** object specifies which properties, expression values, counts, and aggregates a Find* command returns. **list** selects properties, **expressions** computes output values, and **all_properties** returns every property. **count** counts matches before **offset** and **limit**. All members are optional. Omitting ``results`` requests no property projection or aggregate; other command options can still request output or retain a reference. ``count`` and ``all_properties`` are Booleans defaulting to false. ``list`` is a nonempty array of property-name strings; ``expressions`` is an object mapping output names to expressions. ``sum``, ``avg``, ``min``, and ``max`` accept a property name or an array of names; ``group`` accepts a name or an array of names. Omitted projection and aggregate members produce no corresponding output. 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 :ref:`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**: returns the sum of 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] **avg** (alias **average**): returns the average of 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**: returns the minimum value retrieved for the given property key. The value can be a single property key or a list of property keys. * [optional] **max**: returns the maximum value retrieved for the given property key. The value can be a single property key or a list of property keys. * [optional] **group**: groups results by the values of the specified properties. With :ref:`group_by_source`, the response omits **count** and scalar aggregates such as **sum**, **avg**, **min**, and **max**. **group** takes precedence over source grouping; the two grouping modes do not combine. Examples ++++++++ Get "name" and "format" properties of all the objects .. TESTED_EXAMPLE: results_1 .. code-block:: json [{ "FindImage": { "results": { "list": ["name", "format"] } } }] Return :ref:`text search scores ` and other computed values alongside a property: .. code-block:: json [{ "FindEntity": { "with_class": "Person", "results": { "list": ["name"], "expressions": { "nameScore": {"isimilarity": ["$name", "alen"]}, "displayName": {"upper": "$name"} } } } }] Return only the number of results .. TESTED_EXAMPLE: results_2 .. code-block:: json [{ "FindImage": { "results": { "count": true } } }] Return the average age .. TESTED_EXAMPLE: results_3 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "results": { "average": "age" } } }] Return the sum of "number_of_cars" for all matching entities .. TESTED_EXAMPLE: results_4 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "results": { "sum": "number_of_cars" } } }] Return the minimum and maximum age .. TESTED_EXAMPLE: results_5 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "results": { "min": "age", "max": "age" } } }] Return the minimum and maximum age, height, and weight .. TESTED_EXAMPLE: results_6 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "results": { "min": ["height", "weight", "age"], "max": ["height", "weight", "age"] } } }] Return the first 150 objects sorted by email .. TESTED_EXAMPLE: results_7 .. code-block:: json [{ "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. .. TESTED_EXAMPLE: results_8 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "results": { "group": ["year_captured"] } } }] Response .. TESTED_EXAMPLE: results_8_response .. code-block:: json [{ "FindImage": { "groups": [{ "_group_class": "Images", "_group_count": 8, "year_captured": 1874 }, { "_group_class": "Images", "_group_count": 17, "year_captured": 1875 }, { "_group_class": "Images", "_group_count": 25, "year_captured": 1876 }], "returned": 0, "status": 0 } }] Grouping with multiple properties .. TESTED_EXAMPLE: results_9 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "sort": [{ "key": "year_captured" }, { "key": "event" }], "results": { "group": ["year_captured", "event"] }, "blobs": true } }] Response: .. TESTED_EXAMPLE: results_9_response .. code-block:: json [{ "FindImage": { "blobs_start": 0, "groups": [{ "_group_class": "Images", "_group_count": 8, "event": "April Festival", "year_captured": 1874 }, { "_group_class": "Images", "_group_count": 9, "event": "April Festival", "year_captured": 1875 }, { "_group_class": "Images", "_group_count": 8, "event": "June Festival", "year_captured": 1875 }, { "_group_class": "Images", "_group_count": 17, "event": "April Festival", "year_captured": 1876 }, { "_group_class": "Images", "_group_count": 8, "event": "June Festival", "year_captured": 1876 }], "returned": 50, "status": 0 } }] Sorting on the grouping properties and aggregate function sum. .. TESTED_EXAMPLE: results_10 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "sort": [{ "key": "event" }, { "key": "year_captured" }], "results": { "group": ["year_captured", "event"], "sum": "number_of_people" } } }] Response: .. TESTED_EXAMPLE: results_10_response .. code-block:: json [{ "FindImage": { "groups": [{ "_group_class": "Images", "_group_count": 8, "_group_sum": { "number_of_people": 240 }, "event": "April Festival", "year_captured": 1874 }, { "_group_class": "Images", "_group_count": 9, "_group_sum": { "number_of_people": 288 }, "event": "April Festival", "year_captured": 1875 }, { "_group_class": "Images", "_group_count": 17, "_group_sum": { "number_of_people": 830 }, "event": "April Festival", "year_captured": 1876 }, { "_group_class": "Images", "_group_count": 8, "_group_sum": { "number_of_people": 388 }, "event": "June Festival", "year_captured": 1875 }, { "_group_class": "Images", "_group_count": 8, "_group_sum": { "number_of_people": 240 }, "event": "June Festival", "year_captured": 1876 }], "returned": 0, "status": 0 } }] Multiple aggregate functions .. TESTED_EXAMPLE: results_11 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "results": { "group": ["event"], "sum": ["number_of_people"], "average": "exposure" } } }] Response: .. TESTED_EXAMPLE: results_11_response .. code-block:: json [{ "FindImage": { "groups": [{ "_group_avg": { "exposure": 0.5 }, "_group_class": "Images", "_group_count": 34, "_group_sum": { "number_of_people": 1358 }, "event": "April Festival" }, { "_group_avg": { "exposure": 2 }, "_group_class": "Images", "_group_count": 16, "_group_sum": { "number_of_people": 628 }, "event": "June Festival" }], "returned": 0, "status": 0 } }]