Searching

Search Using the Models

Associate the client with the model:

FHIR::Model.client = client

The FHIR models can now be used to directly interact with a FHIR server.

# search patients
results = FHIR::Patient.search(given: 'John', family: 'Doe')
results.count # results in an enumeration

Search Using the Client

There are several search methods built into the client. The most simple example is the "search" involving no parameters.

client.read_feed(klass, format = nil)

In this case klass is the class representing the FHIR resource type to search, e.g. FHIR::Patient or FHIR::Observation, and format is one of four options:

• FHIR::Formats::ResourceFormat::RESOURCE_XML
• FHIR::Formats::ResourceFormat::RESOURCE_JSON
• FHIR::Formats::ResourceFormat::RESOURCE_XML_DSTU2
• FHIR::Formats::ResourceFormat::RESOURCE_JSON_DSTU2

Examples:

# using the current default format
reply = client.read_feed(FHIR::Patient)
bundle = reply.resource

# overriding the default format to use XML
reply = client.read_feed(FHIR::Observation, FHIR::Formats::ResourceFormat::RESOURCE_XML)
# print the raw XML of the Bundle
puts reply.body
# use the search result bundle (inflated from the raw XML)
bundle = reply.resource

Automatically Paginating Search Results

Assuming read permissions exist on the resource type, a search result will be returned as a FHIR::Bundle and the resulting entries can be iterated over using the FHIR::Bundle method each.

reply = client.read_feed(FHIR::Patient) # fetch Bundle of Patients
bundle = reply.resource
bundle.each do |resource|
  puts resource.name[0].text
end
puts reply.code # HTTP 200 (or whatever was returned)
puts reply.body # Raw XML or JSON

Assuming read permissions exist on the resource type, a search result will be returned as a FHIR::Bundle which can be paginated. The FHIR::Bundle instance method each illustrated above, not only iterates through the Bundle entry array, but it will also fetch the next page of results assuming the Bundle contains a "next" link.

Manually Paginating Search Results

As explained above, using the FHIR::Bundle.each instance method will iterate and paginate results, but if you want to paginate manually, you can do so using the FHIR::Bundle.next_bundle method or the FHIR::Client.next_page method.

# next_bundle example
reply = client.read_feed(FHIR::Patient) # fetch Bundle of Patients
bundle = reply.resource
another_bundle = bundle.next_bundle

# next_page example
reply = client.read_feed(FHIR::Patient) # fetch Bundle of Patients
bundle = reply.resource
another_reply = client.next_page(reply)

# next_page in a different direction (FOWARD, BACKWARD, FIRST, or LAST)
reply = client.read_feed(FHIR::Patient) # fetch Bundle of Patients
bundle = reply.resource
another_reply = client.next_page(reply, FHIR::Sections::Feed::BACKWARD)

Searching with Parameters

The default search method has the following signature:

def search(klass, options = {}, format = @default_format)

• klass - the FHIR resource class to search, e.g. FHIR::Patient.
• options - a Hash of search options described below.

options = {
  :resource => klass,
  :format => format,
  :id => 123, # only use if you are searching by compartment
  :search => {
    :flag => false, # :flag is optional. Search by POST when true, otherwise GET.
    :compartment => 'CompartmentName', # optional searching by compartment
    :parameters => {
      # list of key/value pairs go here
    }
  }
}

Search By Parameter

The name parameter in the following example can be substituted for any combination of parameters as described in http://hl7.org/fhir/R4/search.html including dates, numbers, chaining, and so forth.

# GET [base]/Patient?name=Peter
reply = client.search(FHIR::Patient, search: { parameters: { name: 'Peter' } })
bundle = reply.resource
patient = bundle.entry.first.resource

Search By Compartment

# GET [base]/Patient/123/Condition?code:in=http://hspc.org/ValueSet/acute-concerns
reply = client.search(FHIR::Patient, { id: 123,
                      search: {
                        compartment: 'Condition',
                        parameters: { 'code:in': 'http://hspc.org/ValueSet/acute-concerns' }
                      }})
bundle = reply.resource

Search By URL Encoded POST

# POST [base]/Patient/_search?name=Peter
reply = client.search(FHIR::Patient, search: { flag: true, parameters: { name: 'Peter' } })
bundle = reply.resource
patient = bundle.entry.first.resource

Searching with AND, OR, and Composite Values

Composite value searching is described in http://hl7.org/fhir/R4/search.html#combining

# AND: /Patient?language=FR&language=NL
client.search(FHIR::Patient, search: { parameters: { language: [ 'FR', 'NL' ] } } )

# OR: /Patient?language=FR,NL
client.search(FHIR::Patient, search: { parameters: { language: 'FR,NL' } })

# COMPOSITE: /Group?characteristic-value=gender$mixed
client.search(FHIR::Group, search: { parameters: { 'characteristic-value': 'gender$mixed' } })