Camada de persistência openEHR baseada em documento

Reconciliar Famílias de Consultas Clínicas

Essa solução resolve esse problema com um modelo de persistência semiachatado e baseado no documento no MongoDB. Semiachatado significa que achatamos cada elemento como um nó em um array, mas cada um preserva toda a carga útil JSON na estrutura original. Baseada em documento significa que cada composição openEHR é preservada como um único documento MongoDB, em vez de ser decomposta em uma tabela por arquétipo ou uma linha por caminho. Ao mesmo tempo, a composição é materializada como um array de nós reconstrutível, permitindo consultas eficientes baseadas em caminhos sem abandonar a composição como unidade operacional.

Cada nó armazenado retém os seguintes elementos-chave:

• Subárvore clínica local, de modo que o significado e o contexto originais permaneçam disponíveis.

• Metadados posicionais, de modo que a estrutura e a ordem podem ser reconstruídas.

• Caminho AQL invertido, que permite uma correspondência eficiente de restrições de caminho com profundidade variável.

O caminho invertido é uma chave de consulta geral usada para avaliar predicados estruturais de forma eficiente nas rotas de execução com foco no paciente e entre pacientes. Ela permite correspondência limitada por caminho em diferentes estratégias de execução, incluindo correspondência baseada em regex e resolução de caminho no estilo wildcard em índices de pesquisa. Os mesmos padrões de consulta podem ser aplicados quando os predicados utilizam outros componentes do caminho textual ou condições textuais.

Com esse modelo, as cláusulas AQL podem ser compiladas deterministicamente em estágios de consulta do MongoDB. FROM, CONTAINS, e WHERE restrições tornam-se predicados direcionados sobre caminhos e valores de nós. Essa abordagem mantém a composição intacta como o primário contêiner clínico, ao mesmo tempo em que torna a recuperação operacional prática em larga escala.

Figura 1. Representação de composições semiachatadas onde cada nó carrega seu próprio contexto e valores, além do caminho AQL invertido.

Roteamento por Carga de Trabalho

Para muitos repositórios, uma única coleção semiachatada e índices curinga são suficientes. Para implantações maiores, o modelo pode usar uma projeção de pesquisa reduzida que contenha apenas os dados necessários para uma ampla filtragem entre pacientes. A execução da consulta é então roteada por escopo. Uma projeção de pesquisa reduzida é uma coleção derivada menor que armazena apenas os campos de nó necessários para uma filtragem ampla entre pacientes. Ela não substitui o documento principal de composição. Ela reduz a amplitude do índice e o custo de pesquisa para consultas operacionais amplas.

Portanto, fornece as seguintes modalidades:

• As consultas com escopo de paciente são executadas na coleção de composição principal, usando índices direcionados, como um índice composto em campos como ehr_id e reversed_path.

• As consultas entre pacientes são executadas na projeção mais estreita, compilando restrições de caminho em curingas ou correspondências no caminho invertido e predicados de valor em operadores de igualdade, intervalo ou pesquisa.

Esse modelo de execução fornece uma única interface de consulta, permitindo diferentes rotas de acesso físico com base no tamanho da carga de trabalho e na seletividade.

Por Que é Importante Permitir as Consultas de Operações Coorte

As aplicações clínicas modernas precisam, cada vez mais, das duas famílias de consulta na mesma plataforma. Um clínico pode precisar abrir o registro de um paciente imediatamente e fazer perguntas como:

• Quais pacientes receberam um determinado medicamento em um determinado período de tempo?

• Quais pacientes atendem a um protocolo ou regra de segurança?

• Quais casos anteriores são clinicamente semelhantes a este?

Essas perguntas operacionais exigem respostas sem enviar dados por meio de ciclos repetitivos de ETL em sistemas separados.

Um modelo semiachatado baseado em documento preserva os pontos fortes do openEHR e torna essas cargas de trabalho práticas. Ele mantém a composição como a unidade operacional autoritativa, preserva a fidelidade clínica por meio de uma estrutura reconstituível e evita forçar as equipes de aplicativo a escolherem entre um armazenamento centrado no paciente e uma plataforma separada entre pacientes. Repositórios menores podem permanecer simples, com uma coleção semiachatada. Repositórios maiores podem adicionar uma projeção menor para reduzir o custo da filtragem operacional ampla.

Na nossa avaliação, essa abordagem manteve baixa latência de ponta a ponta em ambos os tipos de carga de trabalho, com tempos de resposta baixos para consultas de escopo de paciente e consultas entre pacientes, mesmo em grande escala. Essa eficiência valida-o como uma base prática para repositórios openEHR que devem permitir recuperação operacional, processamento com consciência de proveniência, enriquecimento semântico e fluxos de trabalho orientados por IA em uma única plataforma.

Você pode explorar esse padrão com o kernel, um runtime de referência experimental e um kit de ferramentas para estratégias de dados clínicos baseado em documentos.

Seguindo essa abordagem, você obtém os seguintes benefícios práticos:

• Um modelo semiachatado reconstrutível que preserva a fidelidade da composição.

• Consulta eficiente com escopo do paciente sem forçar uma fragmentação relacional do documento clínico.

• Permissão para recuperação operacional entre pacientes sem definir como padrão uma arquitetura baseada em armazenamento.

• Uma superfície de consulta operacional para equipe de aplicativo, em vez de armazenar duplicados e lógica fragmentada.

• Um caminho para reduzir a sobrecarga de ETL, o desvio de governança e o custo total de propriedade.

O que é kernel e por que usá-lo?

Kernel é um runtime estratégico que transforma modelos de dados de saúde em capacidades operacionais. O kernel existe porque definir um modelo de dados de saúde não é suficiente. As equipes também precisam de uma maneira repetível de validar dados, transformá-los em uma representação operacional, ingeri-los, consultá-los, mantê-los e evoluí-los conforme os requisitos mudam. Sem essa camada de execução, os modelos frequentemente permanecem como documentação, esquemas de armazenamento ou especificações isoladas.

O objetivo é mais amplo do que construir um mecanismo openEHR. A Kehrnel fornece uma abordagem repetível de documentos para tornar os modelos de dados de saúde executáveis, inspecionáveis e reutilizáveis em APIs, ferramentas e fluxos de trabalho de IA. Com o tempo, o mesmo padrão de execução pode dar suporte a outras famílias de modelos e estratégias operacionais, incluindo FHIR, fluxos de trabalho de dados sintéticos, catálogos semânticos, recuperação de linguagem natural e outras ferramentas específicas de domínio.

O kernel foi projetado com base em fluxos de trabalho expostos que podem ser personalizados para as necessidades de cada estratégia de persistência. Cada estratégia pode definir suas próprias operações de ativação, validação, ingestão, transformação, consulta, dados sintéticos e manutenção, sem deixar de usar um modelo de tempo de execução consistente.

O kernel começa com o openEHR porque o openEHR é um modelo exigente e rico em semântica. Inclui arquétipos, modelos, caminhos, terminologia e comportamento complexo de consultas. Isso faz dele uma base sólida para provar uma abordagem de runtime orientada por modelo.

Para esta solução, o Kernel serve como tempo de execução de referência e kit de ferramentas para o padrão de persistência baseado em documentos.

Figura 2. Captura de tela do Kernel CLI

Como Ler Este Documento

Um documento do MongoDB representa uma composição do openEHR. O array cn armazena os nós consultáveis extraídos dessa composição. Cada nó mantém uma subárvore clínica local em data, uma chave de caminho invertida em p, e metadados posicionais como kp, pi, e bk para que a estrutura original possa ser reconstruída.

O exemplo público mostra a chave do caminho de forma legível para facilitar a tradução. Em produção, você pode armazenar o mesmo caminho como tokens compactados codificados por dicionário para reduzir o tamanho do caminho e a pegada do índice.

Codificação de caminho invertido

O campo de caminho armazenado representa a otimização da chave. Atributos do modelo de referência e identificadores de nós de arquétipo constroem caminhos openEHR. Essa solução utiliza um caminho armazenado invertido, permitindo que as restrições de contenção sejam avaliadas com correspondência amigável ao prefixo em vez de varreduras de wildcard iniciais. Essa configuração funciona com a correspondência baseada em regex padrão na rota com escopo de paciente e com a correspondência estilo curinga na rota de pesquisa.

Tradução Determinística de AQL para MQL

O AQL é independente do modelo de armazenamento, tornando a compilação determinística eficaz. As cláusulas SQL são traduzidas para MQL da seguinte forma:

• FROM e CONTAINS se tornam predicados do caminho estruturais.

• WHERE se tornam predicados de valor nas cargas úteis do nó correspondente.

• SELECT torna-se projeção.

• ORDER BY se torna classificação.

O exemplo seguinte ilustra uma consulta AQL.

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

O que esta AQL pede

Esta consulta combina restrições estruturais e baseadas em valor. A cláusula CONTAINS define as estruturas openEHR necessárias, neste caso, uma composição de vacinação que contém um cluster administrativo e uma ação de medicamento. A cláusula WHERE em seguida adiciona predicados no tempo de ação, no identificador do executor e em um código administrativo.

Este tipo de consulta se beneficia da compilação determinística. Expressa condições sobre estruturas clínicas hierárquicas e valores locais de nós.

Como o compilador mapeia AQL para MQL

O MQL compilado segue a mesma lógica que a AQL:

• O filtro ehr_id de nível superior torna a consulta voltada para o paciente.

• A cláusula $all exige que todos os ramos estruturais descritos pela AQL estejam presentes na mesma composição.

• Cada $elemMatch vincula um predicado de caminho e seus predicados de valor ao mesmo nó armazenado.

• O predicado em p é a forma compilada da lógica estrutural CONTAINS.

• Os predicados em dados são a forma compilada das condições WHERE.

• Em um pipeline completo, o compilador adiciona os estágios de projeção e classificação que correspondem a SELECT e ORDER BY.

O próximo exemplo mostra um padrão MQL simplificado com escopo de paciente, gerado a partir da consulta AQL acima. Ele ilustra a lógica do compilador, não uma carga útil de tempo de execução byte a byte.

// 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"
                  }
               }
            ]
         }
      }
   }
]);

Como a Mesma Lógica se Move para a Rota de Pesquisa

A tradução lógica permanece a mesma na rota entre pacientes. A diferença é a execução física. Em vez de fazer a correspondência na coleção de gravações principais, o compilador tem como alvo a projeção esbelta da pesquisa. As restrições estruturais no caminho invertido se tornam filtros wildcard e os predicados de valor se tornam filtros de faixa e igualdade.

O próximo exemplo mostra um padrão MQL gerado a partir de um AQL que não está vinculado a um único paciente. Como antes, ele ilustra a lógica do compilador, e não uma carga útil de tempo de execução byte a byte.

{
   "$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"
                              }
                           }
                        ]
                     }
                  }
               }
            }
         ]
      }
   }
}

Estruturas repetidas e elementos com o mesmo caminho

Algumas estruturas openEHR podem conter nós irmãos repetidos com o mesmo caminho efetivo, por exemplo: EVENTs repetidos. Esses casos exigem que o compilador aprofunde os predicados para que as condições sejam satisfeitas pelo mesmo item repetido. Na agregação padrão, isso significa $elemMatch mais profundamente aninhado. Na rota de pesquisa, o equivalente é embeddedDocument, que vincula várias condições ao mesmo elemento de array embutido.