Crate helios_sof 

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 traits::BundleTrait;

pub use traits::ResourceTrait;

pub use traits::ViewDefinitionTrait;

Modules

data_source

FHIR Data Source Loading

parquet_schema

Parquet Schema Generation for SQL-on-FHIR

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

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.

process_ndjson_chunked

Process an NDJSON input stream and write output incrementally.

process_view_definition

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.