Quickstart

After installing, you need a ViewDefinition. Save this as patient_view.json:

{
  "resourceType": "ViewDefinition",
  "name": "patient_names",
  "resource": "Patient",
  "select": [
    {
      "column": [
        { "name": "id", "path": "id" },
        { "name": "gender", "path": "gender" },
        { "name": "family", "path": "name.first().family" }
      ]
    }
  ]
}

Run a view over FHIR data — no database

Point run at a ViewDefinition and some resources (--input takes an NDJSON file, a Bundle, a JSON resource/array, a directory, or - for stdin):

octofhir-sof run patient_view.json --input patients.ndjson

id,gender,family
pt-1,female,Chalmers
pt-2,male,Levin

Choose the output format with --output csv|ndjson|json (parquet with the Parquet feature). Streaming NDJSON in and NDJSON out runs in bounded memory:

cat export/*.ndjson | octofhir-sof run patient_view.json --input - --output ndjson

Run every view in a directory in one pass, one output file per view:

octofhir-sof run views/ --input data/ --output csv --out out/

Generate SQL

generate emits a PostgreSQL JSONB SELECT by default, or DuckDB JSON with --dialect duckdb:

octofhir-sof generate patient_view.json                  # PostgreSQL
octofhir-sof generate patient_view.json --dialect duckdb # DuckDB

Or a CREATE TABLE for the view’s columns (--ddl, dialect ansi | postgres | duckdb):

octofhir-sof generate patient_view.json --ddl --dialect postgres

See SQL dialects for the differences.

Validate (offline, no package)

validate checks the ViewDefinition’s structure against the spec — SQL-safe names, one iteration construct per select, unique column names, consistent unionAll branches:

octofhir-sof validate patient_view.json
octofhir-sof validate patient_view.json --sarif > results.sarif

Lint

Schema-driven linting checks selectors against a FHIR package; --shareable checks the portable FHIRPath subset (offline, no package needed):

octofhir-sof lint patient_view.json --package hl7.fhir.r4.core
octofhir-sof lint patient_view.json --shareable

Browse every rule in the rule reference, or read the linting guide.

Exit codes

0 on success · 1 on validation errors, lint errors, test failures, or I/O errors.