Searching for resources
FHIR has extensive support for searching resources through the use of the REST interface. Describing all the possibilities is outside the scope of this document, but much more details can be found online in the specification.
The FHIR client has a few operations to do basic search.
Searching within a specific type of resource
The most basic search is the client’s
Search<T>(string[] criteria = null, string[] includes = null, int? pageSize = null)
function. It searches all resources of a specific type based on zero or
more criteria. Criteria must conform to the parameters as they would be
specified on the search URL in the REST interface, so for example
searching for all patients named ‘Eve’ would look like this
Bundle results = client.Search<Patient>(new string[] { "family:exact=Eve" });
The search will return a Bundle containing entries for each resource
found. It is even possible to leave out all criteria, effectively
resulting in a search that returns all resources of the given type.
Additionally, there is a Search()
overload that does not use the
generic T
argument, you can pass the type of resource as a string in
the first parameter instead.
Searching for a resource with a specific id
In some cases you may already have the id of a specific resource (e.g.
an Observation with logical id 123
, corresponding to the url
Observation/123
). In this case you can use
SearchById<T>(string id, string[] includes = null, int? pageSize = null)
.
Note that this function still returns a Bundle. The operation differs
from a Read<T>()
operation because it can return included
resources as well. E.g. given an id 123
for an Observation, you can
ask a FHIR server to not only look for the indicated Observation but to
return the associated subject
as well:
var incl = new string[] { "Observation.subject" };
Bundle results = client.SearchById<Observation>("123", incl);
System wide search
Some servers allow you to execute searches across all resource types.
This would use FhirClient’s
WholeSystemSearch(string[] criteria = null, string[] includes = null, int? pageSize = null)
.
Doing this search:
Bundle results = client.WholeSystemSearch(new string[] { "name=foo" });
would then not only return Patients with “foo” in their name, but Devices named “foo” as well.
Complex searches
An alternative way to specify a query is by creating a SearchParam
resource and pass this to the client’s Search<TResource>(SearchParam q)
overload. The
SearchParam
resource has a set of fluent calls to allow you to easily
construct more complex queries:
var q = new SearchParams()
.Where("name:exact=ewout")
.OrderBy("birthdate", SortOrder.Descending)
.SummaryOnly().Include("Patient:organization")
.LimitTo(20);
Bundle result = client.Search<Patient>(q);
Note that unlike the search options shown before, you can specify search ordering and the use of a summary result. As well, this syntax avoids the need to create arrays of strings as parameters and tends to be more readable.
Paged Results
Normally, any FHIR server will limit the number of search results returned. In the previous example, we explicitly limited the number of results per page to 20.
The FhirClient has a Continue
function to browse a search result
after the first page has been received using a Search
:
var result = client.Search(q);
while( result != null )
{
// Do something useful
result = client.Continue(result);
}
Note that Continue
supports a second parameter that allows you to
browse forward, backward, or go immediately to the first or last page of
the search result.