Query and retrieve data

REST API

Querying and retrieveing data from Atomik is very simple. For retrieveing complete objects by their ID, there are specific GET operations in the REST API like GET /ehr, GET /composition, GET /actor, etc.

Queries

For retrieving objects based on a criteria or datavalues from many objects, a query should be created by using the Query Builder that comes with Atomik. As mentioned in the queries section

In Atomik all queries use the data structures defined in openEHR Operational Templates as metadata for the query. For instance, a combination of archetype ID and path is used to reference a specific node in the template definition, that node is actually an openEHR constraint from the AOM specification which defines terminology, structural constraints and data constraints. All that information is used to create a criteria in a query. For instance if an archetype ID and path reference a DV_CODED_TEXT node in the template, and that constraint contains a list of possible codes, we can use those codes in the query creation because we know for that coded text node, the only values allowed are the ones defined by that constraint. That is not only using available metadata, making queries consistent with the data they suppose to retrieve, it is also faster to build queries because all those constraints are shown at the moment of building the data query.

Query types

Atomik supports the following query types: composition, ehr_status, folder, actor, party_relationship and datavalue. The first five types will retrieve objects, and the datavalue type of query will retrieve specific data points.

Query parameters

For the queries that retrieve objects, there are many options for the results, that can be set at the moment of creating the query or at the moment of executing a query, by providing parameters when invoking the REST API. Atomik queries support a retrieve_data flag that is false by default, when the flag is false the query execution will retrieve references to the matched objects, then a client can use their ID to retrieve the complete objects if they need to. If the retrieve_data flag is true, then the complete openEHR object is retrieved in JSON or XML.

The output format of the query results is another parameter that can be set when creating the query or when executing a query. Current allowed values are json and xml.

A population query is a query that doesn't select a specific patient. If a client doesn't want to do a population query, an ehrId parameters is available, so they can set a specific EHR as the context of the query results and the results will only contain objects for that EHR. If the ehrId parameter is empty, the query is going to be evaluated against all EHRs.

Grouping

Then queries that retrieve objects (composition, actor, folder, etc) group the results by EHR ID, for all the objects contained in an EHR, and will be grouped in the demographics group when related to demographic objects (actor or party relationship). This way it's easy to do population queries and keep track to which EHR each object belongs to.

For datavalue queries, there are three possible ways of grouping the data points from the results: ungruped, by path or by locatable. As ungrouped, all results will be returned in a flat structure, which is useful when clients want to process that data themselves. Grouping by path allows to put all the results for the same data point in the same list, this is a good structure for charting data because each list of data of the same time can be seen as a time series of data points. Lastly, grouping by locatable returns the data values grouped by the identifier of the locatable object that contains the values.

Combined queries

Combined queries is another way of retrieving information from Atomik, and has a very specific purpose: support statistical queries.

Combined queries use existing composition queries as conditions to check if an EHR contains any composition that matches the query. If all composition queries return a non-empty result, then the EHR that contains those compositions will be included in the combined query result. That way a client can count EHRs that match very comples conditions, retrieve their ID, and use the results to inject knowledge in other systems, like Clinical Decision Support Systems (CDSS). A possible use case is to select patient with multiple risk factors and through a CDSS show an alert to the clinician for that patient, so the clinician can take a proactive action like recommending some treatment or proposing specific care plans, which can be suggested by the CDSS based on international protocols.

More about combined queries in the combined queries section.