blazectl is a command line tool to control your FHIR® server. blazectl also works with Blaze.
Currently, you can do the following:
- upload transaction bundles from a directory
- download resources in NDJSON format
- count all resources by type
- evaluate a measure
blazectl is available as binary for Linux, macOS and Windows.
For Linux and macOS an install.sh script is provided. It will download a tar file, extract it, and verify GitHub attestations using the GitHub CLI tool.
curl -sSfL https://raw.githubusercontent.com/samply/blazectl/main/install.sh | shIf you prefer a manual installation or need the Windows variant, please download the latest release here. The attestation verification is described below.
blazectl is a command line tool to control your FHIR® server.
Currently you can upload transaction bundles from a directory, download
and count resources and evaluate measures.
Usage:
blazectl [command]
Available Commands:
compact Compact a Database Column Family
completion Generate the autocompletion script for the specified shell
count-resources Counts all resources by type
disk-perf Measure Disk Performance
download Download resources in NDJSON format
download-history Download history in NDJSON format
evaluate-measure Evaluates a Measure
help Help about any command
render-report Renders a MeasureReport
upload Upload transaction bundles
Flags:
--certificate-authority string path to a cert file for the certificate authority
-h, --help help for blazectl
-k, --insecure allow insecure server connections when using SSL
--no-progress don't show progress bar
--password string password information for basic authentication
--token string bearer token for authentication
--user string user information for basic authentication
-v, --version version for blazectl
Use "blazectl [command] --help" for more information about a command.
You can use the upload command to upload transaction bundles to your server. Currently, JSON (.json), gzip compressed JSON (.json.gz), bzip2 compressed JSON (.json.bz2) and NDJSON (.ndjson) files are supported. If you don't have any transaction bundles, you can generate some with SyntheaTM.
Assuming the URL of your FHIR server is http://localhost:8080/fhir, in order to upload run:
blazectl upload --server http://localhost:8080/fhir my/bundlesYou will see a progress bar with an estimated ETA during upload. After the upload, a statistic inspired by vegeta will be printed:
Starting Upload to http://localhost:8080/fhir ...
Uploads [total, concurrency] 362, 4
Success [ratio] 100 %
Duration [total] 1m42s
Requ. Latencies [mean, 50, 95, 99, max] 826ms, 534ms, 2.71s, 3.85s 6.467s
Proc. Latencies [mean, 50, 95, 99, max] 710ms, 526ms, 2.041s, 2.739s 4.133s
Bytes In [total, mean] 5.10 MiB, 14.59 KiB
Bytes Out [total, mean] 61.74 MiB, 176.59 KiB
Status Codes [code:count] 200:362
The statistics have the following meaning:
- Uploads — the total number of files uploaded with the given concurrency
- Success — the success rate (possible errors will be printed under the statistics)
- Duration – the total duration of the upload
- Requ. Latencies – mean, max and percentiles of the duration of whole requests including network transfers
- Proc. Latencies – mean, max and percentiles of the duration of the server processing time excluding networks transfers
- Bytes In – total and mean number of bytes returned by the server
- Bytes Out – total and mean number of bytes send by blazectl
- Status Codes – a list of status code frequencies. Will show non-200 status codes if they happen.
You can use the download command to download bundles from the server. Downloaded bundles are stored within an NDJSON file. This operation is non-destructive on your site, i.e., if the specified NDJSON file already exists, then it won't be overwritten.
Use the download command as follows:
blazectl download --server http://localhost:8080/fhir Patient \
--query "gender=female" \
--output-file ~/Downloads/Patients.ndjsonIf the optional resource-type is given, the corresponding type-level search will be used. Otherwise, the system-level search will be used and all resources of the whole system will be downloaded.
The --query flag will take an optional FHIR search query that will be used to constrain the resources to download. If the query starts with an @, the rest is interpreted as filename to read the query from. Using this filename syntax, it's possible to supply very large query strings.
With the flag --use-post, you can ensure that the FHIR search query specified with --query is send as POST request in the body.
Using POST can have two benefits, first if the query string is too large for URL's, it will still fine in the body. Second if the query string contains sensitive information like IDAT's it will be less likely end up in log files, because URL's are often logged but bodies not.
The next links are still traversed with GET. The FHIR server is supposed to not expose any sensitive query params in the URL and also keep the URL short enough.
Resources will be either streamed to STDOUT, delimited by newline, or stored in a file if the --output-file flag is given.
As soon as the download has finished, you will be shown a download statistics overview that looks something like this:
Pages [total] 184
Resources [total] 1835
Resources/Page [min, mean, max] 5, 9, 10
Duration [total] 371ms
Requ. Latencies [mean, 50, 95, 99, max] 1ms, 1ms, 2ms, 2ms, 3ms
Proc. Latencies [mean, 50, 95, 99, max] 1ms, 1ms, 1ms, 2ms, 3ms
Bytes In [total, mean] 1.22 MiB, 6.82 KiB
The statistics have the following meaning:
- Pages - total number of pages requested from the server to retrieve resources
- Resources - total number of downloaded resources
- Resources/Page - minimum, mean and maximum number of resources over all pages
- Duration - total duration of the download
- Requ. Latencies - mean, max and percentiles of the duration of whole requests including networks transfers
- Proc. Latencies - mean, max and percentiles of the duration of the server processing time excluding network transfers
- Bytes In - total and mean number of bytes returned by the server
The count-resources command is useful to see how many resources a FHIR server stores by resource type. The resource counting is done by first fetching the capability statement of the server. After that blazectl will perform a search-type interaction with query parameter _summary set to count on every resource type which supports that interaction using one batch request. Bundle.total will be used as resource count.
You can run:
blazectl count-resources --server http://localhost:8080/fhirIt will return:
Count all resources on http://localhost:8080/fhir ...
AllergyIntolerance : 7297
CarePlan : 49818
Claim : 689111
Condition : 116688
DiagnosticReport : 193141
Encounter : 540542
ExplanationOfBenefit : 540542
Goal : 39857
ImagingStudy : 11212
Immunization : 187987
MedicationAdministration : 6400
MedicationRequest : 148569
Observation : 2689215
Organization : 52645
Patient : 16875
Practitioner : 52647
Procedure : 418310
Given a measure in YAML form, creates the required FHIR resources, evaluates that measure and returns the measure report.
You can run:
blazectl evaluate-measure --server "http://localhost:8080/fhir" query.ymlIf the CQL library declares parameters, you can pass values for them with the repeatable --parameter (-p) flag in the form name=value:
blazectl evaluate-measure --server "http://localhost:8080/fhir" --parameter MinAge=21 query.ymlThe type is taken from the command line when given in the form name:type=value, otherwise it defaults to string:
blazectl evaluate-measure --server "http://localhost:8080/fhir" \
--parameter Gender=male --parameter MinAge:integer=18 query.ymlThe supported types are string, code, date, dateTime, boolean, integer and decimal. Repeating the same name supplies a list, which is mapped to a CQL list:
blazectl evaluate-measure --server "http://localhost:8080/fhir" \
--parameter Codes:code=38341003 --parameter Codes:code=73211009 query.ymlWhen at least one parameter is given, the operation is invoked via POST with a FHIR Parameters body, because the parameters input of $evaluate-measure cannot be transmitted as a GET query parameter.
Instead of a measure file, an existing Measure on the server can be evaluated. In that case no resources are created. The Measure is referenced either by its canonical URL with the --measure-url flag:
blazectl evaluate-measure --server "http://localhost:8080/fhir" \
--measure-url "https://example.com/fhir/Measure/example"or by its resource ID with the --measure-id flag:
blazectl evaluate-measure --server "http://localhost:8080/fhir" \
--measure-id DACG22F3LKPU7ZZ5The measure file argument and the --measure-url and --measure-id flags are mutually exclusive. The --parameter flag works the same for existing measures.
More comprehensive documentation can be found in the Blaze CQL Queries Documentation.
Renders a FHIR MeasureReport resource as simple, standalone HTML file. The idea is to combine two blazectl calls, first the evaluate-measure call and second the render-report call.
blazectl evaluate-measure --server "http://localhost:8080/fhir" query.yml | blazectl render-report > query.htmlThe disk-perf command runs the $disk-perf operation that measures the performance of the disk underlying one of Blaze's database directory volumes: index (default), transaction or resource. The benchmark parameters can be tuned with the --file-size, --phase-duration and --concurrency flags. Parameters not given on the command line are left to their server-side defaults.
The command first checks the CapabilityStatement of the server to verify that the server software is Blaze and that the $disk-perf operation is available, so it fails with a helpful error message instead of an obscure HTTP error otherwise. The operation is available from Blaze version 1.11.0 on and only if the admin API is enabled by setting the environment variable ENABLE_ADMIN_API to true.
blazectl disk-perf index --server "http://localhost:8080/fhir"Seq. Write Throughput 828.00 MiB/s
Read IOPS 85000/s
Read Throughput 332.00 MiB/s
Read Latency (p50) 210 µs
Read Latency (p95) 350 µs
Read Latency (p99) 500 µs
Read Latency (max) 1200 µs
Fsync Rate 520/s
Fsync Latency (p50) 1100 µs
Fsync Latency (p95) 1500 µs
Fsync Latency (p99) 1900 µs
Direct I/O yes
Score 87.5
Rating good
Processing Duration 65.2 s
With -o json the raw FHIR Parameters resource returned by the server is printed instead:
blazectl disk-perf index --server "http://localhost:8080/fhir" -o jsonTo ensure trust and security in the software supply chain, GitHub attestations are available for all blazectl binaries. To verify the attestations, please install the GitHub CLI tool and run:
gh attestation verify --repo samply/blazectl blazectlThe install.sh script already verifies the attestations.
The SBOM can be generated by the GitHub CLI:
gh attestation verify --repo samply/blazectl blazectl --predicate-type "https://spdx.dev/Document/v2.3" --format json --jq '.[].verificationResult.statement.predicate' > blazectl-sbom.jsonThe resulting SBOM can be viewed at a Web Viewer provided by SUSE.
- VonkLoader - can also upload transaction bundles but needs .NET SDK
- Synthea Uploader - no parallel uploads
Copyright 2019 - 2025 The Samply Community
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.