TypeScript PostgreSQL for openEHR data

July 16, 2026 · 5 min read

Author of ArcEHR

One of the biggest hurdles in healthtech development is the sheer complexity of querying hierarchical clinical schemas. Usually, this means learning complex, niche query languages.

If you are using ArcEHR, you don't need any of that. You can query and insert graph-mapped openEHR data using the standard, vanilla pg library in TypeScript.

Because ArcEHR presents a PostgreSQL-compatible interface over ArcadeDB, your existing database drivers, parameterized queries, and connection pools work out of the box.

Here is how easily you can handle openEHR CRUD operations in TypeScript:

1. The Setup

No custom database clients required. Just import the standard pg driver, initialize your client, and connect.

import { Client } from 'pg'
const client = await new Client({
    database: 'arcehr',
    port: 5432,
    user: 'root',
    password: 'arcadedb'}).connect()

2. Inserting openEHR Data with Type Safety

When inserting openEHR data, you pass your structured JSON payload directly as a parameterized query. A trigger on the create_composition table handles the heavy lifting, automatically shredding the JSON into RM Document types and graph edges.

// Insert a new composition
const content = {
  archetype_node_id: 'openEHR-EHR-COMPOSITION.encounter.v1',
  name: {value: 'Vital Signs'},
  uid: {_type: 'OBJECT_VERSION_ID', value: '8849182c::openEHRSys.example.com::1'},
  archetype_details: {
    archetype_id: {value: 'openEHR-EHR-COMPOSITION.encounter.v1'},
    template_id: {value: 'Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747'},
    rm_version: '1.0.2',
  },
  language: {terminology_id: { value: 'ISO_639-1' }, code_string: 'en'},
  content: [{ _type: 'OBSERVATION' }]
}
const insert = `INSERT INTO create_composition (ehr_id, content) VALUES ($1, $2)`
await client.query(insert, ['ehr-1', content])

The Response: You receive a clean response back, confirming the target EHR and returning the database record ID (@rid):

{
  ehr_id: 'ehr-1',
  content: '{"archetype_node_id":"openEHR-EHR-COMPOSITION.encounter.v1","name":{"value":"Vital Signs"},"uid":{"_type":"OBJECT_VERSION_ID","value":"8849182c::openEHRSys.example.com::1"},"archetype_details":{"archetype_id":{"value":"openEHR-EHR-COMPOSITION.encounter.v1"},"template_id":{"value":"Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747"},"rm_version":"1.0.2"},"language":{"terminology_id":{"value":"ISO_639-1"},"code_string":"en"},"content":[{"_type":"COMPOSITION"}]}',
  prefer: 'return=minimal',
  content_type: null,
  accept: null,
  '@rid': '#72:1'
}

3. Querying openEHR Data (Zero-Join Graph Traversal)

Because ArcEHR stores this data as a graph under the hood, we can traverse nested clinical paths in a single query without performance-killing relational JOINs.

Scenario A: Fetching Blood Pressure

Lets pull all blood pressure records for a specific EHR. Note how we use standard $1 placeholders to prevent SQL injection:

const select = `SELECT $blood_pressure.$event AS blood_pressure
                FROM   EHR
                LET    $blood_pressure = out("openEHR-EHR-OBSERVATION.blood_pressure.v2")
                WHERE  $ehr = $1`
await client.query(select, ['ehr-1'])

Resulting JSON: You get back clean, structured openEHR Reference Model JSON elements directly in your application:

{
  blood_pressure: [[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Systolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":746.5,"units":"mm[Hg]"}},
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0005","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Diastolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":526.1,"units":"mm[Hg]"}}
    ]],[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Systolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":746.5,"units":"mm[Hg]"}},
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0005","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Diastolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":526.1,"units":"mm[Hg]"}}
  ]]]
}

Scenario B: Multi-Archetype Queries with Path Filtering

What if you need to fetch both blood pressure and pulse, but only return records where the patient's vitals exceed specific safety thresholds?

We use the CONTAINS operator to query inside the nested clinical arrays:

const select = `SELECT $blood_pressure.$event AS blood_pressure, $pulse.$event AS pulse
                FROM   EHR
                LET    $blood_pressure = out("openEHR-EHR-OBSERVATION.blood_pressure.v2"),
                       $pulse = out("openEHR-EHR-OBSERVATION.pulse.v2")
                WHERE  $ehr = $1
                  AND  $blood_pressure.$event CONTAINS (
                           archetype_node_id = "at0004" AND -- Systolic
                           value.magnitude > 140 AND value.units = "mm[Hg]")
                  AND  $pulse.$event CONTAINS (
                           archetype_node_id = "at0004" AND -- Rate
                           value.magnitude > 80 AND value.units = "/min")`
await client.query(select, ['ehr-1'])

Result:

{
  blood_pressure: [[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Systolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":746.5,"units":"mm[Hg]"}},
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0005","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Diastolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":526.1,"units":"mm[Hg]"}}
    ]],[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Systolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":746.5,"units":"mm[Hg]"}},
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0005","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Diastolic"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":526.1,"units":"mm[Hg]"}}
  ]]],
  pulse: [[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Rate"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":636.7,"units":"/min"}}
    ]],[[
        {"@type":"ELEMENT","_type":"ELEMENT","archetype_node_id":"at0004","name":{"@type":"DV_TEXT","_type":"DV_TEXT","value":"Rate"},"value":{"@type":"DV_QUANTITY","_type":"DV_QUANTITY","magnitude":636.7,"units":"/min"}}
  ]]]
}

No database schema migrations, no nested relational mapping code, and no performance loss. Just standard PostgreSQL queries executing lightning-fast graph traversals in Node.js.

The Takeaway

When building modern clinical applications, you shouldn't have to compromise between the rich standards of openEHR and developer-friendly tooling. ArcEHR lets you use the standard Node/TypeScript ecosystem you already know and love to query complex health data seamlessly.

1. The Setup​

2. Inserting openEHR Data with Type Safety​

3. Querying openEHR Data (Zero-Join Graph Traversal)​

Scenario A: Fetching Blood Pressure​

Scenario B: Multi-Archetype Queries with Path Filtering​

The Takeaway​