Replies: 6 comments 21 replies
-
|
Thanks for sharing a very well thought of architecture for a polyglot persistence layer for FHIR, Steve. |
Beta Was this translation helpful? Give feedback.
-
|
@sandhums I am not sure if oauth scopes and roles necessary have to live in the storage layer (broadening its scope). |
Beta Was this translation helpful? Give feedback.
-
|
@lschmierer you are right to question that. Strictly speaking, we only need org_id and hospital_id for multi-tenancy isolation. I was thinking for the future to enforce even greater security, because we are dealing with healthcare. With org_id and hospital_id, we use RLS for tenant isolation, only. Then with scopes and roles, we can enforce database layer authorization. Of course we would be doing that at the handler level with middleware, etc. I always think like - if we are decoding the access token, we are getting this info, might as well use it. Even if we don't enforce RLS for authorization, it could still be used for audit logging and traceability in the query logs. On a lighter note - Roles and scopes live in the middleware, which the handlers enforce. We just give them a free pass if they want to visit the storage layer. |
Beta Was this translation helpful? Give feedback.
-
|
I agree here that what both of you are talking about - oauth tokens and scopes and the like belong at a higher level of the architecture. @sandhums, you are correct that to support row level security, there would need to be additional complexity. The Health Samurai team has done some good work in this space - see their presentation here. Some databases support this really well, and some ignore it completely. I hesitate to add that kind of capability now, however. There is a lot of complexity in doing this sort of thing correctly. The classic case is when a patient has a diagnosis of a mental disorder with which we don't want to reveal to a particular role, yet a list of medications makes that diagnosis obvious. |
Beta Was this translation helpful? Give feedback.
-
|
@smunini Thank you for pointing me in the right direction. The presentation was a great eye-opener. So as I understand, when we are minting the access token which includes scopes/roles, it should also include the security label of the user. Middleware checks, roles/scopes/security label and decides the permission and database enforces row level security based on the security label. Then we have to modify the resource, if the security label is not matching, with an extension of data absent reason. Whew! |
Beta Was this translation helpful? Give feedback.
-
|
That is correct - to the extend that one would want to use database row level security. It is possible to do all that work in a higher level of abstraction. Also, the design that is discussed relies on the client - the creator of the FHIR Resource - to add the correct security labels, so for the example I gave, the correct security label would need to be present on both the Condition resource and the MedicationStratement resource. Other designs could be imagined that would offer a filtering layer that would add those labels programatically, however that would be a more complex design with other risks involved. Complexity like this can only be moved around. |
Beta Was this translation helpful? Give feedback.
-
|
Thank you so much for putting together the document, it was a very interesting read! I have a few design questions and some minor editorial notes. Design Question & Suggestions:
Minor notes:
|
Beta Was this translation helpful? Give feedback.
-
|
Thank you Lukas for these comments and insights - much appreciated!
You are absolutely correct. Good catch. FHIR allows several forms of cross-resource-type searches:
So the SearchBackend trait needs revision. Instead of: pub trait SearchBackend: Send + Sync {
type QueryBuilder;
type QueryResult;
fn query_builder(&self, resource_type: &str) -> Self::QueryBuilder;
// ...
}It should probably be: pub trait SearchBackend: Send + Sync {
type QueryBuilder;
type QueryResult;
/// Creates a query builder for one or more resource types.
/// If `resource_types` is None, searches all resource types.
/// If `resource_types` is Some with multiple types, parameters must be common across all.
fn query_builder(&self, resource_types: Option<&[&str]>) -> Self::QueryBuilder;
async fn execute(&self, query: Self::QueryBuilder) -> Result<Self::QueryResult, SearchError>;
}Similarly, #[async_trait]
pub trait SearchProvider: ResourceStorage {
/// Searches a single resource type.
async fn search(
&self,
tenant: &TenantContext,
resource_type: &str,
query: &SearchQuery,
) -> Result<SearchBundle, StorageError>;
/// Searches multiple resource types (or all if None).
/// Parameters must be common across all searched types.
async fn search_multi(
&self,
tenant: &TenantContext,
resource_types: Option<&[&str]>,
query: &SearchQuery,
) -> Result<SearchBundle, StorageError>;
}
Good point! Looking back at the document, For flexibility, we could define it as an opaque wrapper over a string that supports both simple IDs and hierarchical namespaces: /// A tenant identifier. Opaque to the storage layer—interpretation
/// of structure (flat vs. hierarchical) is left to the application.
///
/// # Examples
///
/// Simple flat identifiers:
/// ```
/// let tenant = TenantId::new("acme-health");
/// ```
///
/// Hierarchical namespaces:
/// ```
/// let tenant = TenantId::new("organization_id/hospital_id");
/// let tenant = TenantId::new("region:us-east/org:12345/facility:main");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TenantId(String);
impl TenantId {
pub fn new(id: impl Into<String>) -> Self {
Self(id.into())
}
/// The system tenant, used for shared resources (terminology, conformance).
pub const fn system() -> Self {
Self(String::new()) // Or a sentinel like "__system__"
}
pub fn as_str(&self) -> &str {
&self.0
}
/// Returns true if this is the system tenant.
pub fn is_system(&self) -> bool {
self.0.is_empty() // Or check for sentinel
}
}
impl From<&str> for TenantId {
fn from(s: &str) -> Self {
Self::new(s)
}
}
impl From<String> for TenantId {
fn from(s: String) -> Self {
Self(s)
}
}This approach:
The one thing to note is that index design might care about hierarchy. If you're using
I was thinking exactly the same thing.
You're right - Offset-based pagination ( Cursor-based pagination avoids both problems. Instead of "skip N rows," the server returns an opaque continuation token encoding the current position. The client passes this token to fetch the next page, and the database seeks directly to that position—O(1) regardless of depth. /// Pagination strategy for search results.
#[derive(Debug, Clone)]
pub enum Pagination {
/// Offset-based (supported for compatibility, discouraged for large result sets).
Offset { count: u32, offset: u32 },
/// Cursor-based (preferred). The cursor is opaque to clients.
Cursor { count: u32, cursor: Option<PageCursor> },
}
/// An opaque pagination cursor. Internal structure is backend-specific.
///
/// For Cassandra, this wraps the paging state.
/// For PostgreSQL, this might encode a keyset (e.g., last seen `_lastUpdated` + `_id`).
/// For Elasticsearch, this wraps a search_after value or scroll ID.
#[derive(Debug, Clone)]
pub struct PageCursor(Vec<u8>);
impl PageCursor {
pub fn new(data: impl Into<Vec<u8>>) -> Self {
Self(data.into())
}
pub fn as_bytes(&self) -> &[u8] {
&self.0
}
/// Encodes the cursor for inclusion in a URL (base64).
pub fn encode(&self) -> String {
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
URL_SAFE_NO_PAD.encode(&self.0)
}
/// Decodes a cursor from a URL parameter.
pub fn decode(s: &str) -> Result<Self, PaginationError> {
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
let bytes = URL_SAFE_NO_PAD.decode(s)
.map_err(|_| PaginationError::InvalidCursor)?;
Ok(Self(bytes))
}
}
/// Search results with pagination support.
pub struct SearchBundle {
pub matches: Vec<StoredResource>,
pub included: Vec<StoredResource>,
pub total: Option<u64>,
/// Cursor for the next page, if more results exist.
pub next_cursor: Option<PageCursor>,
}The
Keyset Pagination for SQL BackendsFor PostgreSQL and other relational databases, keyset pagination (also called "seek method") provides efficient cursor-based paging: -- First page
SELECT * FROM observation
WHERE tenant_id = $1
ORDER BY last_updated DESC, id ASC
LIMIT 100;
-- Subsequent pages (cursor contains last_updated and id of final row)
SELECT * FROM observation
WHERE tenant_id = $1
AND (last_updated, id) < ($last_updated, $last_id)
ORDER BY last_updated DESC, id ASC
LIMIT 100;This requires a stable sort order with a unique tiebreaker (typically Impact on SearchProviderThe #[async_trait]
pub trait SearchProvider: ResourceStorage {
async fn search(
&self,
tenant: &TenantContext,
resource_type: &str,
query: &SearchQuery,
) -> Result<SearchBundle, StorageError>;
}
/// Updated SearchQuery with flexible pagination.
#[derive(Debug, Clone, Default)]
pub struct SearchQuery {
pub parameters: Vec<SearchParameter>,
pub sort: Vec<SortSpec>,
pub pagination: Option<Pagination>,
pub summary: Option<SummaryMode>,
pub elements: Option<Vec<String>>,
pub include: Vec<IncludeSpec>,
pub revinclude: Vec<IncludeSpec>,
}Backends that only support offset pagination can reject cursor-based requests with FHIR Bundle LinksFHIR represents pagination through Bundle links. The cursor appears in the {
"resourceType": "Bundle",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://example.org/fhir/Observation?patient=123&_count=100"
},
{
"relation": "next",
"url": "https://example.org/fhir/Observation?patient=123&_count=100&_cursor=eyJsYXN0X3VwZGF0ZWQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiIsImlkIjoiYWJjMTIzIn0"
}
]
}The
Agreed. The base Here are some initial design ideas and some implications for the FHIR API. Optimistic locking assumes conflicts are rare. Instead of holding locks, the transaction tracks the versions of resources it has read and verifies they haven't changed at commit time. If any resource was modified by another transaction, the commit fails and the client retries. /// Locking strategy for a transaction.
#[derive(Debug, Clone, Copy, Default)]
pub enum LockingStrategy {
/// Pessimistic: acquire locks on read, hold until commit.
/// Guarantees success at commit time but may cause contention.
#[default]
Pessimistic,
/// Optimistic: track read versions, verify at commit.
/// Better concurrency but may fail at commit time.
Optimistic,
}
#[async_trait]
pub trait TransactionProvider: ResourceStorage {
/// Begins a transaction with the default (pessimistic) locking strategy.
async fn begin_transaction(
&self,
tenant: &TenantContext,
) -> Result<Box<dyn Transaction>, StorageError> {
self.begin_transaction_with_options(tenant, TransactionOptions::default()).await
}
/// Begins a transaction with explicit options.
async fn begin_transaction_with_options(
&self,
tenant: &TenantContext,
options: TransactionOptions,
) -> Result<Box<dyn Transaction>, StorageError>;
}
#[derive(Debug, Clone, Default)]
pub struct TransactionOptions {
pub locking: LockingStrategy,
pub isolation: IsolationLevel,
/// Timeout for acquiring locks (pessimistic) or total transaction duration.
pub timeout: Option<std::time::Duration>,
}Optimistic Transaction BehaviorWith optimistic locking, the transaction tracks which resources were read and their versions: #[async_trait]
pub trait Transaction: Send + Sync {
fn tenant(&self) -> &TenantContext;
/// Returns the locking strategy for this transaction.
fn locking_strategy(&self) -> LockingStrategy;
/// Creates a resource within this transaction.
async fn create(&mut self, resource: &Value) -> Result<StoredResource, StorageError>;
/// Reads a resource within this transaction.
///
/// For optimistic transactions, this records the version for
/// conflict detection at commit time.
async fn read(
&self,
resource_type: &str,
id: &str,
) -> Result<Option<StoredResource>, StorageError>;
/// Reads a resource and explicitly tracks it for optimistic locking,
/// even if you don't need the contents. Useful when you want to
/// ensure a resource hasn't changed without fetching it again.
async fn track_version(
&mut self,
resource_type: &str,
id: &str,
expected_version: &str,
) -> Result<(), StorageError>;
/// Updates a resource within this transaction.
async fn update(&mut self, resource: &Value) -> Result<StoredResource, StorageError>;
/// Deletes a resource within this transaction.
async fn delete(&mut self, resource_type: &str, id: &str) -> Result<(), StorageError>;
/// Commits all operations in this transaction atomically.
///
/// For optimistic transactions, this verifies that all tracked
/// resources still have the versions that were read. Returns
/// `StorageError::OptimisticLockFailure` if any version has changed.
async fn commit(self: Box<Self>) -> Result<(), StorageError>;
/// Rolls back all operations in this transaction.
async fn rollback(self: Box<Self>) -> Result<(), StorageError>;
}Error Handling for Optimistic Lock FailuresWhen an optimistic transaction fails at commit time, the client needs enough information to retry intelligently: #[derive(Debug)]
pub enum StorageError {
// ... other variants ...
/// Optimistic lock failure—a tracked resource was modified.
OptimisticLockFailure {
/// Resources that changed since they were read.
conflicts: Vec<ConflictInfo>,
},
/// Version conflict on a single resource update.
VersionConflict {
resource_type: String,
id: String,
expected_version: String,
actual_version: String,
},
}
#[derive(Debug)]
pub struct ConflictInfo {
pub resource_type: String,
pub id: String,
pub read_version: String,
pub current_version: String,
}When to Use Each Strategy
Backends that don't support optimistic locking can reject requests with Interaction with FHIR Conditional OperationsFHIR defines conditional create, update, and delete operations that use search criteria rather than explicit IDs. These interact with transaction locking in important ways. Conditional Create (
|
| Operation | Pessimistic | Optimistic |
|---|---|---|
| Simple CRUD | Lock acquired on access | Version tracked on read, verified on commit |
| Conditional Create | Lock search space | Assert "no matches" at commit |
| Conditional Update | Lock matched resource | Assert same match + version at commit |
| Conditional Delete | Lock matched resources | Assert same match set at commit |
| If-Match on entry | Lock + verify version | Verify version at commit |
| Commit failure | Rare (deadlock, timeout) | Expected under contention |
| Retry strategy | Usually unnecessary | Built into application logic |
Implementation Considerations
-
Search result stability: For conditional operations with optimistic locking, the implementation must track not just "which resources matched" but enough information to verify the search would return the same results at commit time. This is complex for queries with sorting or pagination.
-
Phantom reads: Even with optimistic locking, a conditional delete might miss a resource that was created after the search but before commit. The isolation level determines whether this is acceptable.
-
Backend capabilities: Not all backends can efficiently implement optimistic conditional operations. The capability system should expose this:
pub trait StorageCapabilities {
// ... existing methods ...
/// Returns supported locking strategies.
fn supported_locking_strategies(&self) -> Vec<LockingStrategy>;
/// Returns whether conditional operations are supported within transactions.
fn supports_conditional_in_transaction(&self) -> bool;
/// Returns whether optimistic locking on conditional operations is supported.
fn supports_optimistic_conditional(&self) -> bool;
}- FHIR transaction bundle semantics: The FHIR spec requires that a transaction bundle either fully succeeds or fully fails with no partial effects. Both locking strategies satisfy this—pessimistic by holding locks, optimistic by aborting on conflict. The choice affects throughput and failure modes, not correctness.
Why are the REST interaction modeled with the Interaction enum instead of individual methods ?
You're right - that's weird. Here is a better approach:
/// Handles FHIR REST interactions by coordinating storage traits.
///
/// This trait maps HTTP semantics to storage operations. Implementations
/// handle concerns like ETag generation, Location headers, and
/// OperationOutcome construction.
#[async_trait]
pub trait RestHandler: Send + Sync {
// === Instance-level interactions ===
/// Reads the current version of a resource.
/// Maps to: GET [base]/[type]/[id]
async fn read(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
) -> Result<ReadOutcome, RestError>;
/// Reads a specific version of a resource.
/// Maps to: GET [base]/[type]/[id]/_history/[vid]
async fn vread(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
version_id: &str,
) -> Result<ReadOutcome, RestError>;
/// Updates a resource, optionally with version matching.
/// Maps to: PUT [base]/[type]/[id]
async fn update(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
resource: &Value,
if_match: Option<&str>,
) -> Result<WriteOutcome, RestError>;
/// Patches a resource using JSON Patch, JSON Merge Patch, or FHIRPath Patch.
/// Maps to: PATCH [base]/[type]/[id]
async fn patch(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
patch: &Patch,
if_match: Option<&str>,
) -> Result<WriteOutcome, RestError>;
/// Deletes a resource.
/// Maps to: DELETE [base]/[type]/[id]
async fn delete(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
) -> Result<DeleteOutcome, RestError>;
/// Returns the history of a specific resource.
/// Maps to: GET [base]/[type]/[id]/_history
async fn history_instance(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
params: &HistoryParams,
) -> Result<HistoryOutcome, RestError>;
// === Type-level interactions ===
/// Creates a new resource with server-assigned ID.
/// Maps to: POST [base]/[type]
async fn create(
&self,
tenant: &TenantContext,
resource_type: &str,
resource: &Value,
if_none_exist: Option<&[SearchParameter]>,
) -> Result<WriteOutcome, RestError>;
/// Searches for resources of a given type.
/// Maps to: GET [base]/[type]?params or POST [base]/[type]/_search
async fn search(
&self,
tenant: &TenantContext,
resource_type: &str,
query: &SearchQuery,
) -> Result<SearchOutcome, RestError>;
/// Returns the history of all resources of a type.
/// Maps to: GET [base]/[type]/_history
async fn history_type(
&self,
tenant: &TenantContext,
resource_type: &str,
params: &HistoryParams,
) -> Result<HistoryOutcome, RestError>;
// === Conditional interactions ===
/// Conditional update: updates based on search criteria.
/// Maps to: PUT [base]/[type]?search-params
async fn update_conditional(
&self,
tenant: &TenantContext,
resource_type: &str,
resource: &Value,
search_params: &[SearchParameter],
if_match: Option<&str>,
) -> Result<WriteOutcome, RestError>;
/// Conditional delete: deletes based on search criteria.
/// Maps to: DELETE [base]/[type]?search-params
async fn delete_conditional(
&self,
tenant: &TenantContext,
resource_type: &str,
search_params: &[SearchParameter],
) -> Result<DeleteOutcome, RestError>;
// === System-level interactions ===
/// Searches across all resource types.
/// Maps to: GET [base]?params
async fn search_system(
&self,
tenant: &TenantContext,
resource_types: Option<&[&str]>,
query: &SearchQuery,
) -> Result<SearchOutcome, RestError>;
/// Returns the history of all resources.
/// Maps to: GET [base]/_history
async fn history_system(
&self,
tenant: &TenantContext,
params: &HistoryParams,
) -> Result<HistoryOutcome, RestError>;
/// Returns the server's capability statement.
/// Maps to: GET [base]/metadata
async fn capabilities(&self) -> Result<Value, RestError>;
// === Bundle interactions ===
/// Processes a batch bundle (independent operations).
/// Maps to: POST [base] with Bundle.type = batch
async fn batch(
&self,
tenant: &TenantContext,
bundle: &Value,
) -> Result<Value, RestError>;
/// Processes a transaction bundle (atomic operations).
/// Maps to: POST [base] with Bundle.type = transaction
async fn transaction(
&self,
tenant: &TenantContext,
bundle: &Value,
) -> Result<Value, RestError>;
}Outcome Types
Each interaction category has its own outcome type with appropriate fields:
/// Outcome of a read operation.
pub struct ReadOutcome {
pub resource: Option<StoredResource>,
pub status: HttpStatus,
pub etag: Option<String>,
pub last_modified: Option<chrono::DateTime<chrono::Utc>>,
}
/// Outcome of a write operation (create, update, patch).
pub struct WriteOutcome {
pub resource: StoredResource,
pub status: HttpStatus, // 200 OK or 201 Created
pub etag: String,
pub last_modified: chrono::DateTime<chrono::Utc>,
pub location: Option<String>, // For creates
pub outcome: Option<OperationOutcome>,
}
/// Outcome of a delete operation.
pub struct DeleteOutcome {
pub status: HttpStatus, // 200, 204, or 202
pub outcome: Option<OperationOutcome>,
}
/// Outcome of a search operation.
pub struct SearchOutcome {
pub bundle: SearchBundle,
pub status: HttpStatus,
pub outcome: Option<OperationOutcome>, // Warnings about ignored params, etc.
}
/// Outcome of a history operation.
pub struct HistoryOutcome {
pub bundle: HistoryBundle,
pub status: HttpStatus,
}Cross-Cutting Concerns
The enum approach was motivated by wanting a single place for cross-cutting concerns. With individual methods, these are handled differently:
Logging and metrics: Use a wrapper/decorator that implements RestHandler and delegates to an inner handler:
pub struct InstrumentedRestHandler<H: RestHandler> {
inner: H,
metrics: Arc<Metrics>,
}
#[async_trait]
impl<H: RestHandler> RestHandler for InstrumentedRestHandler<H> {
async fn read(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
) -> Result<ReadOutcome, RestError> {
let timer = self.metrics.start_timer("read", resource_type);
let result = self.inner.read(tenant, resource_type, id).await;
timer.observe(result.is_ok());
result
}
// ... delegate other methods similarly
}Authorization: Same pattern—an AuthorizedRestHandler that checks permissions before delegating.
Audit logging: Same pattern—an AuditedRestHandler that records interactions.
This composition approach is more flexible than a single dispatch point. You can stack decorators, apply them selectively, or use different combinations for different deployments.
When Enums Still Make Sense
The Interaction enum isn't useless—it's still valuable for:
- Capability statements: Declaring which interactions a backend supports
- Authorization rules: "User X can perform Read but not Delete on Patient"
- Audit records: Recording what interaction type occurred
- Configuration: Enabling/disabling interactions per resource type
/// Interaction types for capability declaration and authorization.
/// Not used for dispatch—individual methods handle that.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Interaction {
Read,
Vread,
Update,
Patch,
Delete,
HistoryInstance,
HistoryType,
HistorySystem,
Create,
Search,
SearchSystem,
Capabilities,
Batch,
Transaction,
}
impl Interaction {
/// Returns the HTTP method for this interaction.
pub fn method(&self) -> HttpMethod {
match self {
Interaction::Read | Interaction::Vread | Interaction::Search
| Interaction::SearchSystem | Interaction::HistoryInstance
| Interaction::HistoryType | Interaction::HistorySystem
| Interaction::Capabilities => HttpMethod::Get,
Interaction::Create | Interaction::Batch
| Interaction::Transaction => HttpMethod::Post,
Interaction::Update => HttpMethod::Put,
Interaction::Patch => HttpMethod::Patch,
Interaction::Delete => HttpMethod::Delete,
}
}
/// Returns the scope at which this interaction operates.
pub fn scope(&self) -> InteractionScope {
match self {
Interaction::Read | Interaction::Vread | Interaction::Update
| Interaction::Patch | Interaction::Delete
| Interaction::HistoryInstance => InteractionScope::Instance,
Interaction::Create | Interaction::Search
| Interaction::HistoryType => InteractionScope::Type,
Interaction::SearchSystem | Interaction::HistorySystem
| Interaction::Capabilities | Interaction::Batch
| Interaction::Transaction => InteractionScope::System,
}
}
}The enum describes interactions; methods implement them.
I really like the polyglot design, but I was wondering if it should somehow be possible to aggregate the results of multiple backends in a final post processing step. This is for the case that multiple backends are required to fulfill the entire query (e.g. combine chained searches with full text search). But I see the complexity that brings (kind of its own query planning and optimization)
I think a (hopefully lightweight) query planner and optimizer is an essential requirement. Consider this search:
GET [base]/Observation?patient.name:contains=smith&_text=cardiac&code:below=http://loinc.org|8867-4
This combines:
- Chained search (
patient.name:contains=smith) — best handled by a graph database or relational joins - Full-text search (
_text=cardiac) — requires Elasticsearch or similar - Terminology subsumption (
code:below=...) — needs terminology service expansion
No single backend handles all three efficiently. A naive approach would pick one backend, let it handle what it can, and post-filter the rest—but that might mean fetching millions of rows only to discard most of them.
This is a query planning problem, and it's not unique to polyglot architectures. Even a single-backend system like Cassandra requires careful thought about access paths as we found out in some of our previous work. Cassandra's data model essentially forces you to pre-plan your queries; you can't just throw arbitrary WHERE clauses at it.
Later on S3/Parquet is shown in the comparison table. It might be worth listing Object Store in the „Data Technologies“ section at the beginning of the document.
Good point. I'll add:
- Object Storage (S3, Azure Blob, GCS) provides virtually unlimited, highly durable storage at low cost. For FHIR, object storage serves multiple roles: as the foundation for data lakes storing raw NDJSON exports, as the backing store for large attachments (imaging, documents, waveforms) referenced by DocumentReference and ImagingStudy resources, and increasingly as a direct query target via formats like Parquet with query engines like Athena, Trino, or DuckDB. The Parquet format is particularly valuable for FHIR analytics—its columnar structure and predicate pushdown enable efficient queries over flattened FHIR data without loading entire resources. Object storage is read-heavy and eventually consistent, making it unsuitable for transactional workloads but ideal for bulk export, archival, and analytical queries.
Beta Was this translation helpful? Give feedback.
-
|
Thank you for the quick response, i have a few follow-up notes/questions: Optimistic LockingI don’t fully understand the concept behind Trait scopingIn general, some traits could be still somewhat smaller (e.g. conditional handling in transactions could be separate trait). This allows backends to more gradually adopt features and move in smaller steps. REST handlersSome cross cutting concerns, like logging, can still be handled universally before calling the REST handler. The going to be used rest framework will very likely have some concept of middleware for such things. —— I have some more thoughts and questions on SQL/Postgres vs. offloading resource JSON to S3 offloading, but will write a separate comment to have a dedicated discussion about that. |
Beta Was this translation helpful? Give feedback.
-
|
Hi Lukas! Great points.
That's some internals leaking out into the trait that are unnecessary - That function should be removed from the trait.
Excellent idea. I'll add some more traits in that area.
I plan to assemble an authentication and authorization discussion document next that should should cover the REST handlers better. What is in this document is some initial sketched out ideas and incomplete. That part of the spec really needs it's own standalone discussion document. I debated even to include that REST section in this document. This is an area of future thought and consideration. |
Beta Was this translation helpful? Give feedback.
-
|
Here are some more ideas on additional traits: /// Core transaction capability: atomic CRUD operations.
#[async_trait]
pub trait Transaction: Send + Sync {
fn tenant(&self) -> &TenantContext;
async fn create(&mut self, resource: &Value) -> Result<StoredResource, StorageError>;
async fn read(&self, resource_type: &str, id: &str) -> Result<Option<StoredResource>, StorageError>;
async fn update(&mut self, resource: &Value) -> Result<StoredResource, StorageError>;
async fn delete(&mut self, resource_type: &str, id: &str) -> Result<(), StorageError>;
async fn commit(self: Box<Self>) -> Result<(), StorageError>;
async fn rollback(self: Box<Self>) -> Result<(), StorageError>;
}
/// Indicates this transaction uses optimistic locking.
///
/// Reads automatically track versions; commit fails if any
/// tracked resource was modified by another transaction.
pub trait OptimisticTransaction: Transaction {
fn locking_strategy(&self) -> LockingStrategy {
LockingStrategy::Optimistic
}
}
/// Adds conditional operations to transactions.
#[async_trait]
pub trait ConditionalTransaction: Transaction {
async fn create_if_none_exist(
&mut self,
resource: &Value,
search_params: &[SearchParameter],
) -> Result<ConditionalOutcome, StorageError>;
async fn update_conditional(
&mut self,
resource: &Value,
search_params: &[SearchParameter],
) -> Result<ConditionalOutcome, StorageError>;
async fn delete_conditional(
&mut self,
resource_type: &str,
search_params: &[SearchParameter],
) -> Result<ConditionalDeleteOutcome, StorageError>;
}Now a backend can implement:
The current /// Core search: execute a query, return matches.
#[async_trait]
pub trait SearchProvider: ResourceStorage {
async fn search(
&self,
tenant: &TenantContext,
resource_type: &str,
query: &SearchQuery,
) -> Result;
}
/// Adds multi-type search capability.
#[async_trait]
pub trait MultiTypeSearchProvider: SearchProvider {
async fn search_multi(
&self,
tenant: &TenantContext,
resource_types: Option,
query: &SearchQuery,
) -> Result;
}
/// Adds _include support.
#[async_trait]
pub trait IncludeProvider: SearchProvider {
async fn resolve_includes(
&self,
tenant: &TenantContext,
matches: &[StoredResource],
includes: &[IncludeSpec],
) -> Result<Vec, StorageError>;
}
/// Adds _revinclude support.
#[async_trait]
pub trait RevincludeProvider: SearchProvider {
async fn resolve_revincludes(
&self,
tenant: &TenantContext,
matches: &[StoredResource],
revincludes: &[IncludeSpec],
) -> Result<Vec, StorageError>;
}HistoryProvider DecompositionHistory has three levels that not all backends support equally: /// Instance-level history only.
#[async_trait]
pub trait InstanceHistoryProvider: VersionedStorage {
async fn history_instance(
&self,
tenant: &TenantContext,
resource_type: &str,
id: &str,
params: &HistoryParams,
) -> Result;
}
/// Adds type-level history.
#[async_trait]
pub trait TypeHistoryProvider: InstanceHistoryProvider {
async fn history_type(
&self,
tenant: &TenantContext,
resource_type: &str,
params: &HistoryParams,
) -> Result;
}
/// Adds system-level history.
#[async_trait]
pub trait SystemHistoryProvider: TypeHistoryProvider {
async fn history_system(
&self,
tenant: &TenantContext,
params: &HistoryParams,
) -> Result;
} |
Beta Was this translation helpful? Give feedback.
-
|
I would like to initiate a discussion about SQL (Postgres) vs. S3 vs. hybrid storage models and where it would fit the documented polyglot. A question beforehand: The document mentions S3/Object Storage in connection with Parquet. Am I understanding correctly that this mostly refers to an analytical use where the data is mapped to columnar models (prob. following SQL-on-FHIR semantics; or the golden layer in the medallion architecture)? And not so much about primary data store? Some time ago we discussed an aproach where one would use SQL for indexing and search, while putting the full resource content in S3. While this brings its own challenges (single small file writes to S3 are expensive), where would such approach fit in the polyglot architecture? |
Beta Was this translation helpful? Give feedback.
-
|
This is a really great point. I think I should re-title that column from The design should definitely permit either the use of internal database storage of resources (like in JSONB in Postgres for example), or storing them in an Object Store like S3, and then using separate indexing technology to support search. One could imagine almost a database-less design in that case. This is exactly the kind of design the polyglot architecture should support. |
Beta Was this translation helpful? Give feedback.
-
Exploring unstructured data supportI took a closer look at the Feature Support Matrix + the hfs repo. Right now the matrix lists S3/Parquet as a read-only export backend, and the code seems to match that: the SQL-on-FHIR pipeline is focused on transforming FHIR resources into tabular outputs (CSV, JSON, NDJSON, Parquet), with cloud storage support for S3 / GCS / Azure Blob. That all looks geared toward bulk export + analytics, not using object storage as a primary persistence layer for large binaries. I also didn’t see anything around storing/indexing “unstructured” payloads like DICOM imaging artifacts. Given how relevant imaging is becoming for clinical AI, I think it could be worth discussing what “unstructured data support” would look like in HFS. A few ideas to seed the conv:
Is there already a plan for unstructured data support? Curious if this fits the roadmap, and what design patterns folks think make sense for a more “polyglot” FHIR persistence layer. |
Beta Was this translation helpful? Give feedback.
-
|
Great question! Yes, blob/binary storage for things like DICOM images is absolutely part of the architecture. In practice, this would work through FHIR's I didn't call out a specific BinaryStorage or BlobStorage trait in this document since it's more of a strategy discussion than a complete design, but you're right that this deserves explicit treatment. A dedicated trait for binary content management handling uploads, chunked transfers, content-addressable storage, and tiering policies for large objects would fit naturally alongside the other storage traits. |
Beta Was this translation helpful? Give feedback.
-
|
@smunini woah, this is a super ambitious project! I agree separating compute / storage is critical. As an example, I work primarily in DBX which enables comprehensive audit info (SOC 2 folks are thrilled) in a way that doesn't affect query response time. DBX audit logs relies on browser resources, with separate compute for the query. Contrast this with SQL Server, where something like Spotlight can make the query exp dog slow. A few (possibly whacky) ideas this prompted:
I'm a Rust noob, but fun to read and learn a bit of the syntax. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for these thoughts @dr00b. Regarding DBX and auditing, I need to learn more how that's done. An audit project is coming up next for this effort, and as mentioned in the discussion document, I plan to have a separate storage layer for AuditEvents for two reasons - separate from the query engine, as you mention that DBX follows so it doesn't bog down any query activity, and also for SOC2 purposes - in production setups AuditEvents should reside in a append-only store that can't be modified. I'll do some more research on DBX and how they are configured. I like the idea about WASM with an in-memory/kv backend (client-side). Rust has some of the best support for WASM packages, and it would be really interesting to see if a browser-only solution could be built for relatively small (memory) quickie projects, or increasingly an analytic question answered locally with the help of a LLM and some MCP servers. Definitely an area of future work. I read up on SQLAlchemy - very interesting dialect support. Recently in the SQL on FHIR group, we have been working on a SQL Query resource and there is support for multiple dialects. SQLAlchemy supports quite a few!
That's already happening! You're going to see some commits coming up from some very eager students who have approached me who are enthusiastic about Rust, bioinformatics and everything healthcare. If you are a student and would like to get involved in this project, leave a comment here, and let's connect! |
Beta Was this translation helpful? Give feedback.
-
|
I want to personally thank everyone who engaged with this discussion, @lschmierer, @dougc95, @sandhums, @dr00b. Your comments really helped me with my thinking about this important addition to the project. I'm happy to share that an initial PR implementing many of the ideas from this discussion is now available: #30. This will be included in an upcoming release I'm working on shortly. What's in the PR: The PR introduces the helios-persistence crate — a comprehensive FHIR persistence layer with polyglot storage support. Here's what it includes:
What's ahead: We'll be expanding database backend support over time. Beyond persistence, we're moving on to other key roadmap items, notably authentication and authorization, which will be a major focus in upcoming work. Look for a new discussion document to be posted here on GitHub soon on that topic. As always, feedback and contributions are welcome! |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Introduction
As I write this in early 2026, I don't think it is an understatement to say that the opportunities and impact that are upon us with AI in healthcare feels like a Cambrian Explosion moment. Healthcare professionals, administrators, and patients alike will be increasingly chatting with, talking directly to, and collaborating with artificial intelligence software systems in entirely new ways. This will need to be done safely and carefully.
What worked five years ago, or even two years ago, is increasingly inadequate for the demands of clinical AI, population health analytics, and real-time decision support. For technical architects navigating this shift, the challenge isn't just scaling storage; it's rethinking the entire data architecture.
This discussion document shares my thoughts about an approach to persistence for the Helios FHIR Server.
This document is an architecture strategy document. In other words, it describes the main motivating direction, building blocks, and key technology ingredients that will makeup the persistence design for the Helios FHIR Server. It is not intended to be a comprehensive set of requirements and design, but instead contains enough of a starting point such that readers can understand our approach to persistence, and understand why we decided to make the decisions that we did.
Who should read this?
The Helios FHIR Server is open source software, and is being developed in the open. If you have some interest in persistence design for healthcare software - this document is for you!
My hope is that you will think about the contents of this document, comment and provide feedback!
AI Is Driving New Requirements on Data
AI workloads have upended traditional assumptions about data access patterns. Training models demand sustained high-throughput reads across massive datasets, while inference requires low-latency access to distributed data sources. In healthcare, this is compounded by the explosive growth of unstructured data. Radiology images, pathology slides, genomic sequences, clinical notes, and waveform data from monitoring devices to name a few. Structured EHR data, once the center of gravity, is increasingly extracted from the EMR and compared with other external data sources. Architectures optimized for transactional workloads simply cannot deliver the performance AI pipelines require, and retrofitting them is often a losing battle.
Separation of Storage and Compute
Decoupling storage from compute has moved from a cloud-native best practice to an architectural necessity, yet many FHIR server implementations haven't caught up. While cloud-based analytics platforms routinely embrace this separation, transactional FHIR servers often remain tightly coupled to their persistence layers, treating database and application as an inseparable unit. This creates painful trade-offs: over-provisioning compute to get adequate storage, or vice versa. A modern FHIR server must separate these concerns as a core architectural principle, allowing the API layer to scale horizontally for request throughput while the persistence layer scales independently for capacity and query performance. In healthcare AI workloads, this separation is especially critical. Spin up GPU clusters for model training without provisioning redundant storage, or expand storage for imaging archives without paying for idle compute. The persistence layer becomes a service with its own scaling characteristics rather than a monolithic dependency. This separation is now expected as a defining characteristic of production-ready FHIR infrastructure.
Medallion Architecture Within FHIR Persistence
We have seen our largest petabyte-scale customers transition to a Medallion Architecture strategy for their FHIR data. The bronze layer represents resources as received, preserving original payloads, source system identifiers, and ingestion metadata for auditability and replay. The silver layer applies normalization: terminology mapping, reference resolution, deduplication of resources that represent the same clinical entity, and enforcement of business rules that go beyond FHIR validation. The gold layer materializes optimized views for specific consumers, denormalized patient summaries for clinical applications, flattened tabular projections for analytics, or pre-computed feature sets for ML pipelines.
Hybrid and Multi-Cloud Architectures
The reality for most health IT systems is a hybrid footprint: on-premises data centers housing legacy systems and sensitive workloads, cloud platforms providing elastic compute for AI and analytics, and edge infrastructure at clinical sites. Multi-cloud strategies add another dimension, whether driven by M&A activity, best-of-breed vendor selection, or risk diversification.
Security-First and Zero-Trust Patterns in FHIR Persistence
The persistence layer is where FHIR data lives at rest, making it the most critical surface for security enforcement. Zero-trust principles must be embedded in the persistence design itself, not just the API layer above it. This means encryption at rest as a baseline, but also fine-grained access control at the resource, compartment or even finer-grained levels - ensuring that database-level access cannot bypass FHIR authorization semantics. Audit logging must capture all persistence operations with sufficient detail for HIPAA accounting-of-disclosures requirements. This typically means persisting AuditEvent resources to a separately controlled store. Consent enforcement, particularly for sensitive resource types like mental health or substance abuse records under 42 CFR Part 2, often requires persistence-layer support through segmentation, tagging, or dynamic filtering. Treating security as an API-layer concern while leaving the persistence layer permissive creates unacceptable risk.
Data Retention, Tiering, and Cost Optimization
FHIR persistence layers accumulate data over years and decades. Version history, provenance records, and audit logs all create significant cost pressure. Intelligent tiering within the persistence layer moves older resource versions and infrequently accessed resources to lower-cost storage classes while keeping current data on performant storage. The architectural challenge is maintaining query semantics across tiers: a search that spans active and archived resources should work transparently, even if archived retrieval is slower. Retention policies must account for regulatory requirements that vary by resource type. Imaging studies may have different retention mandates than clinical notes. A well-designed persistence layer makes tiering a configuration concern rather than an architectural constraint.
Different Data Technologies for Different Problems
A FHIR persistence layer that commits to a single storage technology is making a bet that one tool can serve all masters. This is a bet that rarely pays off as requirements evolve. The reality is that different access patterns, query types, and workloads have fundamentally different performance characteristics, and no single database technology optimizes for all of them. A patient lookup by identifier, a population-level cohort query, a graph traversal of care team relationships, and a semantic similarity search for clinical trial matching across different terminology code systems are all legitimate operations against FHIR data, yet each performs best on a different underlying technology.
Relational Databases remain the workhorse for transactional FHIR operations, offering ACID guarantees, mature tooling, and well-understood query optimization for structured data with predictable access patterns.
NoSQL Databases - particularly document stores - align naturally with FHIR's resource model, persisting resources as complete documents without the impedance mismatch of relational decomposition, and scaling horizontally for high-throughput ingestion. Additionally, Cassandra has been exceptional at handling web-scale data requirements without breaking the bank.
Data Lakes provide cost-effective, schema-flexible storage for raw FHIR resources and bulk exports, serving as the foundation for large-scale analytics and ML training pipelines that need to process millions of resources.
Data Warehouses deliver optimized analytical query performance over structured, transformed FHIR data, enabling population health analytics, quality measure computation, and business intelligence workloads that would overwhelm transactional systems.
Graph Databases excel at traversing relationships. Patient to provider to organization to care team is an example relationship pathway that are represented as references in FHIR but are expensive to navigate through recursive joins in relational systems.
Vector Databases enable semantic search and similarity matching over embedded representations of clinical text, supporting AI use cases like similar-patient retrieval, terminology matching, and contextual search that go beyond keyword-based FHIR queries.
Block Storage provides the high-performance, low-latency foundation for database engines themselves, while also serving large binary attachments, imaging data, scanned documents, and waveforms that are referenced by FHIR resources but impractical to store within the resource payload.
The architectural discipline is not choosing one technology but designing the abstraction layer that routes FHIR operations to the appropriate backend while maintaining consistency, security, and a coherent developer experience.
Positioning the Helios FHIR Server in the FHIR Server Landscape
The FHIR server landscape can be understood along two architectural dimensions: how tightly the implementation is coupled to its storage technology, and whether the system supports multiple specialized data stores or requires a single backend.
The vertical axis distinguishes between servers with tightly-coupled persistence where the implementation is deeply intertwined with a specific database technology, and those offering an extensible interface layer that abstracts storage concerns behind well-defined interfaces. A FHIR Server built directly on JPA (Java Persistence API) is such an example, meaning its data access patterns, query capabilities, and performance characteristics are fundamentally shaped by relational database assumptions. In contrast, an extensible interface layer defines traits or interfaces that can be implemented for any storage technology, allowing the same FHIR API to sit atop different backends without rewriting core logic.
The horizontal axis captures the difference between single storage backend architectures and polyglot persistence. Polyglot persistence is an architectural pattern where different types of data are routed to the storage technologies best suited for how that data will be accessed. For example, a polyglot system might store clinical documents in an object store optimized for large binary content, maintain patient relationships in a graph database for efficient traversal, and keep structured observations in a columnar store for fast analytical queries all while presenting a unified FHIR API to consuming applications. Most existing FHIR servers force all resources into a single database, sacrificing performance and flexibility for implementation simplicity.
The Helios FHIR Server occupies the upper-right quadrant: it combines a trait-based, open-source interface layer built in Rust with native support for polyglot persistence. This architecture allows organizations to optimize storage decisions for their specific access patterns while maintaining full FHIR compliance at the API layer.
Decomposing the FHIR Specification: Separation of Concerns in Persistence Design
The FHIR specification is vast. It defines resource structures, REST interactions, search semantics, terminology operations, versioning behavior, and much more. A monolithic interface, or trait that attempts to capture all of this becomes unwieldy, difficult to implement, and impossible to optimize for specific storage technologies. The Helios FHIR Server persistence design takes a different approach: decompose the specification into cohesive concerns, express each as a focused trait, and compose them to build complete storage backends.
Learning from Diesel: Type-Safe Database Abstractions
Before diving into our trait design, it's worth examining what we can learn from Diesel, Rust's most mature database abstraction layer. Diesel has solved many of the problems we face - multi-backend support, compile-time query validation, extensibility, and its design choices offer valuable lessons.
Backend Abstraction via Traits, Not Enums: Diesel defines a
Backendtrait that captures the differences between database systems (PostgreSQL, MySQL, SQLite) without coupling to specific implementations. TheBackendtrait specifies how SQL is generated, how bind parameters are collected, and how types are mapped. This allows new backends to be added without modifying core code. This is exactly what we need for polyglot FHIR persistence.QueryFragment for Composable SQL Generation: Diesel's
QueryFragmenttrait represents any piece of SQL that can be rendered. A WHERE clause, a JOIN, an entire SELECT statement all implementQueryFragment. This composability lets complex queries be built from simple pieces. For FHIR search, we can adopt a similar pattern: each search parameter modifier becomes a fragment that can be composed into complete queries.Type-Level Query Validation: Diesel catches many errors at compile time by encoding schema information in the type system. While we can't achieve the same level of compile-time validation for dynamic FHIR queries, we can use Rust's type system to ensure that storage backends only claim to support operations they actually implement.
MultiConnection for Runtime Backend Selection: Diesel's
#[derive(MultiConnection)]generates an enum that wraps multiple connection types, dispatching operations to the appropriate backend at runtime. This pattern directly applies to polyglot persistence. We can route FHIR operations to different backends based on query characteristics.Extensibility via sql_function! and Custom Types: Diesel makes it trivial to add custom SQL functions and types. For FHIR, this translates to extensibility for custom search parameters, terminology operations, and backend-specific optimizations.
The Core Resource Storage Trait
At the foundation is the
ResourceStoragetrait, which handles the fundamental persistence of FHIR resources. This trait intentionally knows nothing about search, nothing about REST semantics, nothing about transactions. It simply stores and retrieves resources by type and identifier.Multitenancy is not optional in this design. Every operation requires a
TenantContext, making it impossible at the type level to accidentally execute a query without tenant scoping. There is no "escape hatch" that bypasses tenant isolation.Notice what's absent: there's no
if_matchparameter for optimistic concurrency, no version-specific reads, no history. Those capabilities belong to separate traits that extend the base functionality. A storage backend that doesn't support versioning simply doesn't implement the versioning trait.Multitenancy: A Cross-Cutting Concern
Multitenancy has downstream implications for every layer of a FHIR server, from indexing strategy to reference validation to search semantics. By requiring tenant context at the lowest storage layer, we ensure that isolation guarantees propagate upward through the entire system.
Isolation Strategies
There are three fundamental approaches to tenant isolation, each with different trade-offs:
Database-per-tenant: Strongest isolation, simplest security model, easier compliance story. The downside is operational overhead that grows linearly with tenants. Connection pool management becomes complex, and schema migrations are painful at scale.
Schema-per-tenant: Good isolation within a single database instance, allows tenant-specific indexing. PostgreSQL handles this well. Still has schema migration coordination challenges.
Shared schema with tenant discriminator: Most operationally efficient at scale, single migration path. The risk is that every query must include tenant filtering. One missed WHERE clause and you have a data breach.
For SQL-backed FHIR persistence, the shared schema approach with a
tenant_iddiscriminator is pragmatic, but the enforcement layer must be airtight - you literally cannot construct a storage operation without providing tenant context.Tenant Context as a Type-Level Guarantee
Borrowing from Diesel's approach to type safety, we can make tenant context explicit in the type system. Rather than passing tenant IDs as strings that might be forgotten, we create a wrapper type that must be present for any storage operation:
Shared Resources and the System Tenant
CodeSystems, ValueSets, StructureDefinitions, and other conformance resources are typically shared across tenants. We designate a "system" tenant that holds these shared resources:
Index Design for Multitenancy
Search performance in a multitenant system depends critically on index design. The
tenant_idmust be the leading column in composite indexes:Versioning as a Separate Concern
FHIR's versioning model is sophisticated: every update creates a new version, version IDs are opaque strings, and the
vreadinteraction retrieves historical versions. Not all storage backends can efficiently support this. An append-only data lake handles versioning naturally; a key-value store might not.History: Building on Versioning
History access naturally extends versioning. If a backend can read specific versions, it can also enumerate them:
The trait hierarchy
HistoryProvider: VersionedStorage: ResourceStoragemeans that any storage backend supporting history automatically supports versioned reads and basic CRUD - all within tenant boundaries. The type system enforces this relationship.The Search Abstraction: Decomposing FHIR's Query Model
Search is where the FHIR specification becomes genuinely complex. There are eight search parameter types (number, date, string, token, reference, quantity, uri, composite), sixteen modifiers (
:exact,:contains,:not,:missing,:above,:below,:in,:not-in,:of-type,:identifier,:text,:code-text,:text-advanced,:iterate, plus resource type modifiers on references), six comparison prefixes (eq,ne,lt,le,gt,ge,sa,eb,ap), chained parameters, reverse chaining (_has),_includeand_revincludedirectives, and advanced filtering via_filter. A single search query can combine all of these all while respecting tenant boundaries.Modeling search as a single trait would be a mistake. Instead, we decompose it into layers - and here, Diesel's
QueryFragmentpattern proves invaluable.The SearchFragment Pattern (Inspired by Diesel's QueryFragment)
Diesel's
QueryFragmenttrait allows any piece of SQL to be composable. We adapt this pattern for FHIR search, creating fragments that can be combined into complete search queries:Each search modifier becomes a fragment that knows how to render itself:
Search Parameter Types
First, we model the search parameter types and their associated matching logic:
The Core Search Trait
The base search trait handles fundamental query execution without advanced features:
Advanced Search Capabilities as Extension Traits
Not every storage backend can support every search feature. A relational database might handle token searches efficiently but struggle with subsumption queries that require terminology reasoning. A vector database might excel at text search but lack native support for date range queries. We model these variations as extension traits.
Chained Search Provider:
Terminology Search Provider:
Text Search Provider:
This decomposition has practical consequences. When configuring a polyglot persistence layer, we can route terminology-aware searches to a backend that integrates with a terminology server (perhaps backed by a graph database), while directing simple token matches to a faster document store. The trait system makes these routing decisions explicit and type-safe.
Transactions: When Atomicity Matters
FHIR defines batch and transaction bundles. A batch processes entries independently; a transaction either succeeds completely or fails entirely with no partial effects. This all-or-nothing semantics requires database-level transaction support - something not all storage technologies provide natively.
A storage backend that doesn't support transactions can still handle batch operations. It simply processes each entry independently, accepting that failures may leave partial results. The trait separation makes this distinction clear: code that requires atomicity takes
&dyn TransactionProvider, while code that can tolerate partial failures takes&dyn ResourceStorage.Audit Events: A Separated Persistence Store
AuditEvent resources should be ideally stored separately from clinical data. This isn't just a security concern, it's also an architectural one. Audit logs have different access patterns (append-heavy, rarely queried except during investigations), different retention requirements (often longer than clinical data), and different security constraints (must be tamper-evident, may require separate access controls).
The separation of
AuditStoragefromResourceStorageenables critical architectural flexibility. Audit events can flow to a dedicated time-series database optimized for append-only writes, or to an immutable ledger for tamper evidence, or to a separate cloud account for security isolation.The REST Layer: Mapping HTTP to Storage
The FHIR REST API defines interactions (read, vread, update, create, delete, search, etc.) that map HTTP verbs and URL patterns to operations. This mapping is a separate concern from storage. The same storage backend might be accessed via REST, GraphQL, messaging, or bulk export.
The
RestHandleris a coordination layer that combines multiple storage traits to implement FHIR REST semantics. A read interaction needs onlyResourceStorage. A vread needsVersionedStorage. A search with_includeneeds bothSearchProviderandResourceStorage. The REST handler composes these capabilities based on what the request requires and what the storage backend provides.Capability Statements: Documenting What Storage Supports
The FHIR specification requires servers to publish a CapabilityStatement declaring which interactions, resources, and search parameters they support. When storage backends have different capabilities, this statement must accurately reflect the union of what's available and identify gaps.
Diesel solves a similar problem with its type system. Operations that aren't supported simply don't compile. For FHIR, we need runtime capability discovery because queries are dynamic. We model storage capabilities as a queryable trait that can generate CapabilityStatement fragments:
Dynamic Capability Checking
For operations that can't be checked at compile time, we provide runtime capability checking that fails fast with clear error messages:
The Feature Support Matrix
Different storage technologies have different strengths. A key deliverable of the Helios FHIR Server's persistence design is a clear feature support matrix that documents what each storage backend provides. This (example, work-in-progress) matrix drives both the CapabilityStatement generation and helps operators choose the right backend for their workload.
This matrix isn't static. It's generated from the
StorageCapabilitiesimplementations. When a new storage backend is added or an existing one gains features, the matrix updates automatically.Composing Storage Backends (Inspired by Diesel's MultiConnection)
Diesel's
MultiConnectionderive macro generates an enum that wraps multiple connection types, dispatching to the appropriate backend at runtime. We adapt this pattern for polyglot FHIR persistence, but with intelligent routing based on query characteristics:The routing logic becomes explicit policy that considers both capabilities and cost:
The Path Forward
This trait-based decomposition provides a foundation for building a FHIR persistence layer that can evolve with requirements. When AI workloads demand vector similarity search, we add a
VectorSearchProvidertrait and plug in a vector database. When regulatory requirements demand immutable audit trails, we implementAuditStorageagainst an append-only ledger. When performance analysis reveals that graph traversals are bottlenecking population health queries, we route those operations to a dedicated graph database.Extensibility Following Diesel's Model: Just as Diesel's
sql_function!macro makes it trivial to add custom SQL functions, our design should make it easy to add custom search parameters and modifiers. A healthcare organization might need a custom:phoneticmodifier for patient name matching, or a:geo-nearmodifier for location-based searches. TheSearchFragmentpattern enables this:This is what it means to build FHIR persistence for the AI era: not a monolithic database adapter, but a composable system of specialized capabilities that can be assembled to meet the specific needs of each deployment with tenant isolation, search routing, and extensibility built into the architecture from the start.
Thank you!
I very much look forward to your thoughts on these ideas and to the discussions that follow.
Sincerely,
-Steve
Beta Was this translation helpful? Give feedback.
All reactions