The text:positionOf() function can be used to determine where a given sequence of characters occurs within the value of a field. The function returns the index of the occurrence in a new field, using zero-based numbering, which means that a returned value of 0 indicates that the field value begins with the searched characters.

If the searched characters do not occur in the field value, the event is returned without a _position field. The function can therefore be used both to locate a sequence of characters and, by testing whether the output field exists, to determine whether the sequence is present at all.

In this example, the text:positionOf() function is used to find the position of the characters lo within the field field of each event.

Example incoming data might look like this:

The query is used to return the position at which the characters lo occur in the field field of each event.

This query is useful, for example, when a marker or delimiter appears at a variable position within a string and its index is needed before the string can be split or truncated, or when the presence of a sequence of characters must be tested without writing a regular expression.

Sample output from the incoming example data:

Note that the returned position uses zero-based numbering, which is why the value log returns 0 rather than 1, and why the value hello returns 3, as the l of the matched lo sequence is the fourth character of the string.

The blank cell for world represents an absent field, not an empty value. The value world does not contain the sequence lo, even though it contains both characters individually, so no _position field is added to that event.