Define search macros in Settings

Search macros are reusable chunks of Search Processing Language (SPL) that you can insert into other searches. Search macros can be any part of a search, such as an eval statement or search term, and do not need to be a complete command. You can also specify whether the macro field takes any arguments.

Prerequisites

• See Insert search macros into search strings.
• See Design a search macro definition.
• (Optional) If your search macros require the search writer to provide argument variables, you can design validation expressions that tell the search writer when invalid arguments have been submitted. See Validate search macro arguments.

Steps

1. Select Settings > Advanced Search > Search macros.
2. Click New to create a search macro.
3. (Optional) Check the Destination app and verify that it is set to the app that you want to restrict your search macro to. Select a different app from the Destination app list if you want to restrict your search macro to a different app.
4. Enter a unique Name for the search macro.
   If your search macro includes an argument, append the number of arguments to the name. For example, if your search macro mymacro includes two arguments, name it mymacro(2).
5. In Definition, enter the search string that the macro expands to when you reference it in another search.
6. (Optional) Click Use eval-based definition? to indicate that the Definition value is an eval expression that returns a string that the search macro expands to.
7. (Optional) Enter any Arguments for your search macro. This is a comma-delimited string of argument names. Argument names may only contain alphanumeric characters (a-Z, A-Z, 0-9), underscores, and dashes. The string cannot contain repetitions of argument names.
8. (Optional) Enter a Validation expression that verifies whether the argument values used to invoke the search macro are acceptable. The validation expression is an eval expression that evaluates to a Boolean or string value.
9. (Optional) Enter a Validation error message if you defined a validation expression. This message appears when the argument values that invoke the search macro fail the validation expression.
10. Click Save to save your search macro.

Design a search macro definition

The fundamental part of a search macro is its definition, which is the SPL chunk that the macro expands to when you reference it in another search.

If your search macro definition has variables, the macro user must input the variables into the definition as tokens with dollar signs on either side of them. For example, $arg1$ might be the first argument in a search macro definition.

The SPL in a search macro definition must comply with the syntax requirements of the search command that uses it. For example, eval command syntax requires that any literal string in the expression is surrounded by double quotation marks. When using a search macro with the eval command, a literal string in the search macro definition must be surrounded by double quotation marks.

Pipe characters and generating commands in macro definitions

When you use generating commands such as search, inputlookup, rest, or tstats in searches, put them at the start of the search, with a leading pipe character.

If you want your search macro to use a generating command, remove the leading pipe character from the macro definition. Place it at the start of the search string that you are inserting the search macro into, in front of the search macro reference.

For example, you have a search macro named mygeneratingmacro that has the following definition:

tstats latest(_time) as latest where index!=filemon by index host source sourcetype

The definition of mygeneratingmacro begins with the generating command tstats. Instead of preceding tstats with a pipe character in the macro definition, you put the pipe character in the search string, before the search macro reference. For example:

| `mygeneratingmacro`

Validate search macro arguments

When you define a search macro that includes arguments that the user must enter, you can define a Validation expression that determines whether the arguments supplied by the user are valid. You can define a Validation error message that appears when search macro arguments fail validation.

The validation expression must be an eval expression that evaluates to a Boolean or a string. If the validation expression is boolean, validation succeeds when the validation expression returns true. If it returns false, or returns null, validation fails.

If the validation expression is not Boolean, validation succeeds when the validation expression returns null. If it returns a string, validation fails.

Additional resources

For more information, see the following resources.

• Search macro examples
• macros.conf in the Admin Manual. The macros.conf configuration file is where Splunk software stores search macro definitions.
• Generating commands in the Search Reference.