Structure of a NiFi Expression
The NiFi Expression Language always begins with the start delimiter ${
and ends with the end delimiter }
. Between the start and end delimiters is
the text of the Expression itself. In its most basic form, the Expression can consist of just
an attribute name. For example, ${filename}
will return the value of the
"filename" attribute.
In a slightly more complex example, we can instead return a manipulation of this value. We
can, for example, return an all upper-case version of the filename by calling the
toUpper
function: ${filename:toUpper()}
. In this case,
we reference the "filename" attribute and then manipulate this value by using the
toUpper
function. A function call consists of 5 elements. First, there is
a function call delimiter :
. Second is the name of the function - in this
case, "toUpper". Next is an open parenthesis ((
), followed by the
function arguments. The arguments necessary are dependent upon which function is being called.
In this example, we are using the toUpper
function, which does not have any
arguments, so this element is omitted. Finally, the closing parenthesis ()
)
indicates the end of the function call. There are many different functions that are supported
by the Expression Language to achieve many different goals. Some functions provide String
(text) manipulation, such as the toUpper
function. Others, such as the
equals
and matches
functions, provide comparison
functionality. Functions also exist for manipulating dates and times and for performing
mathematical operations. Each of these functions is described below, in the Functions section, with an explanation of what the function does,
the arguments that it requires, and the type of information that it returns.
When we perform a function call on an attribute, as above, we refer to the attribute as
the subject of the function, as the attribute is the entity on which the
function is operating. We can then chain together multiple function calls, where the return
value of the first function becomes the subject of the second function and its return value
becomes the subject of the third function and so on. Continuing with our example, we can chain
together multiple functions by using the expression
${filename:toUpper():equals('HELLO.TXT')}
. There is no limit to
the number of functions that can be chained together.
Any FlowFile attribute can be referenced using the Expression Language. However, if the attribute name contains a "special character," the attribute name must be escaped by quoting it. The following characters are each considered "special characters":
$ (dollar sign)
| (pipe)
{ (open brace)
} (close brace)
( (open parenthesis)
) (close parenthesis)
[ (open bracket)
] (close bracket)
, (comma)
: (colon)
; (semicolon)
/ (forward slash)
* (asterisk)
' (single quote)
(space)
\t (tab)
\r (carriage return)
\n (new-line)
Additionally, a number is considered a "special character" if it is the first
character of the attribute name. If any of these special characters is present in an attribute
is quoted by using either single or double quotes. The Expression Language allows single
quotes and double quotes to be used interchangeably. For example, the following can be used to
escape an attribute named "my attribute": ${"my
attribute"}
or ${'my attribute'}
.
In this example, the value to be returned is the value of the "my attribute"
value, if it exists. If that attribute does not exist, the Expression Language will then look
for a System Environment Variable named "my attribute." If unable to find this, it
will look for a JVM System Property named "my attribute." Finally, if none of these
exists, the Expression Language will return a null
value.
There also exist some functions that expect to have no subject. These functions are
invoked simply by calling the function at the beginning of the Expression, such as
${hostname()}
. These functions can then be changed together, as well. For
example, ${hostname():toUpper()}
. Attempting to evaluate the function with
subject will result in an error. In the Functions section
below, these functions will clearly indicate in their descriptions that they do not require a
subject.
Often times, we will need to compare the values of two different attributes to each other.
We are able to accomplish this by using embedded Expressions. We can, for example, check if
the "filename" attribute is the same as the "uuid" attribute:
${filename:equals( ${uuid} )}
. Notice here, also, that we have a space
between the opening parenthesis for the equals
method and the embedded
Expression. This is not necessary and does not affect how the Expression is evaluated in any
way. Rather, it is intended to make the Expression easier to read. White space is ignored by
the Expression Language between delimiters. Therefore, we can use the Expression ${
filename : equals(${ uuid}) }
or ${filename:equals(${uuid})}
and both Expressions mean the same thing. We cannot, however, use ${file
name:equals(${uuid})}
, because this results in file
and
name
being interpreted as different tokens, rather than a single token,
filename
.