Présentation de $materialize : interface SQL pour les données FHIR

Les structures de données FHIR sont complexes et imbriquées, ce qui les rend difficiles à exploiter avec les outils SQL standard et les plateformes d'analytique.

Pour y remédier, Aidbox introduit une nouvelle opération SQL on FHIR : $materialize. Elle crée une représentation SQL d'une ressource ViewDefinition, transformant les structures FHIR complexes en formats tabulaires familiers qui fonctionnent parfaitement avec des outils comme DBeaver, Metabase et d'autres plateformes d'analytique fondées sur SQL.

En septembre 2025, cette fonctionnalité ne fait pas encore partie de la spécification SQL on FHIR, mais nous espérons la voir standardisée dans le futur.

Ce que fait $materialize

Dans son essence, $materialize fait le pont entre deux univers : la flexibilité de FHIR et la familiarité de SQL. Elle :

• Crée une table ou une vue SQL à partir d'une ressource ViewDefinition.
• Transforme les données FHIR imbriquées en structures plates et interrogeables que les outils SQL peuvent comprendre.
• Fournit une interface familière aux analystes et aux développeurs qui travaillent avec des données FHIR.

Pourquoi c'est important

Les ressources FHIR possèdent des structures JSON complexes et imbriquées, difficiles à interroger directement en SQL.

Traditionnellement, cela exigeait :

• La rédaction de requêtes JSON path complexes
• Une connaissance approfondie des structures de ressources FHIR
• Du code personnalisé pour aplatir et transformer les données

$materialize résout ce problème en vous permettant de définir la transformation des données une seule fois sous forme de ViewDefinition, puis en créant une interface SQL simple que tout analyste peut utiliser avec ses outils habituels.

Avantages en un coup d'œil :

• Requêtes SQL simples plutôt qu'opérations JSON complexes
• Compatible avec tout outil SQL (DBeaver, Metabase, Tableau, etc.)
• Définitions réutilisables — définir une fois, interroger partout
• Approche FHIR standard utilisant les ressources ViewDefinition
• Gains de performance — éviter les requêtes JSON complexes à chaque demande

Types de matérialisation

$materialize prend en charge trois types de matérialisation, vous offrant de la flexibilité selon votre cas d'utilisation :

• view (par défaut) — crée une vue de base de données qui transforme les données à la volée

  • Toujours à jour avec les dernières données FHIR

  • Aucun espace de stockage supplémentaire requis

  • Idéale pour la plupart des cas d'utilisation nécessitant une interface SQL

• table — crée une table persistante avec un instantané des données

  • Lectures les plus rapides pour les grands ensembles de données et les requêtes complexes

  • Nécessite une actualisation manuelle pour mettre les données à jour

  • Utilise de l'espace de stockage mais élimine le traitement au moment de la requête

• materialized-view — crée une vue matérialisée pouvant être actualisée

  • Approche équilibrée entre performance et fraîcheur des données

  • Peut être actualisée à la demande ou selon un calendrier

  • Prend en charge les index pour des performances de requête optimisées

Fonctionnement

• Créer une ressource ViewDefinition qui fait correspondre les données FHIR à des colonnes simples.
• Envoyer une requête POST à /fhir/ViewDefinition/$materialize.
• Le serveur crée une vue ou une table SQL avec les données aplaties.
• La représentation résultante est disponible dans la base de données.
• Vous pouvez également l'interroger avec n'importe quel outil SQL ou le point de terminaison /$sql d'Aidbox.

Exemple de requête

Voici à quoi cela ressemble en pratique.

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 réponse contient des informations sur la vue créée :

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

Vous pouvez maintenant interroger les données aplaties avec du SQL simple :

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

Exemple : identifiants et données démographiques des patients

Utilisations pratiques

Puisque $materialize produit du SQL standard, elle ouvre un large éventail de possibilités :

• Analytique et rapports — connecter les données FHIR à des outils de BI comme Metabase ou Tableau
• Exploration des données — explorer les données FHIR avec des outils SQL comme DBeaver
• Pipelines ETL — extraire des données aplaties pour les systèmes en aval
• Applications personnalisées — créer des applications nécessitant des vues tabulaires des données FHIR
• Recherche et analyse — permettre aux chercheurs d'interroger les données FHIR avec du SQL standard

Considérations de performance

Bien que le principal avantage de $materialize soit de simplifier l'accès aux données, la performance compte pour certains cas d'utilisation :

• Requêtes à haute fréquence : Si vous exécutez les mêmes requêtes complexes de façon répétée (tableaux de bord, rapports), les types materialized-view ou table peuvent réduire considérablement les temps de réponse.
• Grands ensembles de données : Lorsque vous travaillez avec des millions de ressources FHIR, le stockage matérialisé évite de retraiter les structures JSON à chaque requête.
• Transformations complexes : Les [ViewDefinitions](/blog/what-is-a-viewdefinition) comportant plusieurs jointures et agrégations bénéficient du précalcul.
• Charges de travail analytiques : Les outils de BI effectuant des balayages sur de grands ensembles de données constatent des améliorations spectaculaires avec le stockage matérialisé.

Pour la plupart des travaux exploratoires et les volumes de requêtes modérés, le type view par défaut offre le meilleur équilibre entre simplicité et performance.

Notes de clôture

Le type view par défaut convient parfaitement à la plupart des scénarios où vous avez besoin d'une interface SQL vers des données FHIR — toujours à jour, sans maintenance supplémentaire.

Envisagez les types table ou materialized-view pour les requêtes à haute fréquence ou les grands ensembles de données qui bénéficieraient de résultats précalculés.

$materialize transforme les structures FHIR complexes en interfaces SQL simples, rendant les données FHIR accessibles à toute personne qui connaît SQL et permettant l'utilisation d'outils d'analytique standard dans l'écosystème des données de santé.

Pour plus d'information sur le fonctionnement de $materialize et ses paramètres, consultez la documentation d'Aidbox.