Splunk® Enterprise

Knowledge Manager Manual

Splunk Enterprise version 8.0 is no longer supported as of October 22, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

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 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.

Last modified on 21 May, 2021
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

Was this topic useful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters