Loading data: preload vs inline

Before Mercury can evaluate a measure for a patient, it needs the patient’s FHIR resources. There are two patterns for getting them there. They’re not mutually exclusive — most teams use both, for different jobs.

The two patterns

Preload

Load data into the server once, then evaluate against it by subject as many times as you like. Data is stored in Mercury’s durable local corpus and survives restarts.

Inline

Supply data with each request as a throwaway execution. Nothing is persisted — the run is self-contained and reproducible.

Preload — load once, evaluate many

Post a FHIR bundle to the server, then reference patients by subject on $evaluate. This is the right pattern for population runs, repeated evaluations, and anything where the same data is reused.

# 1. Load the data into the server's corpus
curl -X POST http://127.0.0.1:8080/cqf/data/bundle \
  -H "Content-Type: application/fhir+json" \
  --data @patients.bundle.json

# 2. Evaluate by subject — the data is already there
curl "http://127.0.0.1:8080/cqf/Library/Test/\$evaluate?subject=Patient/123&expression=InDenominator"

Because the corpus is persistent, the loaded data is still available after a restart — provided you’ve mounted a volume for it. See Mounting your data drive.

Inline — data with the request

The CLI run command bundles data, library, and operation into a single local execution. Nothing persists, so each run is isolated and easy to reproduce — ideal for quick tests, CI checks, and one-off comparisons.

mercury run \
  --data bundle.json \
  --valueset valuesets.json \
  --operation Test:1.0.0:InDenominator \
  --cql Test.cql \
  --context patient-1

--valueset and --parameter are repeatable; see the CLI reference.

Which should I use?

If you want to…	Use
Run a measure across many patients	Preload
Re-evaluate the same cohort repeatedly	Preload
Keep data available across restarts	Preload (+ a mounted volume)
Run a fast, isolated check in CI	Inline (`mercury run`)
Reproduce a single result exactly	Inline
Avoid leaving any state on the server	Inline

Next steps

Mounting your data drive — make preloaded data durable.
CQF API reference — /cqf/data/bundle, Library, $evaluate.
CLI reference — every flag for mercury run.