Crate helios_sof

Expand description

§SQL-on-FHIR Implementation

This crate provides a complete implementation of the SQL-on-FHIR specification, enabling the transformation of FHIR resources into tabular data using declarative ViewDefinitions. It supports all major FHIR versions (R4, R4B, R5, R6) through a version-agnostic abstraction layer.

There are three consumers of this crate:

sof_cli - A command-line interface for the SQL-on-FHIR implementation, allowing users to execute ViewDefinition transformations on FHIR Bundle resources and output the results in various formats.
sof_server - A stateless HTTP server implementation for the SQL-on-FHIR specification, enabling HTTP-based access to ViewDefinition transformation capabilities.
hfs - The full featured Helios FHIR Server.

§Architecture

The SOF crate is organized around these key components:

Version-agnostic enums (SofViewDefinition, SofBundle): Multi-version containers
Processing engine (run_view_definition): Core transformation logic
Output formats (ContentType): Support for CSV, JSON, NDJSON, and Parquet
Trait abstractions (ViewDefinitionTrait, BundleTrait): Version independence

§Key Features

Multi-version FHIR support: Works with R4, R4B, R5, and R6 resources
FHIRPath evaluation: Complex path expressions for data extraction
forEach iteration: Supports flattening of nested FHIR structures
unionAll operations: Combines multiple select statements
Collection handling: Proper array serialization for multi-valued fields
Output formats: CSV (with/without headers), JSON, NDJSON, Parquet support

§Usage Example

use helios_sof::{SofViewDefinition, SofBundle, ContentType, run_view_definition};
use helios_fhir::FhirVersion;

// Parse a ViewDefinition and Bundle from JSON
let view_definition_json = r#"{
    "resourceType": "ViewDefinition",
    "status": "active",
    "resource": "Patient",
    "select": [{
        "column": [{
            "name": "id",
            "path": "id"
        }, {
            "name": "name",
            "path": "name.family"
        }]
    }]
}"#;

let bundle_json = r#"{
    "resourceType": "Bundle",
    "type": "collection",
    "entry": [{
        "resource": {
            "resourceType": "Patient",
            "id": "example",
            "name": [{
                "family": "Doe",
                "given": ["John"]
            }]
        }
    }]
}"#;

let view_definition: helios_fhir::r4::ViewDefinition = serde_json::from_str(view_definition_json)?;
let bundle: helios_fhir::r4::Bundle = serde_json::from_str(bundle_json)?;

// Wrap in version-agnostic containers
let sof_view = SofViewDefinition::R4(view_definition);
let sof_bundle = SofBundle::R4(bundle);

// Transform to CSV with headers
let csv_output = run_view_definition(
    sof_view,
    sof_bundle,
    ContentType::CsvWithHeader
)?;

// Check the CSV output
let csv_string = String::from_utf8(csv_output)?;
assert!(csv_string.contains("id,name"));
// CSV values are quoted
assert!(csv_string.contains("example") && csv_string.contains("Doe"));

§Advanced Features

§forEach Iteration

ViewDefinitions can iterate over collections using forEach and forEachOrNull:

{
  "select": [{
    "forEach": "name",
    "column": [{
      "name": "family_name",
      "path": "family"
    }]
  }]
}

§Constants and Variables

Define reusable values in ViewDefinitions:

{
  "constant": [{
    "name": "system",
    "valueString": "http://loinc.org"
  }],
  "select": [{
    "where": [{
      "path": "code.coding.system = %system"
    }]
  }]
}

§Where Clauses

Filter resources using FHIRPath expressions:

{
  "where": [{
    "path": "active = true"
  }, {
    "path": "birthDate.exists()"
  }]
}

§Error Handling

The crate provides comprehensive error handling through SofError:

use helios_sof::{SofError, SofViewDefinition, SofBundle, ContentType, run_view_definition};

match run_view_definition(view, bundle, content_type) {
    Ok(output) => {
        // Process successful transformation
    },
    Err(SofError::InvalidViewDefinition(msg)) => {
        eprintln!("ViewDefinition validation failed: {}", msg);
    },
    Err(SofError::FhirPathError(msg)) => {
        eprintln!("FHIRPath evaluation failed: {}", msg);
    },
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}

§Feature Flags

Enable support for specific FHIR versions:

R4: FHIR 4.0.1 support
R4B: FHIR 4.3.0 support
R5: FHIR 5.0.0 support
R6: FHIR 6.0.0 support

Re-exports§

pub use compartment::resolve_group_members_to_patient_refs;
pub use compartment::resource_in_patient_compartment;
pub use constants::ConstantValue;
pub use constants::parse_constant_from_json;
pub use params::ExtractedRunParams;
pub use params::body_has_view_definition;
pub use params::extract_run_params_from_json;
pub use params::split_csv_refs;
pub use sqlquery::BoundParam;
pub use sqlquery::ColumnFhirType;
pub use sqlquery::DependsOnView;
pub use sqlquery::InMemorySqlEngine;
pub use sqlquery::LibraryParameter;
pub use sqlquery::QueryResult;
pub use sqlquery::SqlQueryError;
pub use sqlquery::SqlQueryLibrary;
pub use sqlquery::SqlQueryRunParams;
pub use sqlquery::TableSchema;
pub use sqlquery::bind_supplied_params;
pub use sqlquery::extract_sqlquery_params_from_json;
pub use sqlquery::format_fhir_parameters;
pub use sqlquery::parse_sqlquery_library;
pub use traits::BundleTrait;
pub use traits::ResourceTrait;
pub use traits::ViewDefinitionTrait;

Modules§

compartment: Compartment-aware membership checks for $viewdefinition-run filtering.
constants: Shared SoF v2 ViewDefinition.constant[] parsing.
data_source: FHIR Data Source Loading
fhir_format: Shared fhir-format output and FHIR-representation content negotiation for the SQL-on-FHIR run operations (SoF v2 Common Operation Behavior).
params: Shared SoF v2 $viewdefinition-run parameter extraction.
parquet_schema: Parquet Schema Generation for SQL-on-FHIR
sqlquery: SQL-on-FHIR v2 $sqlquery-run engine.
traits: Version-Agnostic FHIR Abstraction Traits

Structs§

ChunkConfig: Configuration for chunked NDJSON processing.
ChunkedResult: Result from processing a single chunk of resources.
NdjsonChunkIterator: Iterator that combines NDJSON reading with ViewDefinition processing.
NdjsonChunkReader: Reads NDJSON files in chunks, yielding parsed resources.
ParquetOptions: Configuration options for Parquet file generation.
PreparedViewDefinition: Pre-validated ViewDefinition for efficient reuse across multiple chunks.
ProcessedResult: Complete result of ViewDefinition transformation containing columns and data rows.
ProcessedRow: A single row of processed tabular data from ViewDefinition transformation.
ProcessingStats: Statistics from chunked processing.
ResourceChunk: A chunk of parsed FHIR resources from an NDJSON file.
RunOptions: Options for filtering and controlling ViewDefinition execution

Enums§

ContentType: Supported output content types for ViewDefinition transformations.
FhirVersion: Enumeration of supported FHIR specification versions.
SofBundle: Multi-version Bundle container supporting version-agnostic operations.
SofCapabilityStatement: Multi-version CapabilityStatement container supporting version-agnostic operations.
SofError: Comprehensive error type for SQL-on-FHIR operations.
SofViewDefinition: Multi-version ViewDefinition container supporting version-agnostic operations.

Functions§

create_bundle_from_resources: Wraps a list of raw FHIR resources in a collection Bundle of the newest enabled FHIR version.
create_bundle_from_resources_for_version: Wraps a list of raw FHIR resources in a collection Bundle of the specified FHIR version.
filter_resources_by_patient_and_group: Filters raw FHIR resource JSON by patient and/or group references using the FHIR CompartmentDefinition-patient spec data.
filter_resources_by_since: Filters raw FHIR resource JSON by their meta.lastUpdated timestamp, returning only resources whose lastUpdated is strictly after since. Resources without meta.lastUpdated are excluded.
format_csv: Encodes a ProcessedResult as CSV bytes via the csv crate (RFC 4180).
format_json: Encodes a ProcessedResult as a pretty-printed JSON array of row objects. Missing column values are emitted as null.
format_ndjson: Encodes a ProcessedResult as newline-delimited JSON. One row per line; missing column values are emitted as null.
format_output: Renders a ProcessedResult to bytes in the requested ContentType.
format_parquet: Encodes a ProcessedResult as a single Parquet file in memory.
format_parquet_multi_file: Format Parquet data with automatic file splitting when size exceeds limit
get_fhir_version_string: Returns the FHIR version string for the newest enabled version.
get_newest_enabled_fhir_version: Returns the newest FHIR version that is enabled at compile time.
iter_ndjson_chunks: Create an iterator for chunked NDJSON processing.
parse_view_definition: Parses a JSON value into a SofViewDefinition using the newest enabled FHIR version.
parse_view_definition_for_version: Parses a JSON value into a SofViewDefinition using the specified FHIR version.
process_ndjson_chunked: Process an NDJSON input stream and write output incrementally.
process_view_definition
rows_to_processed_result: Builds a ProcessedResult from a stream of flat JSON-object rows.
run_view_definition: Execute a SQL-on-FHIR ViewDefinition transformation on a FHIR Bundle.
run_view_definition_with_options: Execute a ViewDefinition transformation with additional filtering options.

Type Aliases§

SofParameters: Type alias for the version-independent Parameters container.

Crate helios_sof

Crate helios_sof Copy item path

§SQL-on-FHIR Implementation

§Architecture

§Key Features

§Usage Example

§Advanced Features

§forEach Iteration

§Constants and Variables

§Where Clauses

§Error Handling

§Feature Flags

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate helios_sof