Skip to main content

Searching Resources

Searching for resources allows you to read resources based on a specified criteria.

To perform a basic search, you can call the search method along with the criteria by which you want to search. This method will return a Bundle resource containing the search results.

const observationsBundle: r4.Bundle = 
    await plasma.search("Observation", { patient: patientId, category: "laboratory" });

Note that it's possible to use _include to include other resources in your query. The Bundle will contain all of those resources.

const bundle: r4.Bundle = 
    await plasma.searchPatientResourceRaw(patientId, "Observation", { 
        category: "laboratory", 
        _include: "Observation:specimen" 
})

Basic Search (Filtered)​

For convenience, you can use the searchResource method to perform a search and return an array of the requested resources (rather than a Bundle). You should only use this method if you are not _include'ing any other resources in your query.

const observations: r4.Observation[] = 
    await plasma.searchResource<r4.Observation>("Observation", { 
        patient: patientId,
        category: "laboratory"
});

Search Parameters​

The search criteria that are allowed for each resource can be defined by the FHIR server for which you are working and may differ from server to server. However, a good starting place is to find the resource on the official FHIR site and scroll to the "Search Parameters" section. This section will identify the search options for this resource along with instructions on how to use them.

Here is an example for the Observation resource: https://build.fhir.org/observation.html

You can also use the FHIRServerUtils to discover information about the FHIR server you are working with.

Searching Patient Resources​

To search resources that are specific to patients (AllergyIntolerance, Immunization, etc.), you can use the shortcut readPatientResource API as shown below.

const patObservations: r4.Observation[] = 
    await plasma.searchPatientResource<r4.Observation>(patientId, "Observation", { 
        category: "laboratory" 
});

Search Resources By Id​

If you know the Id of a resource, it is recommended that you use the methods from the "Reading Resources" section. However, you can accomplish this with a search by passing in the Id as one of the search parameters. Note that the return type will still be an array.

const observation: r4.Observation[] = 
    await plasma.searchResource<r4.Observation>("Observation", { 
        _id: observationId
});

Searching Binary Resources (and Mixed Resource Types)​

For binary objects, you must use the search method. This method will return a Bundle containing the results.

You can also use this method for non-binary resources if you prefer to have the results as a Bundle. This would be useful in cases where you use an _include search parameter and don't want to have the results filtered to just the resource type that you are searching.

const bundle: r4.Bundle = 
    await plasma.searchPatientResourceRaw(patientId, "Observation", { 
        category: "laboratory", 
        _include: "Observation:specimen" 
})

Resource-Specific Methods​

The Plasma FHIR Client provides a handful of shortcut methods for searching resources of a certain kind. For example, when reading Observation resources that are categorized as laboratory, you can use the shortcut method readLabs as shown below. This is equivalent to searching for Observation resources and supplying the { category: "laboratory" } search parameter.

const labs: r4.Observation[] = await plasma.readLabs(patientId);
const vitals: r4.Observation[] = await plasma.readVitals(patientId);
const smokingStatus: r4.Observation[] = await plasma.readSmokingStatus(patientId);

Duplicate Search Parameters​

Occassionally, you may need to use the same search parameter multiple times in a single search. For example, you may want to use _include multiple times. In this case, you can provide an array of values for that parameter. In the example below, we are searching for Observations and including both the subject and the encounter.

Note that since we are getting a variety of resource types (in other words, not just Observation resources), we will use search and receive a Bundle as our response.

const bundle: r4.Bundle = 
    await plasma.search(patientId, "Observation", { 
        patient: patientId,
        category: "laboratory",
        _include: ["subject", "encounter"]
});