.. _FindEntity: FindEntity ========== Find all entities that satisfy the specified constraints. Requires an authenticated user with ``objects.read`` permission. See :doc:`../API-Description` for query and blob ordering, and :doc:`../Responses` for response fields and errors. Parameters ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 22 18 60 * - Parameter - Type / required - Default and behavior * - :ref:`with_class ` - string / optional - Omitted: search all entity classes; otherwise restrict the class. Details ------- If **with_class** is omitted, entities of any class that satisfy the constraints are eligible. Specify **results**, **_ref**, or ``"uniqueids": true``. The command returns an error if none is specified. If **constraints** is omitted, no property filter is applied. Class and relationship restrictions still apply, as do **offset** and **limit**. Use :ref:`text search expressions ` inside constraints for fuzzy or full-text matching, and an explicit sort expression for relevance ordering. .. include:: group_by_source_details.rst Response and recovery --------------------- The response contains ``status`` and ``returned``. Requested properties appear in ``entities``; requested aggregates such as ``count`` are separate fields. A lookup that only declares ``_ref`` returns ``returned: 0`` even if it matched objects. Request ``results: {"count": true}`` to inspect the match count. * Missing output selection or an invalid reference returns ``status: -1``. Supply ``results``, ``_ref``, or ``uniqueids: true`` and declare references earlier in the same query. * A violated ``unique: true`` expectation can return ``status: 3``. Check the filter and remove the uniqueness requirement if multiple matches are intended. * ``per_group: true`` without ``group_by_source: true`` returns ``status: -1`` with ``per_group requires group_by_source``. Errors may use a top-level object instead of a command result; check the envelopes in :doc:`../Responses`. See :doc:`AddEntity` to create the data and :doc:`FindConnection` to inspect relationships. Examples -------- Find an entity of class "Visit" where its "start_year" property is on or after August 7, 2016, and retrieve other properties of the visit: .. TESTED_EXAMPLE: FindEntity_1 .. code-block:: json [{ "FindEntity": { "with_class": "Visit", "constraints": [ "$start_year", ">=", { "to_date": "Sun Aug 7 10:59:24 PDT 2016" } ], "results": { "list": ["start_year", "billing_id"] } } }] Successful response: .. TESTED_EXAMPLE: FindEntity_1_response .. code-block:: json [{ "FindEntity": { "status": 0, "returned": 1, "entities": [{ "_class": "Visit", "start_year": { "_date": "2017-08-07T10:59:24-07:00" }, "billing_id": 123 }] } }] Find the entities of the class "Visit" where its "start_year" property is on or after August 6, 2016 that are associated with a "Patient" with a "unique_id" equal to 4325, and retrieve other properties of the visit: .. TESTED_EXAMPLE: FindEntity_2 .. code-block:: json [{ "FindEntity": { "with_class": "Patient", "_ref": 1, "unique": true, "constraints": ["$unique_id", "==", 4325] } }, { "FindEntity": { "with_class": "Visit", "constraints": [ "$start_year", ">=", { "to_date": "Sat Aug 6 10:59:24 PDT 2016" } ], "is_connected_to": { "ref": 1, "direction": "in", "connection_class": "PatientMadeVisit" }, "results": { "list": ["start_year", "end_year", "billing_id"] } } }] The first command retains a reference without returning properties, so ``returned: 0`` does not mean that no patient matched. In the response below, the second command finds no matching visits. Visit properties are returned when a qualifying visit has the specified ``PatientMadeVisit`` connection. Response with no matching visits: .. TESTED_EXAMPLE: FindEntity_2_response .. code-block:: json [{ "FindEntity": { "returned": 0, "status": 0 } }, { "FindEntity": { "returned": 0, "status": 0 } }]