Searching & Filtering

Most FHIR resources in the Health Gorilla API support search operations using query parameters. This allows clients to retrieve only the relevant subset of records for a specific patient or clinical context.

A FHIR search is typically performed using the pattern: GET /[ResourceType]?[parameter]=[value]

For example, the query GET /Observation?patient=123456&code=8310-5
returns observation records for patient 123456 where the LOINC code corresponds to body temperature.

Scoping a Search to a Patient

Most clinical resource searches are patient scoped, and the patient parameter is what scopes them. Supplying it keeps data isolated and returns only those resources linked to the patient you name. Some resources, including DiagnosticReport and DocumentReference, accept patient as optional rather than requiring it, so check the resource's own reference page before you omit it.

Common Parameter Types

The following parameter types cover most searches:

Numeric value search isn't supported. You can't filter observations by a result threshold, for example.

Date Prefixes

Date parameters support prefixes for range-based filtering:

If you don't specify a prefix, FHIR treats the date as eq by default. Those five are the supported set on DiagnosticReport, Encounter, and Observation, where ne, sa, eb, and ap return HTTP 400.

DocumentReference behaves differently. It rejects only ap. It accepts ne, sa, and eb, but reinterprets them as eq, ge, and le rather than applying the prefix you asked for. Avoid those three on DocumentReference, because the result won't match what the prefix implies.

Prefixes control how a date value is compared. They don't control which underlying field the comparison targets. For that, along with the difference between filtering on the clinical event date and filtering on the timestamp the resource was last modified in the FHIR server, go to Date Filtering.

Multiple Values

To match any one of several values, a logical OR, separate them with commas in a single parameter: GET /Condition?code=12345,67890

Repeating the same parameter returns HTTP 400. That differs from the base FHIR convention, where repeating a parameter combines the values as a logical AND, so a two-sided range written as two date values fails on most resources here. To require several conditions at once, combine different parameters.

Two exceptions accept repetition: date on DocumentReference, which is how you express a two-sided range there, and the _tag and _security metadata parameters.

Modifier Support

Some parameters support modifiers that change how values are interpreted:

Modifiers apply to string parameters such as name. Coded parameters such as code and status match on the coded value itself.

The :not modifier isn't supported. To exclude a value, filter the results in your own system after retrieval.

Combining Parameters

All parameters in a query are combined using a logical AND, for example: GET /Observation?patient=12345&code=8310-5&date=eq2023-01-01. This returns observations that match all three criteria.

Best Practices

The following guidelines keep searches efficient and predictable:

• Include patient in patient-scoped queries.
• Use coded values such as status, code, and category whenever possible.
• Use date ranges rather than exact dates to avoid missing records.
• Expect any large result set to be paginated, whatever its scope, and follow the supplied next link to retrieve the rest.
• Narrow broad queries with the other parameters the resource supports.