Query API

Common Headers and Query Parameters ¶

All query execution requests SHOULD support at least the following parameters:

• ehr_id - used to execute the query within a single EHR context: an EHR identifier taken from EHR.ehr_id.value

• offset - used for paging: the row number in result to start result-set from (0-based); default 0

• fetch - used for paging: the number of rows to fetch (i.e. limit); default depends on the implementation, but cannot be combined with AQL-top

• other parameter(s) to replace placeholder(s) within the query, generically named query_parameters here.

Related request headers:

• openEHR-EHR-id - used to execute the query within a single EHR context: an EHR identifier taken from EHR.ehr_id.value

Related response headers:

• ETag - A unique identifier of the resultSet

About the ehr_id parameter

This parameter SHOULD be supplied by clients when executing single EHR queries and MAY be used by the underlying backend to perform routing, optimizations or similar. It MUST NOT be supplied for ‘population queries’ and similar multi-patient queries.

Depending on the needs, clients MAY supply it as a query parameter ehr_id or alternatively as a request header named openEHR-EHR-id.

About query_parameter

Depending on each query definition, various query parameters SHOULD be supported, generically named query_parameter in this specification, but in the real request they will have specific names (e.g. uid, systolic_bp, etc.) according to their names in the query definition.

Provided query parameters SHOULD NOT be prefixed with $ sign. Instead, the server will (whenever necessary) add the prefix or format queries as valid AQL queries.

As an example, for the following AQL query SELECT c/name/value FROM COMPOSITION c WHERE c/uid/value = $uid, named as 'myQuery', the client can supply the uid as query_parameter, i.e. GET {baseUrl}/query/myQuery?uid=90910cf0-66a0-4382-b1f8-c0f27e81b42d::openEHRSys.example.com::1.

As another example, the request GET {baseUrl}/query/com.vendor::compositions?temperature_from=36&temperature_unit=Cel will pass query parameters temperature_from and temperature_unit to the underlying AQL query named com.vendor::compositions.

See AQL-parameters specification for more details.

Request structure ¶

Below is a mostly self-documented AQL query request.

{
    "q": "select o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/magnitude as temperature, o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/units as unit from EHR[ehr_id/value='554f896d-faca-4513-bddf-664541146308d'] CONTAINS Observation o[openEHR-EHR-OBSERVATION.body_temperature-zn.v1] WHERE o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/magnitude > $temperature and o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0.63 and name/value='Symptoms']/value/defining_code/code_string=$chills order by temperature desc fetch 3",
    "query_parameters": {
        "temperature": 38.5,
        "chills": "at0.64"
    }
}

GET vs POST

Requests based on GET method have URI length restriction or some characters might not be allowed and have to be encoded. Long queries in the q parameter and having a long list of query_parameter may add up to reach that limit, thus we recommend clients using the POST method instead of GET.

Response structure ¶

Metadata

Data

ResultSet example

Below is a synthesized response with all attributes.

{
                "meta": {
                    "_href": "... the URI for the executed AQL - used only for GET executions ...",
                    "_type": "RESULTSET",
                    "_schema_version": "1.0.0",
                    "_created": "2017-08-19T00:25:47.568+02:00",
                    "_generator": "DIPS.OpenEhr.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)",
                    "_executed_aql": "... the executed aql ..."
                },
                "name": "... the name or identifier of the stored query that was executed ...",
                "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, c/uid/value as cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
                "columns": [
                    {
                        "name": "#0",
                        "path": "/ehr_id/value"
                    },
                    {
                        "name": "startTime",
                        "path": "/context/start_time/value"
                    },
                    {
                        "name": "cid",
                        "path": "/uid/value"
                    },
                    {
                        "name": "#3",
                        "path": "/name"
                    }
                ],
                "rows": [
                    [
                        "81433066-c417-4813-9b29-79783e7bed23",
                        "2017-02-16T13:50:11.308+01:00",
                        "90910cf0-66a0-4382-b1f8-c0f27e81b42d::openEHRSys.example.com::1",
                        {
                            "_type": "DV_TEXT",
                            "value": "Labs"
                        }
                    ]
                ]
            }

Execute Query ¶

This currently supports AQL queries only, other query types might be added in the future.