Skip to content

Add documentation for mapping ViewDefinitions to a relational database #1294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for mapping ViewDefinitions to a relational database #1294

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 41 additions & 15 deletions doc/docs/concepts/views.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,20 +36,18 @@ for common FHIR resources are provided. These can be modified or extended.

The currently supported list (as of July, 2024) are:

```
Condition
DiagnosticReport
Encounter
Immunization
Location
Medicationrequest
Observation
Organization
Patient
Practitioner
PractitionerRole
Procedure
```
- Condition
- DiagnosticReport
- Encounter
- Immunization
- Location
- Medicationrequest
- Observation
- Organization
- Patient
- Practitioner
- PractitionerRole
- Procedure

### SQL virtual views

Expand Down Expand Up @@ -212,4 +210,32 @@ is set.

The resulting Parquet files can be easily loaded into any Parquet-aware query
engine. Examples include [SparkSQL](https://spark.apache.org/sql/)
or [duckdb](https://duckdb.org/)
or [duckdb](https://duckdb.org/)

## Mapping ViewDefinitions to a Relational Database

### Introduction

ViewDefinitions allow you to define custom schemas for FHIR resources, which can then be materialized into relational database tables. This feature is useful for transforming nested FHIR data into flat, queryable tables.

### Configuration

To map ViewDefinitions to a relational database, you need to configure the pipeline appropriately.

1. **Set the `viewDefinitionsDir`**: This directory should contain the JSON files defining your ViewDefinitions.
2. **Set the `sinkDbConfigPath`**: This configuration file should contain the database connection details.

Example configuration in `pipelines/controller/config/application.yaml`:
```yaml
# The location from which ViewDefinition resources are read and applied to the
# corresponding input FHIR resources. Any file in this directory that ends
# `.json` is assumed to be a single ViewDefinition. To output these views to a
# relational database, the next sinkDbConfigPath should also be set.
viewDefinitionsDir: "config/views"

# The configuration file for the sink database. If `viewDefinitionsDir` is set
# then the generated views are materialized and written to this DB. If not,
# then the raw FHIR JSON resources are written to this DB. Note enabling this
# feature can have a noticeable impact on pipelines performance. The default
# empty string disables this feature.
sinkDbConfigPath: "config/hapi-postgres-config_local_views.json"