FHIR Search Feature: _include:iterate

[prb112]

FHIR Search has a _include which can be iterative, if (and only if) the modifier :iterate is included
https://www.hl7.org/fhir/search.html#include

The inclusion process can be iterative, if (and only if) the modifier :iterate is included. For 
example, this search returns all Medication Request resources and their prescribing 
Practitioner Resources for the matching Medication Dispense resources: 

GET [base]/MedicationDispense?_include=MedicationDispense:prescription
    &_include:iterate=MedicationRequest:performer&criteria...

Example from PDXNET: {{url}}/Practitioner?identifier=1230782571&_revinclude=PractitionerRole:practitioner&_include:iterate=PractitionerRole:organization

[lmsurpre]

I recommend we only consider going up to one level for the iterate. Otherwise it just gets too hard and performance becomes a bigger concern.

[michaelwschroeder]

High-level design doc attached.
issue1158_design.docx

[michaelwschroeder]

Updated design doc attached.[
issue1158_design_v2.docx
](url)

[prb112]

Looks good... sample created linked patients and then iterated over it.

{
    "resourceType": "Bundle",
    "id": "a34d9d6b-3fce-4311-8c45-3ac612540814",
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://localhost:9443/fhir-server/api/v4/Patient?_count=10&_id=1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca5&_include:iterate=Patient:link:Patient&_include:iterate=Patient:link:RelatedPerson&_page=1"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://localhost:9443/fhir-server/api/v4/Patient/1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca5",
            "resource": {
                "resourceType": "Patient",
                "id": "1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca5",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-03-29T18:02:29.285271Z"
                },
                "active": true,
                "name": [
                    {
                        "family": "Ortiz",
                        "given": [
                            "David"
                        ]
                    }
                ],
                "gender": "male",
                "link": [
                    {
                        "other": {
                            "reference": "Patient/1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca4"
                        },
                        "type": "seealso"
                    }
                ]
            },
            "search": {
                "mode": "match",
                "score": 1
            }
        },
        {
            "fullUrl": "https://localhost:9443/fhir-server/api/v4/Patient/1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca4",
            "resource": {
                "resourceType": "Patient",
                "id": "1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca4",
                "meta": {
                    "versionId": "3",
                    "lastUpdated": "2021-03-29T18:00:43.412148Z"
                },
                "active": true,
                "name": [
                    {
                        "family": "Ortiz",
                        "given": [
                            "David"
                        ]
                    }
                ],
                "gender": "male",
                "link": [
                    {
                        "other": {
                            "reference": "Patient/1784aa352aa-2bdc10a1-4b4d-405e-a8a1-bd1c19afdca4"
                        },
                        "type": "seealso"
                    }
                ]
            },
            "search": {
                "mode": "include",
                "score": 1
            }
        }
    ]
}