$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.

Multi-server connections

This function uses the default FHIR server unless $useFhirServer() has been called in the current expression block. See Multi-server connections for details.

$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 a flattened array of resources collected from Bundle.entry[].resource across the fetched pages instead of a Bundle.

When fetchAll is enabled, every resource present in Bundle.entry[].resource is included in the returned array. If your search uses _include or _revinclude, included resources are part of that array when the server returns them. This is different from single-match helpers such as $literal() and $resolve(), which enforce match-specific behavior for their own results.

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 resources collected from Bundle.entry[].resource instead of the server-returned Bundle
• maxResults: when fetchAll is enabled, override the default per-call safety cap and 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.

When fetchAll is enabled, $search() uses a default safety cap of 10000 collected resources. Use maxResults to override that cap for the current call. There is no current fume-community or fume environment-variable setting for this limit.

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 resources returned 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. The array contains every resource present in Bundle.entry[].resource across the fetched pages, so _include and _revinclude results are included when the server returns them. If nothing matches, the result is [] (empty array).

Result

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