FindEntity

Find all entities that satisfy the specified constraints.

Requires an authenticated user with objects.read permission. See API Description for query and blob ordering, and Responses for response fields and errors.

Parameters

Parameter	Type / required	Default and behavior
_ref	integer / optional	Omitted: do not retain a reference for later commands in this query.
unique	Boolean / optional	false; require exactly one match when true.
constraints	expression / optional	Omitted: no property filter; other restrictions still apply.
is_connected_to	object / optional	Omitted: no graph-neighbor restriction.
is_endpoint_of	object / optional	Omitted: no connection-endpoint restriction.
group_by_source	Boolean / optional	false; group matches by the source of a relationship lookup.
per_group	Boolean / optional	false; true requires group_by_source: true and applies sort, offset and limit within each source group.
results	object / optional	Omitted: no requested property projection or aggregate. Select output or retain a reference as described below.
batch	object / optional	Omitted: no distributed result batching.
sort	string, object, or array / optional	Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering.
limit	integer 0–2147483647 / optional	Omitted: no explicit result-count limit.
offset	integer 0–2147483647 / optional	0; skip this many matches after sorting.
uniqueids	Boolean / optional	false; include object identifiers when true.

Parameter	Type / required	Default and behavior
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 text search expressions inside constraints for fuzzy or full-text matching, and an explicit sort expression for relevance ordering.

If only one ref parameter is used in the is_connected_to array, the resulting objects obtained after traversing the given connection can be associated with their source objects by specifying the parameter group_by_source as true. The parameter is ignored if is_connected_to is absent. It is set to false by default.

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 Responses. See AddEntity to create the data and 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:

[{
    "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:

[{
    "FindEntity": {
        "status": 0,
        "returned": 1,
        "entities": [{
            "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:

[{
    "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:

[{
    "FindEntity": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindEntity": {
        "returned": 0,
        "status": 0
    }
}]