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 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 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

[{
    "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
    }
}]