You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Below are some examples of using Fast Healthcare Interoperability Resources (FHIR®) search operations, including search parameters and modifiers, chain and reverse chain search, composite search, viewing the next entry set for search results, and searching with a `POST` request. For more information about search, see [Overview of FHIR Search](overview-of-search.md).
16
+
The following are examples of using Fast Healthcare Interoperability Resources (FHIR®) search operations, including search parameters and modifiers, chain and reverse chain search, composite search, viewing the next entry set for search results, and searching with a `POST` request. For more information about search, see [Overview of FHIR Search](overview-of-search.md).
17
17
18
18
## Search result parameters
19
19
20
20
### _include
21
21
22
-
`_include` searches across resources for the ones that include the specified parameter of the resource. For example, you can search across `MedicationRequest` resources to find only the ones that include information about the prescriptions for a specific patient, which is the `reference` parameter `patient`. In the example below, this will pull all the `MedicationRequests` and all patients that are referenced from the `MedicationRequests`:
22
+
`_include` searches across resources for the ones that include the specified parameter of the resource. For example, you can search across `MedicationRequest` resources to find only the ones that include information about the prescriptions for a specific patient, which is the `reference` parameter `patient`. The following example pulls all the `MedicationRequests` and all patients that are referenced from the `MedicationRequests`.
23
23
24
24
```rest
25
25
GET [your-fhir-server]/MedicationRequest?_include=MedicationRequest:patient
@@ -39,20 +39,20 @@ GET [your-fhir-server]/Patient?_revinclude=Encounter:subject
39
39
```
40
40
### _elements
41
41
42
-
`_elements` narrows down the search result to a subset of fields to reduce the response size by omitting unnecessary data. The parameter accepts a comma-separated list of base elements:
42
+
`_elements` narrows down the search result to a subset of fields to reduce the response size by omitting unnecessary data. The parameter accepts a comma-separated list of base elements.
43
43
44
44
```rest
45
45
GET [your-fhir-server]/Patient?_elements=identifier,active
46
46
47
47
```
48
48
49
-
In this request, you'll get back a bundle of patients, but each resource will only include the identifier(s) and the patient's active status. Resources in this returned response will contain a `meta.tag` value of `SUBSETTED` to indicate that they're an incomplete set of results.
49
+
From this request, you get a bundle of patients where each resource only includes the identifiers and the patient's active status. Resources in this response contain a `meta.tag` value of `SUBSETTED` to indicate that they're an incomplete set of results.
50
50
51
51
## Search modifiers
52
52
53
53
### :not
54
54
55
-
`:not` allows you to find resources where an attribute isn't true. For example, you could search for patients where the gender isn't female:
55
+
`:not` allows you to find resources where an attribute isn't true. For example, you could search for patients where the gender isn't female.
56
56
57
57
```rest
58
58
GET [your-fhir-server]/Patient?gender:not=female
@@ -63,7 +63,7 @@ As a return value, you would get all patient entries where the gender isn't fema
63
63
64
64
### :missing
65
65
66
-
`:missing` returns all resources that don't have a value for the specified element when the value is `true`, and returns all the resources that contain the specified element when the value is `false`. For simple data type elements, `:missing=true`will match on all resources where the element is present with extensions but has an empty value. For example, if you want to find all `Patient` resources that are missing information on birth date, you can do:
66
+
`:missing` returns all resources that don't have a value for the specified element when the value is `true`, and returns all the resources that contain the specified element when the value is `false`. For simple data type elements, `:missing=true`matches on all resources where the element is present with extensions but has an empty value. The following example shows how to find all `Patient` resources that are missing information on birth date.
67
67
68
68
```rest
69
69
GET [your-fhir-server]/Patient?birthdate:missing=true
@@ -81,14 +81,14 @@ GET [your-fhir-server]/Patient?name:exact=Jon
81
81
This request returns `Patient` resources that have the name exactly the same as `Jon`. If the resource had Patients with names such as `Jonathan` or `joN`, the search would ignore and skip the resource as it doesn't exactly match the specified value.
82
82
83
83
### :contains
84
-
`:contains` is used for `string` parameters and searches for resources with partial matches of the specified value anywhere in the string within the field being searched. `contains`is case insensitive and allows character concatenating. For example:
84
+
`:contains` is used for `string` parameters and searches for resources with partial matches of the specified value anywhere in the string within the field being searched. `contains`isn't case sensitive and allows character concatenating. For example:
85
85
86
86
```rest
87
87
GET [your-fhir-server]/Patient?address:contains=Meadow
88
88
89
89
```
90
90
91
-
This request would return you all `Patient` resources with `address` fields that have values that contain the string "Meadow". This means you could have addresses that include values such as "Meadowers" or "59 Meadow ST" returned as search results.
91
+
This request would return all `Patient` resources with `address` fields that have values that contain the string "Meadow". This means you could have addresses that include values such as "Meadowers" or "59 Meadow ST" returned as search results.
92
92
93
93
## Chained search
94
94
@@ -101,21 +101,21 @@ To perform a series of search operations that cover multiple reference parameter
101
101
102
102
This request would return all the `DiagnosticReport` resources with a patient subject named "Sarah". The period `.` after the field `Patient` performs the chained search on the reference parameter of the `subject` parameter.
103
103
104
-
Another common use of a regular search (not a chained search) is finding all encounters for a specific patient. `Patient`s will often have one or more `Encounter`s with a subject. To search for all `Encounter` resources for a `Patient` with the provided `id`:
104
+
Another common use of a regular search (not a chained search) is finding all encounters for a specific patient. `Patient`s often have one or more `Encounter`s with a subject. The following searches for all `Encounter` resources for a `Patient` with the provided `id`.
105
105
106
106
```rest
107
107
GET [your-fhir-server]/Encounter?subject=Patient/78a14cbe-8968-49fd-a231-d43e6619399f
108
108
109
109
```
110
110
111
-
Using chained search, you can find all the `Encounter` resources that match a particular piece of `Patient` information, such as the `birthdate`:
111
+
Using chained search, you can find all the `Encounter` resources that match a particular piece of `Patient` information, such as the `birthdate`.
112
112
113
113
```rest
114
114
GET [your-fhir-server]/Encounter?subject:Patient.birthdate=1987-02-20
115
115
116
116
```
117
117
118
-
This would allow not just searching `Encounter` resources for a single patient, but across all patients that have the specified birth date value.
118
+
This would allow searching `Encounter` resources across all patients that have the specified birth date value.
119
119
120
120
In addition, chained search can be done more than once in one request by using the symbol `&`, which allows you to search for multiple conditions in one request. In such cases, chained search "independently" searches for each parameter, instead of searching for conditions that only satisfy all the conditions at once:
121
121
@@ -124,22 +124,22 @@ GET [your-fhir-server]/Patient?general-practitioner:Practitioner.name=Sarah&gene
124
124
125
125
```
126
126
127
-
This would return all `Patient` resources that have "Sarah" as the `generalPractitioner` and have a `generalPractitioner` that has the address with the state WA. In other words, if a patient had Sarah from the state NY and Bill from the state WA both referenced as the patient's `generalPractitioner`, the would be returned.
127
+
This would return all `Patient` resources that have "Sarah" as the `generalPractitioner` and have a `generalPractitioner` that has the address with the state WA. In other words, if a patient had Sarah from the state NY and Bill from the state WA both referenced as the patient's `generalPractitioner`, both are returned.
128
128
129
-
For scenarios in which the search has to be an `AND` operation that covers all conditions as a group, refer to the **composite search** example below.
129
+
For scenarios in which the search has to be an `AND` operation that covers all conditions as a group, refer to the example in [**Composite search**](#composite-search).
130
130
131
131
## Reverse chain search
132
132
133
-
Chain search lets you search for resources based on the properties of resources they refer to. Using reverse chain search, allows you do it the other way around. You can search for resources based on the properties of resources that refer to them, using `_has` parameter. For example, `Observation` resource has a search parameter `patient` referring to a Patient resource. To find all Patient resources that are referenced by `Observation` with a specific `code`:
133
+
Chain search lets you search for resources based on the properties of resources they refer to. Using reverse chain search allows you to do it the other way around. You can search for resources based on the properties of resources that refer to them, using `_has` parameter. For example, an `Observation` resource has a search parameter `patient` referring to a Patient resource. Use the following to find all Patient resources referenced by `Observation` with a specific `code`.
134
134
135
135
```rest
136
136
GET [base]/Patient?_has:Observation:patient:code=527
137
137
138
138
```
139
139
140
-
This request returns Patient resources that are referred by `Observation` with the code `527`.
140
+
This request returns Patient resources referred by `Observation` with the code `527`.
141
141
142
-
In addition, reverse chain search can have a recursive structure. For example, if you want to search for all patients that have `Observation` where the observation has an audit event from a specific user `janedoe`, you could do:
142
+
In addition, reverse chain search can have a recursive structure. For example, the following searches for all patients that have `Observation` where the observation has an audit event from a specific user `janedoe`.
143
143
144
144
```rest
145
145
GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe
@@ -151,7 +151,7 @@ GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practit
151
151
152
152
## Composite search
153
153
154
-
To search for resources that meet multiple conditions at once, use composite search that joins a sequence of single parameter values with a symbol `$`. The returned result would be the intersection of the resources that match all of the conditions specified by the joined search parameters. Such search parameters are called composite search parameters, and they define a new parameter that combines the multiple parameters in a nested structure. For example, if you want to find all `DiagnosticReport` resources that contain `Observation` with a potassium value less than or equal to 9.2:
154
+
To search for resources that meet multiple conditions at once, use a composite search that joins a sequence of single parameter values with a symbol `$`. The result would be the intersection of the resources that match all of the conditions specified by the joined search parameters. Such search parameters are called composite search parameters, and they define a new parameter that combines the multiple parameters in a nested structure. For example, the following search finds all `DiagnosticReport` resources that contain `Observation` with a potassium value less than or equal to 9.2.
155
155
156
156
```rest
157
157
GET [your-fhir-server]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2
@@ -162,7 +162,8 @@ This request specifies the component containing a code of `2823-3`, which in thi
162
162
163
163
## Search the next entry set
164
164
165
-
The maximum number of entries that can be returned per a single search query is 1000. However, you might have more than 1000 entries that match the search query, and you might want to see the next set of entries after the first 1000 entries that were returned. In such case, you would use the continuation token `url` value in `searchset` as in the `Bundle` result below:
165
+
The maximum number of entries that can be returned per a single search query is 1000. If more than 1,000 entries that match the search query, you can use the following procedure to see entries greater than 1000.<br>
166
+
Use the continuation token `url` value in `searchset`, as in the following `Bundle` result.
166
167
167
168
```json
168
169
"resourceType": "Bundle",
@@ -184,27 +185,27 @@ The maximum number of entries that can be returned per a single search query is
184
185
185
186
```
186
187
187
-
And you would do a GET request for the provided URL under the field `relation: next`:
188
+
Then do a GET request for the provided URL under the field `relation: next`.
188
189
189
190
```rest
190
191
GET [your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd
191
192
192
193
```
193
194
194
-
This will return the next set of entries for your search result. The `searchset` is the complete set of search result entries, and the continuation token `url` is the link provided by the server for you to retrieve the entries that don't show up on the first set because the restriction on the maximum number of entries returned for a search query.
195
+
This returns the next set of entries for your search result. The `searchset` is the complete set of search result entries, and the continuation token `url` is the link provided by the server for you to retrieve entries that don't show up in the first 1000.
195
196
196
197
## Search using POST
197
198
198
-
All of the search examples mentioned above have used `GET` requests. You can also do search operations using `POST` requests using `_search`:
199
+
All of the search examples previously mentioned used `GET` requests. You can also do search operations using `POST` requests using `_search`.
199
200
200
201
```rest
201
202
POST [your-fhir-server]/Patient/_search?_id=45
202
203
203
204
```
204
205
205
-
This request would return all `Patient` resources with the `id` value of 45. Just as in GET requests, the server determines which of the set of resources meets the condition(s), and returns a bundle resource in the HTTP response.
206
+
This request returns `Patient` resources with the `id` value of 45. As with GET requests, the server determines which of the set of resources meets the condition, and returns a bundle resource in the HTTP response.
206
207
207
-
Another example of searching using POST where the query parameters are submitted as a form body is:
208
+
Another example of searching using POST where the query parameters are submitted as a form body is as follows.
208
209
209
210
```rest
210
211
POST [your-fhir-server]/Patient/_search
@@ -220,4 +221,4 @@ In this article, you learned about how to search using different search paramete
220
221
>[!div class="nextstepaction"]
221
222
>[Overview of FHIR Search](overview-of-search.md)
222
223
223
-
FHIR® is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.
0 commit comments