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.
"foo`bar`baz"
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 from, search, metadata, inputlookup, pivot, and 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:
| `mygeneratingmacro`
See Define search macros in Settings.
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: `argmacro(120,300)`.
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.
Additional resources
For more information, see the following resources.
- Define search macros in Settings
- Search macro examples
- Generating commands, in the Search Reference.
| 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.8, 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.0.10
Download manual
Feedback submitted, thanks!