Quickstart

The fastest honest test of Mercury is parity plus speed: run the same libraries and patients through Mercury and your current engine, and compare. This page gets you to a first result.

Prerequisites

• Docker.
• The private registry image URI and credentials you were sent.
• The CQL libraries you already use — or their compiled ELM XML.
• A FHIR patient bundle and any value sets the measure under test needs.
• Optional: your existing reference stack, running, for a side-by-side comparison.

Get the image

Community Edition is distributed as a container image from a private registry. Sign in with the credentials you were sent, then pull:

docker login <registry-host>
docker pull IMAGE_URI

Examples below use MERCURY_IMAGE:

export MERCURY_IMAGE=IMAGE_URI

Limited release

There is no public download yet. If you do not have credentials, request access.

The happy path

1. Start the server.

   Docker

   docker rm -f mercury-quickstart >/dev/null 2>&1 || true
   docker run --rm \
     -d \
     --name mercury-quickstart \
     -p 8080:8080 \
     -v mercury-data:/var/lib/mercury \
     "$MERCURY_IMAGE"
   sleep 3

   Binary

   mercury serve --host 127.0.0.1 --port 8080

   Mercury exposes its routes under the base paths /cqf, /api, and /fhir. Confirm it’s up:

   curl -fsS http://127.0.0.1:8080/api/health

   Example response:

   {
     "status": "UP",
     "version": "<your version>",
     "edition": "community",
     "packs": ["core"]
   }

   The exact version value reflects the build you pulled.

2. Download the fixture files — or substitute your own bundle and library.

   export DOCS_BASE_URL=https://docs.getcql.com
   curl -fsS -o patient-bundle.json \
     "$DOCS_BASE_URL/quickstart/patient-bundle.json"
   curl -fsS -o QuickstartLibrary.Library.json \
     "$DOCS_BASE_URL/quickstart/QuickstartLibrary.Library.json"

3. Load data — POST a FHIR bundle.

   curl -X POST http://127.0.0.1:8080/cqf/data/bundle \
     -H "Content-Type: application/fhir+json" \
     --data @patient-bundle.json

4. Load a library — CQL or ELM embedded in a FHIR Library resource.

   curl -X POST http://127.0.0.1:8080/cqf/Library \
     -H "Content-Type: application/fhir+json" \
     --data @QuickstartLibrary.Library.json

5. Execute — evaluate for a subject and expression.

   curl "http://127.0.0.1:8080/cqf/Library/QuickstartLibrary/\$evaluate?subject=Patient/quickstart-patient&expression=Initial%20Population"

6. Clean up when finished.

   docker rm -f mercury-quickstart

Expected result

A FHIR Parameters resource whose evaluate part lists Initial Population with valueBoolean: true.

Contributors / Source Repo

If you have the source repository, you can build a local contributor image and run the in-repo smoke:

docker build -t mercury:community .
scripts/quickstart_smoke.sh

Partners using only an image URI do not need the source repository.

One-shot: the run command

Prefer a single command without starting the server? The CLI run command evaluates local artifacts in-process. Data is supplied inline and isn’t persisted — ideal for quick checks and CI.

mercury run \
  --data bundle.json \
  --valueset valuesets.json \
  --operation Test:1.0.0:InDenominator \
  --cql Test.cql \
  --context patient-1 \
  --parameter "Measurement Period_start:2025-01-01:DateTime" \
  --parameter "Measurement Period_end:2026-01-01:DateTime"

See the difference between loading data ahead of time and passing it inline in Loading data: preload vs inline.

To verify the binary edition without the startup banner:

mercury --no-banner edition

Community builds report edition=community and enable Core only by default. Interoperability and observability surfaces stay off unless explicitly enabled.

What success looks like

• Mercury returns the same population results as your reference engine for the same libraries and patients.
• Your existing MCT or harness runs unchanged against Mercury’s base URL.
• Evaluation latency and throughput improve measurably on your workload.

Next steps

• Running the containers — the full drop-in stack and its ports.
• Mounting your data drive — keep state across restarts.
• CQF API reference — every endpoint you just used.
• AWS Marketplace — customer deployment placeholders for paid Core container and AMI listings.
• Hit a snag? Troubleshooting & FAQ.
• Ran it? Send evaluation feedback — what worked, what broke, and whether results matched your reference engine.