Use search macros in searches
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.
Insert search macros into search strings
When you put a search macro in a search string, place a back tick character ( ` ) before and after the macro name. On most English-language keyboards, this character is located on the same key as the tilde (~). You can reference a search macro within other search macros using this same syntax. For example, if you have a search macro named
mymacro it looks like the following when referenced in a search:
sourcetype=access_* | `mymacro`
Macros inside of quoted values are not expanded. In the following example, the search macro
bar is not expanded.
Preview search macros in search strings
Check the contents of your search macro from the Search bar in the Search page using the following keyboard shortcut:
- Command-Shift-E (Mac OSX)
- Control-Shift-E (Linux or Windows)
The shortcut opens a preview that displays the expanded search string, including all nested search macros and saved searches. If syntax highlighting or line numbering are enabled, those features also appear in the preview.
You can copy parts of the expanded search string. You can also click Open in Search to run the expanded search string in a new window. See Preview your search.
Search macros that contain generating commands
When you use a search macro in a search string, consider whether the macro expands to an SPL string that begins with a Generating command like
tstats. If it does, you need to put a pipe character before the search macro.
For example, if you know the search macro
mygeneratingmacro starts with the
tstats command, you would insert it into your search string as follows:
When search macros take arguments
If your search macro takes arguments, define those arguments when you insert the macro into the search string. For example, if the search macro
argmacro(2) includes two arguments that are integers, you might have inserted the macro into your search string as follows:
If your search macro argument includes quotes, escape the quotes when you call the macro in your search. For example, if you pass a quoted string as the argument for your macro, you use:
`mymacro("He said \"hello!\"")`.
Your search macro definition can include the following:
- A validation expression that determines whether the arguments you enter are valid.
- A validation error message that appears when you provide invalid arguments.
Using macros to provide comments in searches
The search macro framework also lets you add comments to searches.
`comment("This part of the search returns only one value")`
See Add comments to a search, in the Search Manual.
For more information, see the following resources.
Configure field aliases with props.conf
Define search macros in Settings
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.1.0, 8.1.1, 7.3.8, 8.1.2, 8.1.3