Skip to main content

config

Config for the EHR query step (v1).

Classes​

EHRQueryConfig​

class EHRQueryConfig(**data: Any):

Config for the EHR criteria query step.

mode selects how patients are identified:

"filename" The default. Patients are resolved from imaging file metadata (name + DOB columns on the datasource). Requires datasource and filenames on the task call.

"patient_id_cache" Patients are resolved by ID from a cache accessor wired in via the step's inputs: block (typically ehr_patient_lister.cache). datasource and filenames are not consulted. Records are stored without imaging file IDs or per-scan metadata.

fetch_appointments adds three per-patient EHR calls (previous appointments, previous encounters, next appointment). It is off by default because those calls cost a round-trip each and only the appointment-history criteria consume them. When off, the corresponding cache columns are left NULL, which downstream criteria read as UNKNOWN rather than as a failure.

observation_codes/observation_categories fetch coded Observations (labs/measurements) — unlike conditions/procedures, Observation searches require an explicit code or category parameter on at least one major FHIR backend (Epic's Observation.Search rejects a bare patient-only query — error 59108, "either the category or code parameter must be specified"). observation_codes is precise (e.g. LOINC-coded albumin); observation_categories is a coarser net over the core FHIR observation-category values (e.g. "laboratory", "vital-signs") — Epic's own docs note category assignment is "subjective and may differ across organizations" and recommend code search when consistency matters. Both may be set together; results are merged and deduplicated (as two separate searches — at least one backend rejects a query with both code and category set, so they are never combined into one).

Default, when neither is set (both left None): ehr_criteria_query_task fetches every core FHIR observation-category (ALL_OBSERVATION_CATEGORIES — social history, vital signs, imaging, laboratory, procedure, survey, exam, therapy, activity), so a criteria-tree CodeCriterion referencing any observation code has a chance of finding data without the flow author having to enumerate codes/categories up front. Setting observation_codes (with observation_categories left None) opts out of that wide default in favour of a precise, narrower fetch; setting observation_categories explicitly is respected as-is, not widened back to "all" — this includes setting it to [], which deliberately fetches no categories at all (a full opt-out of category search, distinct from leaving it None). Likewise, an explicit observation_codes: [] opts out of code search without re-triggering the wide category default. The distinction is None (unset) vs. any list including [] (an explicit, respected choice) — never emptiness. The corresponding cache column is NULL only if the fetch itself fails or genuinely finds nothing, which downstream criteria read as UNKNOWN.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors​

Variables​

  • static fetch_appointments : bool
  • static mode : Literal['filename', 'patient_id_cache']
  • static model_config
  • static observation_categories : Optional[list[str]]

Methods​

fetch_options​

def fetch_options(self) ‑> EHRFetchOptions:

Resolve this config into the fetch scope every lookup is asked for.

A method rather than a helper in ehr_query/functions.py, so that every version of the step resolves the defaults documented above identically: functions.py cannot import this module (its own package imports functions, so the two would form an import cycle), and duplicating the resolution per version would let the versions drift apart on what an unset field means.

Both observation fields are read with is not None rather than for truthiness, so an explicitly empty list — a deliberate opt-out of that search — is honoured instead of falling through to the wide default.

Returns The EHRFetchOptions to pass to the EHR resource for every patient in the run.

ObservationCode​

class ObservationCode(**data: Any):

A single Observation code to fetch, e.g. a LOINC lab code.

Arguments

  • code_system: Short system name ("loinc", "snomed", "icd10", "cpt4"), matching CODE_SYSTEM_TO_IDENTIFIER's keys. None matches the code value across any system.
  • code: The code value to search for (e.g. "1751-7").

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Variables​

  • static code : str
  • static code_system : str | None
  • static model_config