Skip to main content

$searchSingle

$searchSingle(resourceTypeOrRef?, params?, options?) -> object
Compact type signature<s-o?o?:o>

If resourceTypeOrRef 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.

$searchSingle(resourceTypeOrRef, params?, options?) returns one FHIR resource.

It supports the same single-resource lookup patterns as $resolve(): pass a structured query (resource type and a parameters object) or a full search query as string.

Supported argument forms​

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

Supported options​

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

Error behavior​

$searchSingle() requires exactly one match. It throws if the search returns no match or multiple matches.

Examples​

Search and expect exactly one match​

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

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

This search must resolve to exactly one matching resource.

Result

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