Skip to main content

Advanced Search Parameters

The FHIR search framework allows for special search parameters that enable more complex searches to fine-tune your results. In this document, we will go over the following special parameters:

_id​

The _id parameter allows you to search for any resource based on its id element. It is also the only way to search using multiple ids in FHIR. To do so, just enter the ids as a comma separated list.

Example: Searching for patients by _id
await medplum.searchResources('Patient', {
  _id: 'homer-simpson,marge-simpson,lisa-simpson',
});

_lastUpdated​

The _lastUpdated parameter allows you to search for resources based on when they were most recently changed.

This is especially useful when combined with comparison operators, such as gt (greater than) or lt (less than) to find resources that have or have not been changed since a certain time or date.

Example: Searching for only communications that have occurred since the beginning of October, 2023
await medplum.searchResources('Communication', {
  _lastUpdated: 'gt2023-10-01',
});

_summary​

The _summary parameter allows you to return only a portion of a resource's elements. Its primary intent is to optimize your queries by fetching only essential information. It is particularly useful when searching for large resources such as those with images or repeating elements.

The _summary parameter can contain one of the following value set:

ValueDescription
trueOnly returns elements that are marked as summary in the resource definition.
countReturns the count of matching resources, but none of the actual resource details for those matches.
Example: Searching for a summary of a patient
await medplum.searchResources('Patient', {
  _id: 'homer-simpson',
  _summary: true,
});

/* 
Example response: 
{
  resourceType: 'Patient',
  identifier: [
    {
      use: 'official',
      system: 'https://example-hospital.org',
      value: 'patient-1',
    },
  ],
  active: true,
  name: [
    {
      family: 'Simpson',
      given: ['Homer', 'Jay'],
    },
  ],
  gender: 'male',
  birthDate: '1956-05-12',
  deceasedBoolean: false,
  address: [
    {
      use: 'home',
      type: 'physical',
      line: ['742 Evergreen Terrace'],
      city: 'Springfield',
    },
  ],
  managingOrganization: {
    reference: 'Organization/example-hospital',
  },
  link: [
    {
      type: 'refer',
    },
  ],
};
*/

_elements​

The _elements parameter is similar to _summary in that it allows you to return only a subset of the resource's elements. However, rather than a predefined value set, _elements allows you to choose which fields you would like to return.

The fields you choose should be formatted as a comma separated list of base elements for a given resource.

Note that any top-level mandatory or modifier elements should always be included in the chosen list of elements.

Example: Searching the subject and performers of observations
await medplum.searchResources('Observation', {
  _elements: 'status,code,subject,performer',
});
/* 
Example Response: 
[
  {
    resourceType: 'Observation',
    status: 'final',
    code: {
      coding: [
        {
          system: 'http://loinc.org',
          code: '8867-4',
          display: 'Heart Rate',
        },
      ],
    },
    subject: {
      reference: 'Patient/homer-simpson',
    },
    performer: [
      {
        reference: 'Practitioner/dr-alice-smith',
      },
    ],
  },
  {
    resourceType: 'Observation',
    status: 'preliminary',
    code: {
      coding: [
        {
          system: 'http://loinc.org',
          code: '8310-5',
          display: 'Body temperature',
        },
      ],
    },
    subject: {
      reference: 'Patient/marge-simpson',
    },
    performer: [
      {
        reference: 'Practitioner/dr-gregory-house',
      },
    ],
  },
];
*/

_tag​

The _tag parameter allows you to search on the tag field of the meta element of the resource you are searching for. The tag field contains user-defined tags to categorize the resource.

Example: Searching for observations that are tagged as critical
await medplum.searchResources('Observation', {
  _tag: 'https://example.org/tags|critical',
});

_compartment​

A compartment is a grouping of resources which share a common relation. For example, each Patient resource has its own compartment. A Patient compartment includes any resources which reference that Patient, usually in the subject field.

Medplum allows you to easily search using compartments by providing the non-standard _compartment parameter. This enables you to find all resources of a given type that are associated with a certain compartment.

Example: Find all communications for a patient
await medplum.searchResources('Communication', {
  _compartment: 'Patient/homer-simpson',
});

_total​

The _total parameter allows you to return the total count of matching resources in your search response. For more details see the Paginated Search docs.

Example: Search for all patients in your organization and get an estimate of the total number
await medplum.search('Patient', {
  _total: 'estimate',
});

_profile​

FHIR allows profiling to create custom data structures that specify how resources can be sub-specialized to meet specific use cases. The _profile parameter allows you to search based on these profiles.

The _profile parameter is a reference parameter, meaning you may provide a reference as an argument to the parameter. See the FHIR Profiles doc to learn more about profiling.

Example: Search for observations that are part of the pediatric growth charts profile
await medplum.searchResources('Observation', {
  _profile: 'https://example.org/StructureDefinition/pediatric-growth-chart',
});

_filter​

The _filter parameter can be used to filter for more complex queries. For more details see the _filter Search Parameter docs.

_sort​

The _sort parameter allows you to sort the results of your search based on different parameters. For details on how to use the _sort parameter, see the Sorting the Results docs.