FHIRPath Function: coalesce

{:.stu}

Note: The contents of this section are Standard for Trial Use (STU) {: .stu-note } The coalesce function takes a variable number of arguments, each of which is a collection. It returns the first non-empty collection from the arguments. If all arguments are empty collections, the result is an empty collection. {:.stu}

Note that short-circuit behaviour is expected in this function. In other words, arguments after the first non-empty argument are not evaluated. For implementations, this means delaying evaluation of the arguments (as is done with iif). {:.stu}

Patient.coalesce(name.where(use='official'), name.where(use='usual'), name.first()).text // preferentially select name via use
Patient.name.select(coalesce(family & ' ' & given.join(', '), text, 'unknown')) // select is required to process each name separately
coalesce(Patient.identifier.where(system = 'http://example.org/identifier').value.first(), 'unknown')

{:.stu}

Note that this function is useful for providing fallback options, and is more concise than using iif to check each collection in turn. {:.stu}

Such as selecting specific telecom elements based on their use, and falling back to the first available telecom element if none of the specific uses are present: {:.stu}

iif( telecom.where(use='mobile').exists(), telecom.where(use='mobile'),
    iif( telecom.where(use='home').exists(), telecom.where(use='home'),
        iif( telecom.where(use='work').exists(), telecom.where(use='work'),
          telecom))).first()
// could equivalently be written as:
coalesce(telecom.where(use='mobile'), telecom.where(use='home'), telecom.where(use='work'), telecom).first()

{:.stu}

Another common case is to select a specific coding in a CodeableConcept if it is available, otherwise whatever coding is available. {:.stu}

iif( code.coding.where(system='http://snomed.info/sct').exists(),
        code.coding.where(system='http://snomed.info/sct')),
            code.coding)
    .first().code
// could equivalently be written as:
coalesce(code.coding.where(system='http://snomed.info/sct'), code.coding).first().code

{:.stu}

Summary

• Category: Filtering and projection
• Section: 5.2.8
• Return Type: collection
• Empty Input Result: empty
• Errors on Multiple Input: true

Description

The coalesce function takes a variable number of arguments, each of which is a collection. It returns the first non-empty collection from the arguments. If all arguments are empty collections, the result is an empty collection.

Arguments

• value: collection - Collection to check for non-empty values

Type Mapping

• Any-Any

Example

Patient.coalesce(name.where(use='official'), name.where(use='usual'), name.first()).text // preferentially select name via use
Patient.name.select(coalesce(family & ' ' & given.join(', '), text, 'unknown')) // select is required to process each name separately
coalesce(Patient.identifier.where(system = 'http://example.org/identifier').value.first(), 'unknown')