.. _reading-results: 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 :doc:`QueryingData`. .. _request-properties-and-counts: Properties and counts --------------------- This complete request returns names and ages and counts all matching adults: .. code-block:: json [{"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 :doc:`parameters/results` reference also covers sums, averages, grouping, and computed output values. The response field names and failure envelopes are defined in :doc:`Responses`. .. _read-a-page: 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: .. code-block:: json [{"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. .. _retrieve-media: 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``: .. code-block:: json [{"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 :doc:`parameters/blobs`, :doc:`API-Description`, and the `media input and output guide `_.