When to escape characters

When using SPL2, use the backslash character ( \ ) to ignore characters that have special meaning in a search, such as quotation marks, pipes, and the backslash character itself.

Alternatives to using escape characters

In some situations, you can avoid using escape characters by using a search literal or raw string literal instead.

Search literals

A search literal is a way to search for one or more terms that appear in your data.

For example, suppose you have a series of logon events that include failed passwords events such as this:

Failed password for user "ladron" from 192.0.2.0/24 port 1047 ssh2

You want to search for the terms user "ladron" from 192.0.2.0/24 in these events. To search for these terms you can use a search literal. With a search literal, an AND condition is implied between each of the terms. Internally the search becomes user AND "ladron" AND from AND 192.0.2.0/24

You must enclose the terms in backtick characters ( ` ). The quoted string inside the set of terms doesn't need to be escaped.

You specify the search literal in the WHERE clause of the from command:

... WHERE `user "ladron" from 192.0.2.0/24`

For more information, see Search literals in expressions.

Raw string literals

A raw string literal is an expression in which the backspace character ( \ ) is not processed.

Raw string literals must be preceded by the at symbol ( @ ) and enclosed in double quotation marks. If a double quotation occurs in the string, it must be escaped using another double quotation.

For example, you want to specify the path C:\windows in your search. This path is a string value and normally you need to escape the backslash character ( \ ) to have the search ignore the backslash in the string. As with all strings, it must be enclosed in double quotation marks.

To use the escaping nomenclature for this string, you specify "C:\\windows".

However, instead of escaping the backslash character, you can designate the path C:\windows as a raw string and precede the string with the at symbol ( @ ). For example: @"C:\windows".

For more information about raw string literals, see Types of expressions

Escape sequences

An escape sequence is a set of characters used in string literals that have a special meaning, such as a new line, a new page, or a tab. For example, the escape sequence \n represents a new line character.

To ignore an escape sequence in your search, prepend a backslash character to the escape sequence. For example, specify \\n to ignore the new line escape sequence.

When you apply a backslash to an escape sequence that is inside quotation marks, the escape sequence is expanded inside the quotation marks.

Characters and escape sequences that must be escaped

The following table shows the characters and escape sequences that must be escaped in your searches:

Character or escape sequence	Description
"	Quotation marks.
\	Backslash character.
\b	Backspace escape sequence.
\f	Page Break escape sequence. Also referred to as the Formfeed Page Break escape sequence.
\n	New Line escape sequence
\r	Return escape sequence. Also referred to as the Carriage Return escape sequence.
\t	Tab escape sequence. Also referred to as the Horizontal Tab escape sequence.

To escape a double quotation mark ( " ), use the sequence \" to search for a literal double quotation mark. To escape a backslash character ( \ ), use the sequence \\ to search for a backslash.

When an escape sequence is sent to a SPL2 command that the command doesn't recognize, an error is returned. For example, the new line \n in a search string is not a known escape sequence. So when \n is sent to a command, an error is returned. However, \\n is a known escape sequence. The escape sequence \\n is interpreted and sent to the command as \n.

Rules for when to use escape characters

The following table explains the circumstances in which you need to use escape characters:

Data type	Rules
String values	String values must be enclosed in double quotation marks ( " ). If a string value contains a single quotation mark ( ' ), that single quotation mark doesn't need to be escaped. For example: ... WHERE game_name="Tzolk'in: The Mayan Calendar" If a string value contains a double quotation mark ( " ), that double quotation mark must be escaped. Otherwise, the search will misinterpret where the string value ends. For example: ... WHERE _raw="The user \"vpatel\" isn't authenticated." If you don't escape the quotation marks around the username "vpatel" the search interprets the string value as "The user ". Because the search can't interpret the rest of the WHERE clause, the search returns a syntax error.
Field names	Field names that contain anything other than letters, numbers, or the underscore ( _ ) character must be enclosed in single quotation marks ( ' ). If a field name contains a single quotation mark ( ' ), that single quotation mark must be escaped. Otherwise, the search will misinterpret where the field name ends. In the following example, the field name Berlin's values contains a space and must be enclosed in single quotation marks. Because the field name also contains a single quotation mark for Berlin's, that single quotation mark must be escaped. ... | eval 'Berlin\'s values'=if(city="Berlin", round(sales), null)
Search literals	Search literals must be enclosed in backtick characters ( ` ). If a string literal contains a backtick character ( ` ), that backtick character must be escaped.

Examples

In addition to the previous examples, the following sections show more examples.

Escaping quotation marks

When you want to search for values that contain quotation marks, using the rules in the preceding section, you must escape the quotation marks.

Consider the following events:

_raw
The user "vpatel" isn't authenticated.
The user "amartin" is not found.

Anytime you search for string values, you must enclose the values in double quotation marks ( " ).

To search string values that contain double quotation marks, such as "amartin", you need to escape the double quotation marks that surround the name. Your search must look like this:

... WHERE name="\"amartin\""...

Here's another example.

Consider the following JSON. The text values contain quotation marks, which are escaped using the backslash character ( \ ):

{
  quote:
    {
      name:"Hamlet", 
      text:"\"To be, or not to be, that is the question:\""
    },
  quote:
    {
      name:"Maya Angelou", 
      text:"\"You may not control all the events that happen to you, 
      but you can decide not to be reduced by them.\""
    },
  quote:
    {
      name:"Ralph Waldo Emerson", 
      text:"\"To be yourself in a world that is constantly trying to 
      make you something else is the greatest accomplishment.\""
    }
}

To search for all text objects that contain values that start with "To be, you need to use a wildcard. The WHERE clause does not support the asterisk character ( * ) wildcard. Instead, you must use the like function in the WHERE clause to search using a wildcard. The like function uses the percent sign ( % ) as a wildcard character.

The search looks like this:

| FROM [{ quote:{name:"Hamlet", text:"\"To be or not to be that is the question:\""}, quote:{name:"Maya Angelou", text:"\"You may not control all the events that happen to you, but you can decide not to be reduced by them.\""}, quote:{name:"Ralph Waldo Emerson", text:"\"To be yourself in a world that is constantly trying to make you something else is the greatest accomplishment.\""} }] WHERE 'quote' LIKE "%\"To be%"

This search returns the quotes from Hamlet and Ralph Waldo Emerson.

The like function supports several syntaxes, see Comparison and Conditional functions.

This example uses a dataset literal so that you can see what is being searched for. See Dataset literals.

Escaping backslashes

The most common example of escaping backslashes is with Windows file paths. Suppose you want to search for the path C:\windows\temp in your events. You must escape the backslashes ( \ ):

...WHERE path="C:\\windows\\temp"

See also

Related information

SPL2 and regular expressions