Command-Line Interface

Command-line interface reference.

This page contains usage instructions for all of the Fhirbase CLI commands. Same information is available in terminal with fhirbase help <subcommand>.

fhirbase init

fhirbase --fhir=[FHIR version] [postgres connection options] init

Creates SQL schema (tables, types and stored procedures) to store resources from FHIR version specified with --fhir flag. Database where schema will be created is specified with --db flag. Specified database should be empty, otherwise command may fail with an SQL error.

fhirbase load

fhirbase load [options] [BULK DATA URL or FILE PATH(s)]

Load command loads FHIR resources from named source(s) into the Fhirbase database.

You can provide either single Bulk Data URL or several file paths as an input.

Fhirbase can read from following file types:

• NDJSON files

• transaction or collection FHIR Bundles

• regular JSON files containing single FHIR resource

Also Fhirbase can read gziped files, so all of the supported file formats can be additionally gziped.

You are allowed to mix different file formats and gziped/non-gziped files in a single command input, i.e.:

fhirbase load *.ndjson.gzip patient-john-doe.json my-tx-bundle.json

Fhirbase automatically detects gzip compression and format of the input file, so you don't have to provide any additional hints. Even file name extensions can be ommited, because Fhirbase analyzes file content, not the file name.

If Bulk Data URL was provided, Fhirbase will download NDJSON files first (see the help for "bulkget" command) and then load them as a regular local files. Load command accepts all the command-line flags accepted by bulkget command.

Fhirbase reads input files sequentially, reading single resource at a time. And because of PostgreSQL traits it's important if Fhirbase gets a long enough series of resources of the same type from the provided input, or it gets resource of a different type on every next read. We will call those two types of inputs "grouped" and "non-grouped", respectively. Good example of grouped input is NDJSON files produced by Bulk Data API server. A set of JSON files from FHIR distribution's "examples" directory is an example of non-grouped input. Because Fhirbase reads resources one by one and do not load the whole file, it cannot know if you provided grouped or non-grouped input.

Fhirbase supports two modes (or methods) to put resources into the database: "insert" and "copy". Insert mode uses INSERT statements and copy mode uses COPY FROM STDIN. By default, Fhirbase uses insert mode for local files and copy mode for Bulk Data API loads.

It does not matter for insert mode if your input is grouped or not. It will perform with same speed on both. Use it when you're not sure what type of input you have. Also insert mode is useful when you have duplicate IDs in your source files (rare case but happened couple of times). Insert mode will ignore duplicates and will persist only the first occurrence of a specific resource instance, ignoring other occurrences.

Copy mode is intended to be used only with grouped inputs. When applied to grouped inputs, it's almost 3 times faster than insert mode. But it's same slower if it's being applied to non-grouped input.

fhirbase bulkget

fhirbase bulkget [--numdl=10] http://some-fhir-server.com/fhir/Patient/$everything /output/dir/

Downloads FHIR data from Bulk Data API endpoint and saves results into specific directory on a local filesystem.

NDJSON files generated by remote server will be downloaded in parallel and you can specify number of threads with --numdl flag.

To mitigate differences between Bulk Data API implementations, there is an --accept-header option which sets the value for "Accept" header. Most likely you won't need to set it, but if Bulk Data server rejects queries because of "Accept" header value, consider explicitly set it to something it expects.