Skip to main content

Reading results

A filter selects matching objects; results specifies the information returned about them. Property selection, counts, sorting, and pagination control the response independently of the filter. The examples use the Person objects introduced in Querying data.

Properties and counts​

This complete request returns names and ages and counts all matching adults:

[{"FindEntity": {
    "with_class": "Person",
    "constraints": ["$age", ">=", 18],
    "results": {"list": ["name", "age"], "count": true}
}}]

results.list selects properties. results.all_properties requests all properties instead. The two options are mutually exclusive. results.count counts matches before offset and limit. It is different from returned, which describes returned objects. A reference-only lookup can omit properties and report returned: 0 while still finding objects for a later command.

The results reference also covers sums, averages, grouping, and computed output values. The response field names and failure envelopes are defined in Responses.

Sorting and pagination​

The command-level sort, offset, and limit parameters determine which matches appear on a page. This query returns the first 20 people in name order and includes a count of all matches:

[{"FindEntity": {
    "with_class": "Person",
    "sort": "name",
    "offset": 0,
    "limit": 20,
    "results": {"list": ["name", "age"], "count": true}
}}]

With the same filter and sort, offset: 20 requests the next page. Sorting happens before offset and limit. Equal sort values use object IDs to break ties. Separate page requests do not hold a snapshot across concurrent writes: inserts, updates, or deletes can shift page boundaries. If a stable export is required, coordinate writes with the application.

batch provides cached result sharing for multiple workers. Its cache lifetime and restrictions differ from offset pagination; batching cannot establish _ref for a later command. A batch remains available only for the lifetime of its cache; it is not a persistent cursor.

Media and binary results​

FindImage.blobs controls whether the response includes image data and defaults to false. This query requests the properties and binary data of one image named sample:

[{"FindImage": {
    "constraints": ["$name", "==", "sample"],
    "blobs": true,
    "limit": 1,
    "results": {"list": ["name"]}
}}]

The client returns the JSON response and a separate array of binary buffers. Blob indexes associate each result with its binary data, including when several commands or grouped results share the output list. JSON result positions alone do not identify the corresponding blobs. See blobs, API Description, and the media input and output guide.