FHIR Group Member Search Flow with ClickHouse and MongoDB

System Design · sequence diagram · MIT

Illustrates how a FHIR API handles member searches for groups, leveraging ClickHouse for efficient member lookup and MongoDB for group metadata retrieval.

Source: https://github.com/icanbwell/fhir-server/blob/1bb6a360bf7d199ee31787c65b42a2e5ffc75594/readme/clickhouse.md
Curated by icanbwell
FHIR Group Member Search ClickHouse MongoDB Sequence Diagram

Mermaid source

sequenceDiagram
    participant Client
    participant API as FHIR API
    participant Provider as MongoWithClickHouse<br/>StorageProvider
    participant CH as ClickHouse
    participant Mongo as MongoDB

    Client->>API: GET /4_0_0/Group?member=Patient/123
    API->>Provider: findAsync(query)

    Note over Provider: Detect member search parameter
    Provider->>Provider: Extract member criteria<br/>from MongoDB query

    Provider->>CH: SELECT group_id<br/>FROM Group_4_0_0_MemberCurrentByEntity<br/>WHERE entity_reference = 'Patient/123'<br/>AND event_type = 'added'

    Note over CH: Uses argMax aggregation<br/>for current state
    CH-->>Provider: [groupId1, groupId2, ...]

    Provider->>Mongo: find({_id: {$in: [groupId1, groupId2]}})
    Mongo-->>Provider: [Group metadata...]

    Note over Provider: Groups returned WITHOUT<br/>member arrays (stripped)

    Provider-->>API: Groups[]
    API-->>Client: 200 OK Bundle

What this diagram shows

This diagram details the sequence of operations for a FHIR Group member search. A client queries the FHIR API, which delegates to a storage provider. The provider detects the member search, queries ClickHouse for group IDs based on the member reference, then fetches group metadata from MongoDB, finally returning a bundle of groups (without member arrays) to the client.

When to use it

Use this pattern when designing systems requiring highly efficient searches on large datasets by specific attributes, where the primary data store isn't optimized for such queries. It's ideal for offloading and accelerating specialized lookups using an analytics store like ClickHouse.

How to adapt it for your project

This pattern can be adapted by swapping ClickHouse and MongoDB with alternative data stores (e.g., Elasticsearch, PostgreSQL, Cassandra). The member criteria extraction logic can be modified for different query parameters or data models. The stripping of member arrays can be made conditional based on API requirements.

Key concepts