FHIR search

Aidbox supports FHIR Search API .
The FHIR Search API is the primary mechanism for finding FHIR resources by conditions.
A base search request is composed of a list of pairs <parameter>=<value>:

GET /fhir/[resourceType]?param1=value2&param2=value2&...

For example, to search for a Patient resource with the name "John" and a birthdate of "1900-01-01", the request would look like this:

GET /fhir/Patient?name=John&birthdate=1900-01-01

Search capabilities

FHIR Search API supports various search features to help retrieve exactly the data you need. Here are some of the most commonly used capabilities.

Search results

Search results are returned as a FHIR Bundle resource of type "searchset". The Bundle contains:

• A total count of matching resources
• The matched resources as entries
• Links for pagination (first, previous, next, last pages)
• Additional included/revincluded resources (if requested)

Example response:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 100,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "123",
        "gender": "male"
      }
    }
  ],
  "link": [
    {
      "relation": "self",
      "url": "https://localhost:8080/fhir/Patient?_page=1"
    },
    {
      "relation": "first",
      "url": "https://localhost:8080/fhir/Patient?_page=1" 
    },
    {
      "relation": "next",
      "url": "https://localhost:8080/fhir/Patient?_page=2"
    }
  ]
}

Note: using the X-Original-Uri header allows for complete overwrite of the content of the URL parameter. Aidbox will automatically add a page param to your link, or replace it if it exists. x-original-uri: https://example.com/fhir/Patient?page=4 will produce:

...
link:
  - relation: first
    url: https://example.com/fhir/Patient?page=1
  - relation: self
    url: https://example.com/fhir/Patient?page=4
...

See also:

• _count
• _page
• _total
• _sort

SearchParameter

A SearchParameter is a FHIR resource that defines how to search for data within other FHIR resources.
SearchParameter can be:

• Resource-specific parameters (for example, Patient.name)
• Common underscored parameters across all resources (_id, _sort, _count, _page, _elements, etc.)

See also:

SearchParameter types

Each SearchParameter has a defined type, which determines how it behaves and what kind of values it accepts.

It is important to understand the type of SearchParameter because there are differences in how they are processed. For example, different modifiers are supported, some types support prefixes, some don't, etc.

See also SearchParameter Types.

Modifiers

Modifiers change the behavior of a search parameter to support more specific queries.
For example, searching for patients with the name exactly "Smith", rather than the default partial matching:

GET /fhir/Patient?name:exact=Smith

List of supported modifiers:

Including referenced resources

When searching for resources, you can include referenced resources in the search results using the _include parameter. This reduces the number of API calls needed to fetch related data.

For example, to search for patients and include their referenced practitioners:

GET /fhir/Patient?_include=Patient:practitioner

Reverse include

The _revinclude parameter does the opposite of _include. It returns resources that reference the ones you're querying.

For example, to search for practitioners and include all patients who reference them:

GET /fhir/Practitioner?_revinclude=Patient:practitioner

See also:

Chaining

Chaining allows you to search across references between resources. It’s useful when you need to filter by attributes of related resources.

There are two types of chaining:

• Forward chaining: GET /fhir/Patient?general-practitioner:Practitioner.name=Oz (get patients who have a general practitioner with the name "Oz")
• Reverse chaining: GET /fhir/Practitioner?_has:Patient:general-practitioner.gender=male (get practitioners that are referenced by patients with gender "male")

See also:

Other ways to search

Sometimes FHIR Search API is not enough. For example, there's no way to search using a case-insensitive match without starts-with string type logic (combining token and string types), which is useful to search, say, for domains of emails.

Aidbox has custom APIs to search for resources, which can be used instead of FHIR Search API in corner cases:

• Search resource - use SQL to define where and order-by parts of SQL statements. Combines with other SearchParameters.
• AidboxQuery - use DSL to define search criteria. Does not combine with other SearchParameters.
• Dot expressions - an easy way to search without using SearchParameters at all.

It is also possible to use GraphQL to search for resources.

See also: