fhir_search {fhircrackr}

Download FHIR search result

Description

Downloads all FHIR bundles of a FHIR search request from a FHIR server by iterating through the bundles. Search via GET and POST is possible, see Details.

Usage

fhir_search(
  request = fhir_current_request(),
  body = NULL,
  username = NULL,
  password = NULL,
  token = NULL,
  add_headers = NULL,
  max_bundles = Inf,
  verbose = 1,
  delay_between_attempts = c(1, 3, 9, 27, 81),
  log_errors = NULL,
  save_to_disc = NULL,
  delay_between_bundles = 0,
  rm_tag = "div",
  max_attempts = deprecated()
)

Arguments

request

An object of class fhir_url or a character vector of length one containing the full FHIR search request. It is recommended to explicitly create the request via fhir_url() as this will do some validity checks and format the url properly. Defaults to fhir_current_request()

body

A character vector of length one or object of class fhir_body with type "application/x-www-form-urlencoded". A body should be provided when the FHIR search request is too long and might exceed the maximal allowed length of the URL when send to the server. In this case a search via POST (see https://www.hl7.org/fhir/search.html#Introduction) can be used. The body should contain all the parameters that follow after the ⁠?⁠ in the FHIR search request. When a body is provided, the required ⁠_search⁠ is automatically added to the url in request. See examples and ?fhir_body.

username

A character vector of length one containing the username for basic authentication.

password

A character vector of length one containing the password for basic authentication.

token

A character vector of length one or object of class httr::Token, for bearer token authentication (e.g. OAuth2). See fhir_authenticate() for how to create this.

add_headers

A named character vector of custom headers to add to the HTTP request, e.g. c(myHeader = "somevalue") or c(firstHeader = "value1", secondHeader = "value2").

max_bundles

Maximal number of bundles to get. Defaults to Inf meaning all available bundles are downloaded.

verbose

An integer vector of length one. If 0, nothing is printed, if 1, only finishing message is printed, if > 1, downloading progress will be printed. Defaults to 1.

delay_between_attempts

A numeric vector specifying the delay in seconds between attempts of reaching the server that fhir_search() will make. The length of this vector determines the number of attempts that will be made before stopping with an error. Defaults to c(1,3,9,27,81).

log_errors

Either NULL or a character vector of length one indicating the name of a file in which to save the http errors. NULL means no error logging. When a file name is provided, the errors are saved in the specified file. Defaults to NULL. Regardless of the value of log_errors the most recent http error message within the current R session is saved internally and can be accessed with fhir_recent_http_error().

save_to_disc

Either NULL or a character vector of length one indicating the name of a directory in which to save the bundles. If a directory name is provided, the bundles are saved as numerated xml-files into the directory specified and not returned as a bundle list in the R session. This is useful when a lot of bundles are to be downloaded and keeping them all in one R session might overburden working memory. When the download is complete, the bundles can be loaded into R using fhir_load(). Defaults to NULL, i.e. bundles are returned as a list within the R session.

delay_between_bundles

A numeric scalar specifying a time in seconds to wait between pages of the search result, i.e. between downloading the current bundle and the next bundle. This can be used to avoid choking a weak server with too many requests to quickly. Defaults to zero.

rm_tag

Character vector of length 1 defining an xml tag of elements that will removed from the bundle automatically. Defaults to "div",leading to the removal of all html parts (see Details). Set to NULL to keep the bundles untouched. See fhir_rm_div() and fhir_rm_tag() for more info.

max_attempts

The number of maximal attempts is now determined by the length of delay_between_attempts

Details

Request type

fhir_search allows for two types of search request:

1. FHIR search via GET: This is the more common approach. All information on which resources to download is contained in the URL that is send to the server (request argument). This encompasses the base url of the server, the resource type and possible search parameters to further qualify the search (see fhir_url()). The search via GET is the default and performed whenever the argument body is NULL.

2. FHIR search via POST: This option should only be used when the parameters make the search URL so long the server might deny it because it exceeds the allowed length. In this case the search parameters (everything that would usually follow the resource type after the ⁠?⁠) can be transferred to a body of type "application/x-www-form-urlencoded" and send via POST. If you provide a body in fhir_search(), the url in request should only contain the base URL and the resource type. The function will automatically amend it with ⁠_search⁠ and perform a POST.

Authentication

There are several ways of authentication implemented in fhir_search(). If you don't need any authentication, just leave the arguments described in the following at their default values of NULL.

1. Basic Authentication: Provide the username and the password for basic authentication in the respective arguments.

2. Token Authentication: Provide a token in the argument token, either as a character vector of length one or as as an object of class httr::Token. You can use the function fhir_authenticate() to create this object.

Additional headers

Per default, the underlying HTTP requests are equipped with Accept and Authorization headers. If you need to pass additional headers, e.g. cookies for authentication or other custom headers, you can add these to the request as a named character vector using the add_headers argument.

HTML removal

FHIR resources can contain a considerable amount of html code (e.g. in a narrative object), which is often created by the server for example to provide a human-readable summary of the resource. This data is usually not the aim of structured statistical analysis, so in the default setting fhir_search() will remove the html parts immediately after download to reduce memory usage (on a hapi server typically by around 30%, see fhir_rm_div()). The memory gain is payed with a runtime increase of 10%-20%. The html removal can be disabled by setting rm_tag = NULL to increase speed at the cost of increased memory usage.

Value

A fhir_bundle_list when save_to_disc = NULL (the default), else NULL.

See Also

• Creating a FHIR search request: fhir_url() and fhir_body() (for POST based search)

• OAuth2 Authentication: fhir_authenticate()

• Saving/reading bundles from disc: fhir_save() and fhir_load()

• Flattening the bundles: fhir_crack()

Examples

#the try({}, silent = TRUE) statement is only there to catch errors when the server is down
#you can skip it when the server is reachable

try({

### Search with GET

#create fhir search url

request <- fhir_url(url = "https://server.fire.ly",
                    resource = "Patient",
                    parameters = c(gender="female"))

#download bundles
bundles <- fhir_search(request, max_bundles = 5)



### Search with POST (should actually be used for longer requests)

request <- fhir_url(url = "https://server.fire.ly",
                    resource = "Patient")

body <- fhir_body(content = list(gender = "female"))

bundles <- fhir_search(request = request,
                       body = body,
                       max_bundles = 5)


 }, silent = TRUE)