--- { "title": "Presentamos $materialize: interfaz SQL para datos FHIR", "description": "La nueva operación $materialize en Aidbox crea tablas o vistas SQL a partir de recursos ViewDefinition de FHIR, facilitando la consulta de datos FHIR anidados. Ayuda a transformar estructuras JSON complejas en formatos tabulares familiares para su uso con herramientas SQL estándar.", "date": "2025-09-17", "author": "Andrew Listopadov", "reading-time": "7 minutes", "tags": [ "SQL on FHIR", "Aidbox" ] } --- > For the complete documentation index, see [llms.txt](https://www.health-samurai.io/llms.txt). > Use it to discover all available pages before guessing URLs. --- 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](/blog/aidbox-becomes-the-first-fhir-server-to-pass-all-sql-on-fhir-tests): `$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](https://build.fhir.org/ig/FHIR/sql-on-fhir-v2/), 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. ```javascript 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: ```javascript { "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: ```javascript SELECT * FROM sof.patient_view WHERE birth_date > '1990-01-01'; ``` Ejemplo: identificadores y datos demográficos de pacientes | id | birth_date | family_name | | --- | --- | --- | | d3c79580-592d-491b-acdf-db335896a886 | 1991-02-21 | Smith | | 4a37e330-1bf9-48f6-9891-52a39e3a0579 | 1990-08-02 | Johnson | | 4ae699f4-8efa-4879-84ef-e5301397f3ae | 1998-11-11 | Williams | ## 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`](/blog/what-is-a-viewdefinition) 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](https://www.health-samurai.io/docs/aidbox/modules/sql-on-fhir/operation-materialize).