# Reading material draft

## 1. Search operations
Search operations traverse through an existing set of resources filtering by parameters supplied to the search operation. The FHIR search framework is described here: https://www.hl7.org/fhir/search.html

In the simplest case, a search is executed by performing a `GET` operation in the RESTful framework, which has the following format:

`GET [base]/[type]?name=value&...{&_format=[mime-type]}}`

The different parts of this operation are explained below:
* *base* - a link to a FHIR server to perform the search upon
* *type* - the name of the Resource type that is searched upon
* *name* - the name of a search parameter that applies to the selected Resource
* *value* - the value that you want to search upon (for example if you want to search for all female patients, the search parameter would be gender and the value to search upon would be female
* *format* - only used if you want to specify the format of the output (for example if you want the output to be formatted in JSON, you would write `_format=json`)

Below are a couple of examples of searches on the Vonk server. Note that you can also test these examples by copy-pasting the link (without `GET`) in your browser.

**Example 1** 

In this example no search parameter is used. By using only *base* and *type* you can retrieve all instances of a specific Resource type. Run this example to get all Patients from the Vonk server. 

`GET http://vonk.furore.com/Patient`

**Example 2**

When adding one or more search parameters to your query, start with a question mark behind *type*. In this example the search parameter `name` of the Patient Resource is used. This search parameter can be used to find matches on any of the String fields in HumanName, including family, given, prefix, suffix, suffix, and/or text. Run this example to get all Patients named Caro from the Vonk server. 

`GET http://vonk.furore.com/Patient?name=Caro`

**Example 3** 

You can add more than one search parameter by using the `&` character. In this example, we use the search parameters `family` and `given` to search for Patients named Caro Emerald (given=Caro and family=Emerald). We also include the `_format` parameter to get the output in JSON format. Run this example to get all Patients named Caro Emerald from the Vonk server in JSON format.

`GET http://vonk.furore.com/Patient?family=Emerald&given=Caro&_format=JSON`

## 2. Search parameters
Each Resource can be searched by a couple of common parameters (e.g. `_id`, `_lastUpdated` and `_tag`) and the additional search parameters that are specified for this Resource. When you scroll down in the Content tab of the documentation of a Resource, you find the search parameters defined for that Resource. You can also find a list of all search parameters here: https://www.hl7.org/fhir/searchparameter-registry.html

The table below shows the search parameter types, common search parameters for all resources and the search result parameters.

{{render:Search_parameters.PNG}}

### 2.1 Search parameter types
Each search parameter has a certain type (e.g. a String or a Number), which specifies the type of data that is searched upon. For the ordered parameter types of number, date, and quantity, a prefix to the parameter value may be used to control the nature of the matching. For example, if you want to search within a specific date range, you would use the prefixes `ge` (greater or equal) and `le` (less or equal). For example: 

`GET [base]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31`

These are the defined search parameter types

type     | description | example
---------|-------------|----------
number   |Search parameter SHALL be a number (a whole number, or a decimal).| ```length=27 ```
date	 | Search parameter is on a date/time. The date format is the standard XML format. | ```birthdate=1964-12-10```
string	|Search parameter is a simple string, like a name part. Search is case-insensitive and accent-insensitive. May match just the start of a string. String parameters may contain spaces. | ```name=John``` 
token	|Search parameter on a coded element or identifier. May be used to search through the text, displayname, code and code/codesystem (for codes) and label, system and key (for identifier). Its value is either a string or a pair of namespace and value, separated by a ``` "|" ```, depending on the modifier used.| ```gender=http://hl7.org/fhir/v3/AdministrativeGender|female```
reference | A reference to another resource. | ```subject:Patient=23```
composite |	A composite search parameter that combines a search on two values together. | ```state-on-date=new$2013-05-04```
quantity  |	A search parameter that searches on a quantity. | ```value=5.4|http://unitsofmeasure.org|mg```
uri	      | A search parameter that searches on a URI (RFC 3986). | ```uri=http://acme.org/fhir/```

#### 2.1.1 Modifiers
Depending on the type of the search parameters, modifiers can sometimes be used. For example, a search on a String can be altered by the `:exact` modifier to match the exact String value or the `:contains` modifier to search for String values that match partly match the value.

**Example**

Suppose you have three Patients in your database, one named Caro, one named Carola and one named Jim. You run the following search requests:

`GET http://vonk.furore.com/Patient?name:contains=Caro`

`GET http://vonk.furore.com/Patient?name:exact=Caro`

The first request would return both Caro and Carola, as Carola contains the String value Caro. The second request would only return Caro, as you're asking the server for an exact match of both String values.

#### 2.1.2 Prefixes
For the parameter types of ```number```, ```date```, and ```quantity```, a prefix to the value may be used to control the nature of the matching. If no prefix is present, the prefix ```eq``` is assumed. The following prefixes can be used: 

prefix | description 
-------|-------------
eq |	the value for the parameter in the resource is equal to the provided value 
ne |	the value for the parameter in the resource is not equal to the provided value 
gt |	the value for the parameter in the resource is greater than the provided value  
lt |	the value for the parameter in the resource is less than the provided value 
ge |	the value for the parameter in the resource is greater or equal to the provided value 
le |	the value for the parameter in the resource is less or equal to the provided value
sa |	the value for the parameter in the resource starts after the provided value
eb |	the value for the parameter in the resource ends before the provided value
ap |	the value for the parameter in the resource is approximately the same to the provided value. Note that the recommended value for the approximation is 10% of the stated value (or for a date, 10% of the gap between now and the date), but systems may choose other values where appropriate

**Examples**

Get all appointments that start after or on January 1st 2018 and until and including February 15th 2019

```GET http://vonk.furore.com/Appointment?date=ge2018-01-01&date=le2018-02-15```

or

```GET http://vonk.furore.com/Appointment?date=gt2017-12-31&date=lt2018-02-16```

More details about the prefixes, including extensive examples, can be found on the [FHIR specification search spec](http://hl7.org/stu3/fhir/search.html#prefix)

### 2.2 Parameters for all resources
This set of parameters works for all Resource types. In this section we will explain a couple of them:
1. The `_id` parameter refers to the logical ID of the Resource and can be used to search for a specific instance of the Resource. Note however that a search operation always returns a Bundle, even if the number of matches is 1. To go to an instance directly you would need to use `[base]/[type]?logical_id` rather then `[base]/[type]?_id=logical_id`. 
2. The `_lastUpdated` parameter can be used to search for Resources that are updated after a certain Date. 
3. The `_tag`, `_profile` and `_security` parameters search on the equivalent parameters in the meta element. For example, tags could be used to mark that a Resource should still be reviewed. 
4. The `_profile` parameter can be used to restrict the search to instances of a specific profile only.

### 2.3 Search result parameters
The search result parameters can be used to manage the returned Resources. For example the `_sort` parameter can be used to order the returned Resources alphabetically by name. Another example is the `_count` parameter, which allows you to define the maximum number of search results you want to show on a page. For example, suppose your search results in 15 Patients and you have set the `_count` to 10. In this case, the first page of the Bundle would show the first 10 Patients and the second page would show the remaining 5 Patients.

Here is a list of all parameters that can be used to manage the returned results.

name | description | allowable content | example
-----|-------------|--------------------|-----------
_sort |	Order to sort results in (can repeat for inner sort orders)	| Name of a valid search parameter | ```_sort=date```
_count |Number of results per page |	Whole number | ```_count=50```
_include | Other resources to include in the search results that search matches point to |SourceType:searchParam(:targetType) |  ```_include=Patient:general-practitioner```
_revinclude |Other resources to include in the search results when they refer to search matches |	SourceType:searchParam(:targetType) | ```_revinclude=Provenance:target```
_summary | Just return the summary elements (for resources where this is defined) |	```true | false``` (false is default) | ```_summary=true```
_contained |	Whether to return resources contained in other resources in the search matches|```true | false | both``` (false is default) | ```_contained = true ```
_containedType |	If returning contained resources, whether to return the contained or container resources | ```container | contained``` | ```containedType = container ```
_elements |  return a specific set of elements as part of a resource | Name of  resource elements | ```_elements=identifier,active,link```

## 3. Custom search parameters
Some FHIR servers allow you to add custom search parameters. For example, if you are running your own Vonk implementation, you can choose to add custom search parameters by either posting them to the administration database or you can configure the settings to automatically load them from a local folder on your machine when starting your server. 

Below is an example of a custom search parameter that was created for the US to search on race. This search parameter is not part of the core specification, but as it is common to include race in the US, they provide this search parameter at a national level.

{{render:US-Core/race-2}}

## 4. Running your own search requests
You can run search requests in your browser, but if you are running them more frequently, we would advice you to download a REST client. One that we like to use is [Postman](https://www.getpostman.com/). Postman is free to use and allows you to save requests to collections and share them with others. If you want to learn more about running your own requests, a nice starting point is the free [tutorial](https://fhir-drills.github.io/) of the Australian Digital Health Agency.