Skip to main content

$search

$search(resourceTypeOrQuery?, params?, options?) -> value
Compact type signature<s-o?o?:x>

If resourceTypeOrQuery is omitted, the current context value is used.

Browse categories
FHIR Server And ResourceAsync And Concurrency
Execution
AsyncCan run in parallel

This helper performs FHIR server work asynchronously. Independent calls can start together when they wait on the server. See Parallelism And Async Evaluation and Async And Concurrency.

Documentation​

Requires a configured FHIR server base URL.

$search(resourceTypeOrQuery, params?, options?) performs a FHIR search. The canonical form is a resource type as the first argument and a params object as the second argument. A full query string remains supported when that is more convenient.

Zero, one, or many matches are all valid outcomes.

Return shapes​

  • By default, $search() returns the raw FHIR searchset Bundle returned by the server for that request. In most cases this is the first page of results.
  • If you pass {"fetchAll": true}, $search() follows pagination and returns an array of resources collected across the fetched pages instead of a Bundle.

Zero results​

Zero results are valid.

  • In default mode, the server can return a searchset Bundle with no entry items.
  • In fetchAll mode, $search() returns an empty array.

Supported argument forms​

  • Structured query: $search("Patient", {"identifier": "http://fhir.acme.health/identifier/member-id|" & identifiers.memberId})
  • String query: $search("Patient?identifier=http://fhir.acme.health/identifier/member-id|" & identifiers.memberId)

Supported options​

  • fetchAll: follow pagination and return an array of matched resources instead of the server-returned Bundle
  • maxResults: when fetchAll is enabled, stop with an error before collecting more than this many resources across fetched pages
  • asPost: send the search to the FHIR _search endpoint using POST (see GET and POST variants for FHIR search). Default is false (uses GET)
  • noCache: bypass cached responses for this request. This forces a fresh interaction even if the request is already cached.

Params object behavior​

  • Scalar values become a single FHIR search parameter.
  • Comma-separated strings stay a single parameter value, which is useful when the target server interprets commas as OR semantics for that parameter.
  • Array values become repeated parameters such as identifier=a&identifier=b, which is the practical FHIR-style AND pattern.

Examples​

Search for matching resources​

Input

This example uses the full patient-summary example input. The expression reads the non-FHIR identifiers.memberId source field and combines it with a fixed FHIR identifier system in the search expression.

Example input

JSON
{
  "patientId": "pat-0001",
  "name": {
    "given": "Avery",
    "family": "Reed",
    "display": "Avery Reed"
  },
  "birthDate": "1990-06-12",
  "sex": "female",
  "primaryCareTeam": {
    "organization": "ExampleCare",
    "facility": "ExampleCare Clinic",
    "practitioner": {
      "practitionerId": "prac-4001",
      "display": "Jordan Kim"
    }
  },
  "identifiers": {
    "memberId": "mbr-3001",
    "recordNumber": "rec-5001"
  },
  "tags": [
    "demo",
    "fictional"
  ],
  "_xmlTagName": "patientSummary"
}

Expression

$search("Patient", {"identifier": "http://fhir.acme.health/identifier/member-id|" & identifiers.memberId})

The result below shows the default return shape: the raw searchset Bundle returned by the server. If nothing matches, the same mode can return a valid Bundle with no entry items.

Result

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "pat-0001"
      }
    }
  ]
}

Fetch all matching resources across pages​

Input

This example uses the same patient-summary source input and switches only the options object.

Example input

JSON
{
  "patientId": "pat-0001",
  "name": {
    "given": "Avery",
    "family": "Reed",
    "display": "Avery Reed"
  },
  "birthDate": "1990-06-12",
  "sex": "female",
  "primaryCareTeam": {
    "organization": "ExampleCare",
    "facility": "ExampleCare Clinic",
    "practitioner": {
      "practitionerId": "prac-4001",
      "display": "Jordan Kim"
    }
  },
  "identifiers": {
    "memberId": "mbr-3001",
    "recordNumber": "rec-5001"
  },
  "tags": [
    "demo",
    "fictional"
  ],
  "_xmlTagName": "patientSummary"
}

Expression

$search("Patient", {"identifier": "http://fhir.acme.health/identifier/member-id|" & identifiers.memberId}, {"fetchAll": true})

This mode returns an array of resources instead of a Bundle. If nothing matches, the result is [] (empty array).

Result

[
  {
    "resourceType": "Patient",
    "id": "pat-0001"
  }
]