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. Inserts, updates, or deletes between page requests can shift page
boundaries, causing objects to be repeated or skipped. If a stable export is
required, coordinate writes with the application.
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.