Consulta de Datos Clínicos con AQL: Rutas, Predicados y Prácticas en Producción

El Archetype Query Language (AQL) es el estándar openEHR para consultar datos clínicos en un CDR. Su sintaxis se describe oficialmente como una síntesis de la sintaxis estructural de SQL y la sintaxis de rutas de openEHR: cláusulas SELECT / FROM / WHERE / ORDER BY familiares, combinadas con expresiones de ruta que navegan la jerarquía de arquetipos y composiciones, y un operador CONTAINS que expresa la contención entre estructuras del modelo de referencia [1]. La propiedad crucial — y la razón por la que AQL existe — es que las consultas se escriben contra modelos clínicos, no esquemas físicos: el identificador de arquetipo entre corchetes limita la consulta a un concepto clínico independientemente de qué plantilla, formulario o aplicación almacenó los datos.

Un ejemplo completo, siguiendo el patrón de la especificación — todas las lecturas hipertensivas de presión arterial en un EHR, las más recientes primero [1]:

SELECT
  o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic,
  o/data[at0001]/events[at0006]/data[at0003]/items[at0005]/value/magnitude AS diastolic,
  c/context/start_time AS date_time
FROM EHR e[ehr_id/value=$ehrUid]
  CONTAINS COMPOSITION c
    CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1]
WHERE
  o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= 140
  OR o/data[at0001]/events[at0006]/data[at0003]/items[at0005]/value/magnitude >= 90
ORDER BY c/context/start_time DESC

Leyendo Rutas AQL: De Dónde Vienen los at-codes

Las rutas AQL se derivan directamente de la estructura del arquetipo, y la especificación distingue dos tipos: rutas de arquetipo, que se refieren a nodos dentro de un arquetipo, y rutas de atributo del modelo de referencia, que apuntan a atributos del RM como c/context/start_time o e/ehr_id/value [1]. Los segmentos entre corchetes — at0001, at0004 — son at-codes: identificadores de nodo locales definidos en la sección de terminología del arquetipo, cada uno vinculado a un nombre legible por humanos. En el arquetipo de presión arterial, items[at0004] es el nodo sistólico y items[at0005] el diastólico; la ruta /data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude se lee como "la magnitud del elemento sistólico, dentro de cualquier evento, dentro de los datos de la observación."

Nadie debería construirlas de memoria. El flujo de trabajo confiable es inspeccionar la definición ADL del arquetipo o — mejor — navegar el árbol de nodos en una herramienta de modelado visual y copiar la ruta generada; las rutas a nivel del RM puro son difíciles de manejar sin ayuda, y los at-codes son hechos del arquetipo, no cadenas adivinables. Para un recorrido completo de rutas, predicados y construcción de consultas, consulta el AQL Guide de CaboLabs [5]. Dos detalles prácticos que ahorran tiempo de depuración: los predicados basados en nombre pueden desambiguar hermanos repetidos (p. ej., items[at0011, 'Fracciones']) [2], y los arquetipos especializados introducen at-codes con punto (at0013.1) cuyo significado solo tiene sentido contra la jerarquía de especialización — otra razón por la que el arquetipo, no la consulta, es la fuente de verdad.

Consultar Arquetipos, No Plantillas

Cuando el mismo concepto clínico puede registrarse a través de múltiples plantillas — y en cualquier CDR maduro, así será — preferir consultar por identificadores de arquetipo en lugar de estructuras específicas de plantilla. El predicado de arquetipo (OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1]) coincide con cada composición que contiene esa observación independientemente de la plantilla usada para confirmarla, por lo que la consulta sigue devolviendo resultados correctos a medida que se despliegan nuevas plantillas y las antiguas evolucionan. Este es el dividendo en el lado de consultas del modelado en dos niveles: tu analítica está acoplada al modelo clínico gobernado, no a la capa de formularios que cambia más rápido. Las consultas limitadas a plantillas tienen su lugar — cuando genuinamente quieres "datos capturados a través de este documento" — pero deben ser la excepción deliberada, no el reflejo.

Ejecutar AQL en Producción: La API REST

La API REST de openEHR estandariza la ejecución de consultas en plataformas conformantes [3]. Las consultas ad-hoc van al endpoint de consulta — con POST recomendado sobre GET, ya que las cadenas AQL largas y las listas de parámetros superan rápidamente los límites de longitud de URI:

POST [base]/query/aql HTTP/1.1
Content-Type: application/json

{
  "q": "SELECT ... FROM EHR e[ehr_id/value=$ehrUid] CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE o/.../value/magnitude >= $systolicThreshold",
  "query_parameters": {
    "ehrUid": "554f896d-faca-4513-bddf-66454114630d",
    "systolicThreshold": 140
  }
}

Tres capacidades de la API merecen uso deliberado en lugar de descubrimiento incidental:

• Vinculación de parámetros: AQL soporta parametrización por diseño ($ehrUid, $systolicThreshold), con valores suministrados en la ejecución a través de query_parameters. Úsala siempre — concatenar valores en cadena en AQL es el mismo antipatrón que concatenar SQL, con las mismas consecuencias de inyección y caché.
• Consultas almacenadas (nombradas): los endpoints de definiciones de la API REST gestionan consultas registradas que los clientes ejecutan por nombre calificado y versión [4]. En nuestra experiencia, este es el remedio más efectivo para las cadenas AQL dispersas y duplicadas en el código de aplicación: las consultas se convierten en artefactos del servidor versionados y gobernados, y las aplicaciones mantienen referencias, no copias.
• Control de resultados: limita las consultas a un único EHR donde el caso de uso lo permita (mediante parámetro o cabecera ehr_id) en lugar de ejecutar consultas de población por defecto, ordena los resultados explícitamente y pagina los conjuntos de resultados grandes en lugar de obtener listas sin límite.

El rendimiento depende en última instancia de cómo el CDR subyacente estructura e indexa las composiciones — AQL define la semántica, no la estrategia de ejecución — por lo que la misma consulta puede comportarse de manera muy diferente entre plataformas. CDRs openEHR como EHRbase, Better y nuestro propio Atomik implementan cada uno la ejecución de AQL sobre sus propios diseños de persistencia; en nuestra experiencia, probar tus consultas más pesadas contra volúmenes de datos realistas en tu plataforma real pertenece a la evaluación y preproducción, no después del primer dashboard lento.

El Rol de CaboLabs

AQL es donde una inversión en openEHR empieza a pagar dividendos analíticos — si las consultas son correctas, mantenibles y rápidas. CaboLabs tiene experiencia profunda en AQL a nivel de implementación: hemos construido motores de consulta AQL, diseñado estrategias de indexación de rutas de arquetipo para persistencia relacional, y ayudado a equipos a convertir la proliferación de consultas ad-hoc en catálogos de consultas almacenadas y gobernadas. Nuestro repositorio de datos clínicos nativo en openEHR, Atomik, pone esa experiencia en producción: consulta basada en arquetipos sobre un CDR estándar, con tus modelos clínicos — no tu esquema de base de datos — como superficie de consulta.

Si tu equipo está aprendiendo AQL, tus consultas están superando el rendimiento de tu CDR, o estás evaluando plataformas openEHR y quieres entender qué hay realmente detrás de cada endpoint AQL, habla con nosotros en cabolabs.com — hablamos AQL a nivel del motor.