Patient Observation Query Builder

Create asynchronous helpers that assemble and execute FHIR queries for Observation and Patient resources using the package's fluent search capabilities.

Capabilities

Retrieve recent observations for a patient

• Given a patient reference, a list of observation codes, a since timestamp, and max_results=10, returns a bundle with at most 10 Observation entries sorted by most recent effective time first. @test
• When summary_only=True, Observation entries only include id, code, subject, effective[x], and value[x] fields while still embedding referenced Patient and Practitioner resources. @test

Find patients by observation criteria

• With an observation code and optional since timestamp, returns Patient resources that have matching Observations through a reverse-chained query instead of client-side filtering. @test
• When include_observations=True, the bundle also contains the matching Observation resources alongside Patients. @test
• When a time filter is present, patient results are ordered by the most recent matching observation. @test
• When filtering by performer organization, only patients with Observations performed by that organization are returned. @test

Implementation

@generates

API

async def fetch_recent_observations(
    client,
    patient_ref: str,
    codes: list[str],
    since: str,
    *,
    max_results: int = 25,
    summary_only: bool = False
) -> dict:
    """
    Return a raw bundle of Observation resources for a patient, limited by code and time,
    sorted newest-first, with related Patient and Practitioner resources included.
    Element selection is applied when summary_only is True.
    """

async def find_patients_by_observation(
    client,
    code: str,
    *,
    since: str | None = None,
    include_observations: bool = False,
    performer_organization: str | None = None
) -> dict:
    """
    Return Patient resources that have matching Observations,
    optionally bundling the related Observations and restricting by performer organization.
    """

Dependencies { .dependencies }

fhirpy { .dependency }

FHIR client toolkit for building and executing FHIR queries.