Skip to content

Commit bb03c47

Browse files
KendalBond007KendalBond007
authored
Update overview-of-search.md
Insert of content per https://dev.azure.com/msft-skilling/Content/_workitems/edit/419638/?view=edit Editing and cleanup to follow.
1 parent b38332e commit bb03c47

File tree

1 file changed

+62
-2
lines changed

1 file changed

+62
-2
lines changed

‎articles/healthcare-apis/fhir/overview-of-search.md

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -129,8 +129,8 @@ FHIR specifies a set of search result parameters to help manage the information
129129
| ------------------------- | -------------------- | ------------------------- | ------------|
130130
| `_elements` | Yes | Yes | |
131131
| `_count` | Yes | Yes | `_count` is limited to 1000 resources. If it's set higher than 1000, only 1000 are returned and a warning will be included in the bundle. |
132-
| `_include` | Yes | Yes | Items retrieved with `_include` are limited to 100. `_include` on PaaS and OSS on Azure Cosmos DB doesn't support `:iterate` [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). |
133-
| `_revinclude` | Yes | Yes |Items retrieved with `_revinclude` are limited to 100. `_revinclude` on PaaS and OSS on Azure Cosmos DB doesn't support `:iterate` [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). There's also an incorrect status code for a bad request: [#1319](https://github.com/microsoft/fhir-server/issues/1319). |
132+
| `_include` | Yes | Yes | `_include` on PaaS and OSS on Azure Cosmos DB doesn't support `:iterate` [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). |
133+
| `_revinclude` | Yes | Yes | `_revinclude` on PaaS and OSS on Azure Cosmos DB doesn't support `:iterate` [(#2137)](https://github.com/microsoft/fhir-server/issues/2137). There's also an incorrect status code for a bad request: [#1319](https://github.com/microsoft/fhir-server/issues/1319). |
134134
| `_summary` | Yes | Yes | |
135135
| `_total` | Partial | Partial | `_total=none` and `_total=accurate` |
136136
| `_sort` | Partial | Partial | `sort=_lastUpdated` is supported on the FHIR service. For the FHIR service and the OSS SQL DB FHIR servers, sorting by strings and dateTime fields are supported. For Azure API for FHIR and OSS Azure Cosmos DB databases created after April 20, 2021, sort is supported on first name, last name, birthdate, and clinical date. |
@@ -144,6 +144,66 @@ Note:
144144

145145
By default, the FHIR service in Azure Health Data Services is set to lenient handling. This means that the server ignores any unknown or unsupported parameters. If you want to use strict handling, you can include the `Prefer` header and set `handling=strict`.
146146

147+
#### _include and _revinclude searches
148+
149+
The FHIR service supports search queries using the `_include` and `_revinclude` parameters. These parameters allow for the retrieval of reference resources in the search results.
150+
151+
The `_include` search parameter enables the retrieval of a particular clinical resource, as well as any other resources that are referenced by it. When included in the query, the `_include` parameter will return both the specified resource and its referenced resources.
152+
153+
The `_revinclude` search parameter operates in reverse order, allowing the retrieval of a resource along with any other resources that reference it. This provides a way to search for resources based on their relationships with other resources. For detailed information on include and revinclude in search parameters, refer to the [FHIR Search Documentation](https://www.hl7.org/fhir/R4/search.html#revinclude).
154+
155+
##### Request parameters
156+
157+
When executing a search request with the `_include` and `_revinclude` parameter, the following optional parameters can be used to control the count.
158+
159+
| **Name** | **Value** | **Description** |
160+
| -------- | --------- | --------------- |
161+
| `_count` | Default value: 10, Max value: 1000 | The value represents the number of targeted resources to be retrieved per request. The value can be set up to 1000. When the parameter is not provided, it is set to 10. |
162+
| `_includesCount` | Default value: 1000 | The value represents the number of matching resources referenced by target resources to be retrieved per request. |
163+
164+
For matched items from `_include` and `_revinclude` searches, a maximum of 1000 items will be included in the response. If the number of matched items exceeds this limit, a related link will be provided that encompasses the $include operation. The provided link will allow you to traverse through the complete result set of matched items.
165+
166+
Example:
167+
168+
In the following example, a search request for Observations is made for Patient with Identifier 123 .
169+
170+
```
171+
GET {{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10
172+
```
173+
174+
The response returned will have observation data for Patient 123. The matched resource references are given 10 per page, and a link is provided which contains the $include operation. You can follow the link to move through the result set.
175+
176+
```
177+
{
178+
"resourceType": "Bundle",
179+
180+
"id": "b5491e39-8f8f-4405-a4cf-2a6716755d73",
181+
"meta": {
182+
"lastUpdated": "2025-04-10T21:09:42.6517693+00:00"
183+
},
184+
"type": "searchset",
185+
"link": [
186+
{
187+
"relation": "next",
188+
"url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10&ct=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGpSSwAAAD%2F%2Fw%3D%3D"
189+
},
190+
191+
{
192+
"relation": "related",
193+
"url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10&includesCt=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGhAaaYqYmOqQUWYaNYAAAAAP%2F%2F"
194+
},
195+
{
196+
"relation": "self",
197+
"url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10”
198+
}
199+
],
200+
"entry": [….]
201+
}
202+
```
203+
204+
> [!NOTE]
205+
> Queries with wild card *.* for `_revinclude` are limited to 100 matches overall.
206+
147207
## Chained & reverse chained searching
148208

149209
A [chained search](https://www.hl7.org/fhir/search.html#chaining) allows you to perform fine-targeted queries for resources that have a reference to another resource. For example, if you want to find encounters where the patient’s name is Jane, use:

0 commit comments

Comments
 (0)