Safe_not_null

The safe_not_null function can be used to evaluate a number of expressions against any entry. It will evaluate the expressions in the order they are defined in the function, and it will return the result for the first function that is not null. If all expressions fail to provide a valid result, the function will return null.

Syntax

safe_not_null(any $entry, &expressions[])

Evaluates $entry against a set of expressions, returning the first one that provides a non-null answer

Parameters

$entry: The array, object, or key-value pair that defines the scope that will be used for the evaluations
&expressions[]: A set of expressions that will be evaluated against the scope. The function converts the parameter’s input to an array (thus the [] in the syntax). When using this function in a transformation, there is no need to use square brackets when listing expressions. The expressions are introduced with & and divided using a comma instead.

Example

In the examples below, the safe_not_null function is used to evaluate a set of expressions against a string and an array.

{
    "key1": "Hello world! My name is DocuMotor :)",  //String value
    "key2": [  //Array of objects
        {
            "id": 23, //Number value
            "name": "James" //String value
        },
        {
            "id": 56,
             "name": "John"
        }
    ]
}

In the transformation below, safe_not_null is used to evaluate 3 expressions against a string value (key1). The 3 expressions are basically different functions (add, substring and split_on) that are using the defined scope. It is worth mentioning that the expression doesn’t have to be consisting of functions necessarily.

{
    string1: safe_not_null(key1, &add(@, `123`), &substring(@, `0`, `11`), &split_on(@, `true`, '!'))
}

Of the 3 expressions, the first one is invalid, since the add function doesn’t support string values. The remaining 2 are both valid, but only the result of the first one is outputted. That happens, because once the function encounters a valid result, it won’t continue evaluating the remaining expressions.

{
    "string1": "Hello world"
}

Further examples

By changing the order of the 2nd and 3rd expressions within the safe_not_null function in the transformation above, so that the split_on function is evaluated before substring, the final result changes as well. This can be seen in the transformation and output blocks below:

{
    string2: safe_not_null(key1, &add(@, `123`), &split_on(@, `true`, '!'), &substring(@, `0`, `11`))
}

{
    "string2": [
        "Hello world",
        " My name is DocuMotor :)"
    ]
}

When it comes to the array, the safe_not_null function is used to evaluate the add function against the different keys of each object of the array.

{
    array_example: safe_not_null(key2, &add([0].name, [1].name), &add([0].id, [1].id))
}

In the first expression, it results in null as it doesn’t support string values, but the second expression provides a valid result, as it evaluates the function against number values, and thus, this is the result of the safe_not_null function as well.

{
    "array_example": 79
}

Lastly, safe_not_null is used to evaluate 3 expressions against the string value from the first case. All three expressions result in null, as all of them only support array inputs, thus the safe_not_null function also results in null.

{
    null_example: safe_not_null(key1, &add(@, `123`), &map(&@, @), items(@))
}

{
    "null_example": null
}

Note

When the above transformations are run, they might give warning or error messages. This is usually because of the expressions that result in null within the safe_not_null function. Despite that, the transformation is still working and provides valid output data.