Document-First openEHR Persistence Layer

Reconcile Clinical Query Families

This solution addresses that problem with a document-first, semi-flattened persistence model on MongoDB. Semi-flattened means that we flatten each element as a node in an array, but each preserves the full JSON payload in the original structure. Document-first means that each openEHR composition is preserved as one MongoDB document, rather than being decomposed into one table per archetype or one row per path. At the same time, the composition is materialized as a reconstructable node array, enabling efficient path-based querying without abandoning the composition as the operational unit.

Each stored node retains the following key elements:

• Local clinical subtree, so the original meaning and context remain available.

• Positional metadata, so structure and ordering can be reconstructed.

• Reversed AQL path, which enables efficient matching of variable-depth path constraints.

The reversed path is a general query key used to evaluate structural predicates efficiently across both the patient-scoped and cross-patient execution routes. It supports path-constrained matching across different execution strategies, including regex-based matching and wildcard-style path resolution in search indexes. The same query patterns can be applied when predicates use other textual path components or textual conditions.

With this model, AQL clauses can be compiled deterministically into MongoDB query stages. FROM, CONTAINS, and WHERE constraints become targeted predicates over node paths and values. This approach keeps the composition intact as the primary clinical container while still making operational retrieval practical at scale.

Figure 1. Representation of semi-flattened compositions where each node carries its own context and values plus the reversed AQL path

Routing by Workload

For many repositories, a single semi-flattened collection and wilcard indexes are sufficient. For larger deployments, the model can use a slim search projection that contains only the data needed for wide cross-patient filtering. Query execution is then routed by scope. A slim search projection is a smaller derived collection that stores only the node fields needed for broad cross-patient filtering. It does not replace the main composition document. It reduces index breadth and search cost for wide operational queries.

Therefore, it provides the following modalities:

• Patient-scoped queries run on the main composition collection, using targeted indexes such as a compound index on fields like ehr_id and reversed_path.

• Cross-patient queries run against the slimmer projection, compiling path constraints into wildcards or matches on the reversed path, and value predicates into equality, range, or search operators.

This execution model provides a single query interface, allowing different physical access paths based on workload size and selectivity.

Why Supporting Operation Cohort Queries Matter

Modern clinical applications increasingly need both query families on the same platform. A clinician might need to open one patient record immediately and ask questions such as:

• Which patients received a certain medication in a given time window?

• Which patients match a protocol or safety rule?

• Which prior cases are clinically similar to this one?

These operational questions require answers without pushing data through repeated ETL cycles into separate systems.

A document-first, semi-flattened model preserves the strengths of openEHR and makes those workloads practical. It keeps the composition as the authoritative operational unit, preserves clinical fidelity through reconstructable structure, and avoids forcing application teams to choose between a patient-centric store and a separate cross-patient platform. Smaller repositories can remain simple, with one semi-flattened collection. Larger repositories can add a smaller projection to reduce the cost of broad operational filtering.

In our evaluation, this approach maintained low end-to-end latency across both workload types, with low response times for patient-scoped and cross-patient queries, even at large scale. This efficiency validates it as a practical foundation for openEHR repositories that must support operational retrieval, provenance-aware processing, semantic enrichment, and AI-driven workflows from one platform.

You can explore this pattern with kehrnel, an experimental reference runtime and toolkit for document-first clinical data strategies.

Following this approach gives you the following practical benefits:

• A reconstructable semi-flattened model that preserves composition fidelity.

• Efficient patient-scoped querying without forcing a relational shred of the clinical document.

• Support for cross-patient operational retrieval without defaulting to a warehouse-first architecture.

• One operational query surface for application teams, instead of duplicated stores and fragmented logic.

• A path to lower ETL overhead, lower governance drift, and lower total cost of ownership.

What Is Kehrnel and Why Use It?

Kehrnel is a strategy runtime that turns healthcare data models into operational capabilities. Kehrnel exists because defining a healthcare data model is not enough. Teams also need a repeatable way to validate data, transform it into an operational representation, ingest it, query it, maintain it, and evolve it as requirements change. Without that execution layer, models often remain documentation, storage schemas, or isolated specifications.

The goal is broader than building an openEHR engine. Kehrnel provides a repeatable document-first approach for making healthcare data models executable, inspectable, and reusable across APIs, tooling, and AI workflows. Over time, the same runtime pattern can support other model families and operational strategies, including FHIR, synthetic data workflows, semantic catalogs, natural language retrieval, and other domain-specific tools.

Kehrnel is designed around exposed workflows that can be customized for the needs of each persistence strategy. Each strategy can define its own activation, validation, ingestion, transformation, query, synthetic-data, and maintenance operations, while still using a consistent runtime model.

Kehrnel starts with openEHR because openEHR is a demanding, semantic-rich model. It includes archetypes, templates, paths, terminology, and complex query behavior. That makes it a strong foundation for proving a model-driven runtime approach.

For this solution, Kehrnel serves as the reference runtime and toolkit for the document-first persistence pattern.

Figure 2. Kehrnel CLI screenshot

How to Read This Document

One MongoDB document represents one openEHR composition. The cn array stores the queryable nodes extracted from that composition. Each node keeps a local clinical subtree in data, a reversed path key in p, and positional metadata such as kp, pi, and bk so the original structure can be reconstructed.

The public example shows the path key in a readable form to make the translation easier to follow. In production, you can store the same path as compact dictionary-encoded tokens to reduce path size and index footprint

Reversed Path Encoding

The stored path field represents the key optimization. Reference-model attributes and archetype node identifiers build openEHR paths. This solution uses a reversed stored path, allowing containment constraints to be evaluated with prefix-friendly matching instead of leading-wildcard scans. This setup works with standard regex-based matching in the patient-scoped route and with wildcard-style matching in the search route.

Deterministic AQL to MQL Translation

AQL is independent of the storage-model, making deterministic compilation effective. SQL clauses translate to MQL as follows:

• FROM and CONTAINS become structural path predicates.

• WHERE becomes value predicates on the matched node payloads.

• SELECT becomes projection.

• ORDER BY becomes sorting.

The following example illustrates an AQL query.

SELECT
  e/ehr_id/value AS ehrId,
  c/uid/value AS compositionId,
  med_ac/description[at0017]/items[at0140]/items[at0141]/value/defining_code/code_string AS locationCode
FROM
  EHR e
  CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.vaccination_list.v0]
  CONTAINS (
    CLUSTER adminInfo[openEHR-EHR-CLUSTER.admin_salut.v0]
    AND SECTION[openEHR-EHR-SECTION.immunisation_list.v0]
    AND ACTION med_ac[openEHR-EHR-ACTION.medication.v1]
  )
WHERE
  med_ac/time/value >= '2000-04-13T07:54:16.345Z'
  AND med_ac/time/value <= '2026-02-13T07:54:16.345Z'
  AND adminInfo/items[at0007]/items[at0014]/value/defining_code/code_string = 'E08019820'
  AND med_ac/other_participations/performer/identifiers/id = '038321545'
ORDER BY
  med_ac/time/value DESC

What This AQL Asks For

This query combines structural and value-based constraints. The CONTAINS clause defines the required openEHR structures, in this case a vaccination composition that contains an administrative cluster and a medication action. The WHERE clause then adds predicates on the action time, the performer identifier, and an administrative code.

This query type benefits from deterministic compilation. It expresses conditions over hierarchical clinical structures and node-local values.

How the Compiler Maps AQL to MQL

The compiled MQL follows the same logic as the AQL:

• The top-level ehr_id filter makes the query patient-scoped.

• The $all clause requires all structural branches described by the AQL to be present in the same composition.

• Each $elemMatch binds a path predicate and its value predicates to the same stored node.

• The predicate on p is the compiled form of the structural CONTAINS logic.

• The predicates under data are the compiled form of the WHERE conditions.

• In a full pipeline, the compiler then adds the projection and sorting stages that correspond to SELECT and ORDER BY.

The next example shows a simplified patient-scoped MQL pattern generated from the AQL query above. It illustrates the compiler logic, not a byte-for-byte runtime payload.

// Simplified compiler output for a single-EHR query.
// Projection and sorting stages are omitted here for clarity.
db.compositions.aggregate([
   {
      "$match": {
         "ehr_id": "b416bc97-de39-43f5-9d47-712af6688947~r1",
         "cn": {
            "$all": [
               {
                  "$elemMatch": {
                     "p": {
                        "$regex": /^ACTION\.medication\.v1(?:\.[^.]+)*\.SECTION\.immunisation_list\.v0(?:\.[^.]+)*\.COMPOSITION\.vaccination_list\.v0$/
                     },
                     "data.time.value": {
                        "$gte": ISODate("2000-04-13T07:54:16.345Z"),
                        "$lte": ISODate("2026-02-13T07:54:16.345Z")
                     },
                     "data.other_participations.performer.identifiers.id": "038321545"
                  }
               },
               {
                  "$elemMatch": {
                     "p": {
                        "$regex": /^at0014\.at0007\.CLUSTER\.admin_salut\.v0(?:\.[^.]+)*\.COMPOSITION\.vaccination_list\.v0$/
                     },
                     "data.value.defining_code.code_string": "E08019820"
                  }
               }
            ]
         }
      }
   }
]);

How the Same Logic Moves to the Search Route

The logical translation stays the same in the cross-patient route. The difference is physical execution. Instead of matching on the main compositions collection, the compiler targets the slim search projection. Structural constraints on the reversed path become wildcard filters, and value predicates become range and equality filters.

The next example shows a MQL pattern generated from an AQL not bound to one patient. As before, it illustrates the compiler logic, not a byte-for-byte runtime payload.

{
   "$search": {
      "index": "search_nodes_index",
      "compound": {
         "filter": [
            {
               "embeddedDocument": {
                  "path": "sn",
                  "operator": {
                     "compound": {
                        "filter": [
                           {
                              "wildcard": {
                                 "path": "sn.p",
                                 "query": "ACTION.medication.v1*SECTION.immunisation_list.v0*COMPOSITION.vaccination_list.v0"
                              }
                           },
                           {
                              "range": {
                                 "path": "sn.data.time.value",
                                 "gte": ISODate("2000-04-13T07:54:16.345Z"),
                                 "lte": ISODate("2025-04-13T07:54:16.345Z")
                              }
                           },
                           {
                              "equals": {
                                 "path": "sn.data.other_participations.performer.identifiers.id",
                                 "value": "038321545"
                              }
                           }
                        ]
                     }
                  }
               }
            }
         ]
      }
   }
}

Repeated Structures and Same-Path Siblings

Some openEHR structures can contain repeated sibling nodes with the same effective path, for example repeated EVENTs. These cases require the compiler to push the predicates deeper so the conditions are satisfied by the same repeated item. In standard aggregation, that means deeper nested $elemMatch. In the search route, the equivalent is embeddedDocument, which binds multiple conditions to the same embedded array element.