Presentamos $materialize: interfaz SQL para datos FHIR

Las estructuras de datos FHIR son complejas y anidadas, lo que dificulta su uso con herramientas SQL estándar y plataformas de análisis.

Para abordar esto, Aidbox presenta una nueva operación de SQL on FHIR: $materialize. Crea una representación SQL de un recurso ViewDefinition, transformando estructuras FHIR complejas en formatos tabulares familiares que funcionan perfectamente con herramientas como DBeaver, Metabase y otras plataformas de análisis basadas en SQL.

A partir de septiembre de 2025, esto aún no forma parte de la especificación SQL on FHIR, pero esperamos que se estandarice en el futuro.

Qué hace $materialize

En esencia, $materialize tiende un puente entre dos mundos: la flexibilidad de FHIR y la familiaridad de SQL. Permite:

• Crear una tabla o vista SQL a partir de un recurso ViewDefinition.
• Transformar datos FHIR anidados en estructuras planas y consultables que las herramientas SQL pueden comprender.
• Proporcionar una interfaz familiar para analistas y desarrolladores que trabajan con datos FHIR.

Por qué esto es importante

Los recursos FHIR tienen estructuras JSON complejas y anidadas que resultan difíciles de consultar directamente con SQL.

Tradicionalmente, esto requería:

• Escribir consultas complejas con rutas JSON
• Conocer en detalle las estructuras de los recursos FHIR
• Código personalizado para aplanar y transformar los datos

$materialize resuelve esto permitiéndole definir la transformación de datos una sola vez como ViewDefinition, y creando a continuación una interfaz SQL sencilla que cualquier analista puede utilizar con herramientas familiares.

Ventajas de un vistazo:

• Consultas SQL simples en lugar de operaciones JSON complejas
• Compatible con cualquier herramienta SQL (DBeaver, Metabase, Tableau, etc.)
• Definiciones reutilizables — defínase una vez, consúltese en cualquier lugar
• Enfoque FHIR estándar mediante recursos ViewDefinition
• Ventajas de rendimiento — se evitan consultas JSON complejas en cada solicitud

Tipos de materialización

$materialize admite tres tipos de materialización, lo que le ofrece flexibilidad según su caso de uso:

• view (predeterminado) — crea una vista de base de datos que transforma los datos al vuelo

  • Siempre actualizada con los últimos datos FHIR

  • No requiere almacenamiento adicional

  • Ideal para la mayoría de los casos de uso que necesitan una interfaz SQL

• table — crea una tabla persistente con una instantánea de los datos

  • Lecturas más rápidas para conjuntos de datos grandes y consultas complejas

  • Requiere actualización manual para renovar los datos

  • Usa almacenamiento, pero elimina el procesamiento en tiempo de consulta

• materialized-view — crea una vista materializada que puede actualizarse

  • Enfoque equilibrado entre rendimiento y vigencia de los datos

  • Puede actualizarse bajo demanda o de forma programada

  • Admite índices para optimizar el rendimiento de las consultas

Cómo funciona

• Cree un recurso ViewDefinition que asigne datos FHIR a columnas simples.
• Envíe un POST a /fhir/ViewDefinition/$materialize.
• El servidor crea una vista o tabla SQL con los datos aplanados.
• La representación resultante queda disponible en la base de datos.
• Alternativamente, puede consultarla con cualquier herramienta SQL o con el endpoint /$sql de Aidbox.

Ejemplo de solicitud

A continuación se muestra cómo se ve en la práctica.

POST /fhir/ViewDefinition/$materialize
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "type",
    "valueCode": "view"
  }, {
    "name": "viewResource",
    "resource": {
      "name": "patient_view",
      "status": "draft",
      "resource": "Patient",
      "description": "Patient flat view",
      "id": "a099e84c-b3c2-4b6e-8115-a580d25f6495",
      "resourceType": "ViewDefinition",
      "select": [{
        "column": [{
          "name": "id",
          "path": "id",
          "type": "id"
        }, {
          "name": "birth_date",
          "path": "birthDate",
          "type": "date"
        }, {
          "name": "family_name",
          "path": "name.family",
          "type": "string"
        }]
      }]
    }
  }]
}

La respuesta contiene información sobre la vista creada:

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "viewName",
    "valueString": "sof.patient_view"
  }, {
    "name": "viewType",
    "valueString": "view"
  }, {
    "name": "viewSchema",
    "valueString": "sof"
  }]
}

Ahora puede consultar los datos aplanados con SQL sencillo:

SELECT * FROM sof.patient_view WHERE birth_date > '1990-01-01';

Ejemplo: identificadores y datos demográficos de pacientes

Usos prácticos

Dado que $materialize genera SQL estándar, abre un amplio abanico de posibilidades:

• Análisis e informes — conecte datos FHIR a herramientas de BI como Metabase o Tableau
• Exploración de datos — explore datos FHIR con herramientas SQL como DBeaver
• Pipelines ETL — extraiga datos aplanados para sistemas posteriores
• Aplicaciones personalizadas — desarrolle aplicaciones que necesiten vistas tabulares de datos FHIR
• Investigación y análisis — permita a los investigadores consultar datos FHIR con SQL estándar

Consideraciones de rendimiento

Aunque el principal beneficio de $materialize es simplificar el acceso a los datos, el rendimiento es relevante para determinados casos de uso:

• Consultas de alta frecuencia: Si ejecuta las mismas consultas complejas de forma repetida (paneles de control, informes), los tipos materialized-view o table pueden reducir significativamente los tiempos de respuesta.
• Conjuntos de datos grandes: Al trabajar con millones de recursos FHIR, el almacenamiento materializado evita reprocesar las estructuras JSON en cada consulta.
• Transformaciones complejas: Los ViewDefinitions con múltiples combinaciones y agregaciones se benefician del cálculo previo.
• Cargas de trabajo analíticas: Las herramientas de BI que realizan análisis sobre grandes conjuntos de datos experimentan mejoras notables con el almacenamiento materializado.

Para la mayoría de los trabajos exploratorios y volúmenes de consultas moderados, el tipo view predeterminado ofrece el mejor equilibrio entre simplicidad y rendimiento.

Notas finales

El tipo view predeterminado es perfecto para la mayoría de los escenarios en los que se necesita una interfaz SQL para datos FHIR: siempre actualizada y sin mantenimiento adicional.

Considere los tipos table o materialized-view cuando gestione consultas de alta frecuencia o conjuntos de datos grandes que se beneficiarían de resultados precalculados.

$materialize transforma estructuras FHIR complejas en interfaces SQL sencillas, haciendo que los datos FHIR sean accesibles para cualquier persona que conozca SQL y permitiendo el uso de herramientas de análisis estándar en todo el ecosistema de datos sanitarios.

Para obtener más información sobre cómo funciona $materialize y sus parámetros, consulte la documentación de Aidbox.