Study guide
7.1 Creating Basic Search Macros & Backtick Syntax
Splunk Core Certified Power User Exam
Track your progress as you read
Finished sections get a check mark.
1 Introduction & Exam Overview
0.1 Exam Facts, Logistics & Test-Taking Strategy 0.2 Splunk Knowledge Objects & Search Pipeline Architecture
2 Chapter 1: Transforming Commands for Visualizations
1.1 The chart Command & Multi-Dimensional Aggregations 1.2 The timechart Command & Time-Series Visualizations 1.3 Transforming Options: limit, useother, usenull, and Split-By Clauses
3 Chapter 2: Filtering and Formatting Results
2.1 The eval Command & Core Evaluation Functions 2.2 Filtering Data: search vs. where Commands 2.3 Handling Missing Data with fillnull
4 Chapter 3: Correlating Events & Transactions
3.1 Understanding Transactions & Event Grouping Concepts 3.2 Configuring transaction Constraints: maxspan, maxpause, startswith, endswith 3.3 Analyzing Transaction Output Fields: duration & eventcount 3.4 transaction vs. stats: Performance & Architectural Trade-offs
5 Chapter 4: Creating and Managing Fields
4.1 Regular Expression Extractions with Field Extractor 4.2 Delimiter-Based Extractions with Field Extractor 4.3 Field Extraction Management, Permissions & Search-Time Precedence
6 Chapter 5: Field Aliases and Calculated Fields
5.1 Creating and Using Field Aliases 5.2 Creating and Configuring Calculated Fields 5.3 Aliases vs. Calculated Fields in the Search Execution Pipeline
7 Chapter 6: Tags and Event Types
6.1 Creating and Using Event Types 6.2 Creating and Managing Tags 6.3 Combining Tags and Event Types for Data Classification
8 Chapter 7: Creating and Using Search Macros
7.1 Creating Basic Search Macros & Backtick Syntax 7.2 Macro Arguments, Validation & Evaluation Functions 7.3 Macro Scoping, Permissions & Troubleshooting
9 Chapter 8: Creating and Using Workflow Actions
8.1 Workflow Action Architecture & Field/Event Context 8.2 Creating GET and POST Workflow Actions 8.3 Creating Search Workflow Actions & Dynamic Secondary Searches
10 Chapter 9: Data Models and Pivot
9.1 Data Model Architecture & The Pivot Tool 9.2 Creating and Structuring Datasets & Hierarchies 9.3 Accelerating Data Models & TSIDX Acceleration
11 Chapter 10: Common Information Model (CIM)
10.1 The Splunk Common Information Model (CIM) & Normalization 10.2 CIM Knowledge Objects, Data Models & Schemas 10.3 Normalizing & Validating Data with the CIM App / datamodel command
7.1 Creating Basic Search Macros & Backtick Syntax
Key Takeaways Explain This Topic AI
A search macro is a reusable, named chunk of Search Processing Language (SPL) text or search fragment stored as a Splunk knowledge object that performs search-time string substitution before query execution.
Search macros are invoked in SPL searches exclusively using enclosing backtick characters ( macro_name ); standard single quotes ('...') or double quotes ("...") treat the macro name as a literal string and will NOT trigger macro expansion.
Unlike event types or saved searches that have fixed operational roles, search macros can be placed anywhere within an SPL search string—including base search filters, eval expressions, transforming commands, or entire downstream pipeline stages.
Search macros are created and managed graphically in Splunk Web under Settings > Advanced search > Search macros or defined on the filesystem in macros.conf.
Search macros support modular nesting, allowing one macro to invoke another within its definition, with Splunk recursively expanding all nested references while enforcing cycle detection to prevent infinite loops.
Last updated: August 2026
7.1 Creating Basic Search Macros & Backtick Syntax
In enterprise Splunk deployments, analysts and engineers frequently construct complex, multi-line Search Processing Language (SPL) queries to perform security correlation, operational monitoring, infrastructure health checks, and business metric reporting. Often, identical search fragments—such as complex base search filters, intricate regular expression logic, statistical formulas, or standard output formatting pipelines—must be duplicated across dozens or hundreds of saved searches, alert definitions, reports, and dashboard panels.
This copy-paste approach introduces severe operational risks: if an index name changes, a field definition evolves, or a calculation formula needs adjustment, administrators and Power Users must manually locate and update every individual search. Search macros solve this architectural challenge by enabling the Don't Repeat Yourself (DRY) software engineering principle within Splunk. A search macro allows you to encapsulate a reusable chunk of SPL text into a named knowledge object, which is then dynamically expanded inline whenever the macro is invoked.
Mastering search macro creation, backtick invocation syntax, string substitution mechanics, placement flexibility, and macro nesting is a critical core competency tested on the Splunk Core Certified Power User examination.
1. Architectural Foundations & String Substitution Mechanics
A search macro is a persistent Splunk knowledge object that stores a predefined fragment of SPL text. When a user runs a search containing a search macro, Splunk's search parser performs a search-time literal string substitution (interpolation) : it replaces the macro invocation token with the full definition string of the macro before compiling and executing the query pipeline. +-----------------------------------------------------------------------------------------+
- | SEARCH MACRO COMPILATION & EXPANSION PIPELINE |
- +-----------------------------------------------------------------------------------------+
- | User-Entered Search Query in Search Bar: |
- | `web_server_errors` | stats count by clientip, status | `format_top_10` |
- +-----------------------------------------------------------------------------------------+
- │
- Stage 1: Search Parser Identifies Backtick Tokens
- `web_server_errors` ---> (sourcetype=access_* status>=400 status<=599)
- `format_top_10` ---> sort - count | head 10
- │
- ▼
- +-----------------------------------------------------------------------------------------+
- | Fully Expanded Search String (Compiled into Abstract Syntax Tree): |
- | (sourcetype=access_* status>=400 status<=599) |
- | | stats count by clientip, status |
- | | sort - count | head 10 |
- +-----------------------------------------------------------------------------------------+
- │
- Stage 2: Distributed Query Optimization & Execution
- ▼
- | Dispatched to Indexers (Map Phase) & Aggregated on Search Head (Reduce Phase) |
- +-----------------------------------------------------------------------------------------+
Core Operational Characteristics of Search Macros:
Pre-Execution String Substitution: Macro substitution occurs at parse time before any data retrieval or command evaluation begins. The search engine treats the expanded macro text exactly as if the user had typed the full SPL string manually.
Zero Storage Overhead on Indexers: Search macros exist solely as knowledge object definitions on search heads (stored in macros.conf ). They do not consume disk space on indexers or modify raw data journals.
Centralized Maintenance & Instant Propagation: Modifying a single macro definition instantly updates every dashboard panel, scheduled report, correlation alert, and ad-hoc query referencing that macro across the organization.
Abstracted Query Complexity: Junior analysts and business users can leverage highly complex, optimized SPL routines authored by Power Users simply by typing a short, intuitive macro name.
2. Backtick Syntax Rules & The Character Distinction Matrix
To invoke a search macro in SPL, the macro name must be enclosed within backtick characters (also known as the accent grave or grave accent: ` ). On standard US/QWERTY keyboards, the backtick key is located in the upper-left corner, immediately below the Esc key and sharing the keycap with the tilde ( ~ ). `-- Correct macro invocation syntax:`
- `macro_name`
- The Critical Quote Character Distinction Matrix
A frequent point of confusion for new Splunk practitioners—and a heavily tested concept on the Power User exam—is the strict distinction between backticks, double quotes, and single quotes in SPL:
Character Type Symbol / Syntax Splunk SPL Semantic Meaning Example Usage What Happens if Used for a Macro?
Backtick `macro_name` Macro Invocation & String Expansion `web_errors` CORRECT. Splunk expands the macro definition into SPL before search execution.
Double Quote "string_literal" String Literal / Phrase Grouping "404 Not Found" ; user="john doe" FAILS. Splunk treats "web_errors" as a literal text search for the word web_errors in event text.
Single Quote 'field_name' Field Identifier with Special Characters / Spaces (in eval and where ) | eval x = 'ip-address' ; | where 'error count' > 5 FAILS. In eval / where , Splunk treats 'web_errors' as a field name; in base search, it is treated as literal text. +-----------------------------------------------------------------------------------------+
- | SPL CHARACTER SEMANTICS COMPARISON |
- +-----------------------------------------------------------------------------------------+
- | 1. Backtick (`) --> `audit_logs` ==> Expands to: index=security sourcetype=audit |
- | 2. Double Quote (") --> "audit_logs" ==> Searches for the literal word "audit_logs" |
- | 3. Single Quote (') --> 'audit_logs' ==> References a field named 'audit_logs' |
- +-----------------------------------------------------------------------------------------+
Important
The Strict Backtick Rule: Splunk will only recognize and expand a search macro if it is wrapped in backticks ( ` ). If you type 'macro_name' (single quotes) or "macro_name" (double quotes), Splunk will never invoke the macro knowledge object.
3. Placement Flexibility: Positioning Macros Anywhere in SPL
Unlike event types (which can only be referenced in search filtering clauses) or saved searches (which are typically executed via | savedsearch <name> ), search macros possess universal placement flexibility . Because a macro is simply a literal text replacement mechanism, a macro can be inserted at any position within an SPL query string where valid syntax can exist. +-----------------------------------------------------------------------------------------+
- | SEARCH MACRO PLACEMENT SCENARIOS IN SPL |
- +-----------------------------------------------------------------------------------------+
- | 1. Base Search Filter: `firewall_index` dest_port=443 |
- | 2. Command Clause / Eval: index=web | eval response_sec = `ms_to_sec(duration_ms)` |
- | 3. Filtering Pipe / Where: index=auth | `filter_non_admin_users` |
- | 4. Transforming Pipeline: index=sales | `aggregate_daily_revenue` |
- | 5. Formatting & Layout: index=perf | stats avg(cpu) by host | `standard_table` |
- | 6. Complete End-to-End SPL: `generate_compliance_audit_report` |
- +-----------------------------------------------------------------------------------------+
Detailed Placement Patterns & Real-World Examples:
Pattern 1: Leading Base Search Filter (Index & Sourcetype Selection)
A macro can encapsulate the base index, sourcetype, and foundational boolean filter criteria for an enterprise technology:
- Macro Name: pan_traffic
- Macro Definition: index=firewall sourcetype=pan:traffic action=allowed
- Search Usage: `pan_traffic` dest_port=22
- | stats count by src_ip, dest_ip
- Expanded Search: index=firewall sourcetype=pan:traffic action=allowed dest_port=22
- | stats count by src_ip, dest_ip
- Pattern 2: Middle-of-Search Streaming Evaluation
A macro can encapsulate complex mathematical formulas or conditional logic within an eval command:
- Macro Name: calc_network_mb
- Macro Definition: round((bytes_in + bytes_out) / 1048576, 2)
- Search Usage: index=network
- | eval total_mb = `calc_network_mb`
- | stats sum(total_mb) as volume_mb by host
- Pattern 3: Filtering Pipe ( where or search Clause)
A macro can represent a standardized exclusion filter (e.g., stripping internal test IP addresses or automated health check agents):
- Macro Name: exclude_internal_probes
- Macro Definition: search NOT src_ip="10.0.0.0/8" NOT src_ip="127.0.0.1" NOT user_agent="*Pingdom*"
- Search Usage: index=web
- | `exclude_internal_probes`
- | stats count by uri_path
- Pattern 4: Downstream Transforming & Formatting Pipeline
A macro can encapsulate standard presentation pipelines, charting commands, or table formatting rules:
Macro Name: format_kpi_summary
Macro Definition: stats count, p95(resp_time) as p95_latency, count(eval(status>=500)) as server_errors by service | eval error_rate = round((server_errors/count)*100, 2)
- Search Usage: index=microservices sourcetype=api_gateway
- | `format_kpi_summary`
- 4. Step-by-Step UI Configuration Walkthrough in Splunk Web
Power Users frequently create and manage basic search macros directly within the Splunk Web graphical interface without needing backend filesystem access. +-----------------------------------------------------------------------------------------+
- | SPLUNK WEB NAVIGATION: CREATING A SEARCH MACRO |
- +-----------------------------------------------------------------------------------------+
- | [Settings] ➔ [Advanced search] (under Knowledge category) ➔ [Search macros] |
- | ➔ Click [New Search Macro] (Green Button) |
- +-----------------------------------------------------------------------------------------+
Step-by-Step Creation Procedure:
Log into Splunk Web and click Settings in the global navigation bar.
Under the Knowledge category, click Advanced search .
On the Advanced Search page, click Search macros to open the macro management table.
Click the green New Search Macro button in the upper-right corner.
Complete the macro configuration modal with the required attributes:
Destination app: Select the Splunk application container where the macro will reside (e.g., search , SplunkEnterpriseSecuritySuite , or a custom corporate app).
Name: Enter the unique, descriptive identifier for the macro (e.g., web_server_errors or pci_scoped_hosts ). For basic macros that do not accept parameters, do not include parentheses in the name.
Definition: Enter the exact SPL string fragment to be substituted when the macro is invoked (e.g., (sourcetype=access_* status>=400) ).
Description: (Optional but recommended) Enter clear documentation describing what the macro does, who authored it, and intended usage.
Use eval-based definition: Leave unchecked for basic string substitution macros.
Arguments: Leave empty / blank for basic 0-argument macros.
Validation expression: Leave empty / blank for basic macros.
Validation error message: Leave empty / blank for basic macros.
- Click Save . +-----------------------------------------------------------------------------------------+
- | SPLUNK WEB SEARCH MACRO CREATION MODAL |
- +-----------------------------------------------------------------------------------------+
- | Destination app: [ Search & Reporting (search) ▼ ] |
- | Name: [ web_server_errors ] |
- | Definition: [ (sourcetype=access_* status>=400 status<=599) ] |
- | Description: [ Filters web access logs for 4xx and 5xx errors ] |
- | Use eval-based definition? [ ] (unchecked for standard SPL replacement) |
- | Arguments: [ ] |
- | Validation expression: [ ] |
- | Validation error message: [ ] |
- | |
- | [ Cancel ] [ Save (Green Button) ] |
- +-----------------------------------------------------------------------------------------+
- Setting Permission Scopes (Private, App, Global)
When a search macro is initially saved in Splunk Web, its sharing permission defaults to Private (accessible only to the user account that created it). To enable team members, scheduled reports, and dashboards to use the macro:
In the Search macros management list, locate the newly created macro.
Under the Sharing column, click Permissions .
In the Permissions modal:
Select This app only (App scope) to share the macro across all users within the current application context.
Select All apps (Global scope) to share the macro across every application on the search head.
Assign Read permissions (e.g., Everyone * ) and Write permissions (e.g., power , admin ).
Click Save .
5. Search Macro Nesting & Modular Composition
A powerful architectural feature of Splunk search macros is nesting (modular composition), in which one search macro invokes another search macro within its definition string. +-----------------------------------------------------------------------------------------+
- | MODULAR NESTED SEARCH MACRO ARCHITECTURE |
- +-----------------------------------------------------------------------------------------+
- | Tier 1: Foundation Base Macro |
- | Macro Name: `base_auth_events` |
- | Definition: (index=security sourcetype=auth_logs) |
- +-----------------------------------------------------------------------------------------+
- │
- (Nested Invocation)
- ▼
- +-----------------------------------------------------------------------------------------+
- | Tier 2: Specialized Domain Filter Macro |
- | Macro Name: `auth_failures` |
- | Definition: `base_auth_events` (action=failure OR action=blocked) |
- +-----------------------------------------------------------------------------------------+
- │
- (Nested Invocation)
- ▼
- +-----------------------------------------------------------------------------------------+
- | Tier 3: Analytic KPI Reporting Macro |
- | Macro Name: `brute_force_candidates` |
- | Definition: `auth_failures` | stats count by user, src_ip | where count >= 10 |
- +-----------------------------------------------------------------------------------------+
Recursive Expansion Mechanics:
When an analyst executes the search: `brute_force_candidates`
Splunk expands `brute_force_candidates` into:
`auth_failures` | stats count by user, src_ip | where count >= 10
Splunk scans the newly expanded string and detects `auth_failures` , expanding it into:
`base_auth_events` (action=failure OR action=blocked) | stats count by user, src_ip | where count >= 10
Splunk scans the string again and detects `base_auth_events` , expanding it into:
(index=security sourcetype=auth_logs) (action=failure OR action=blocked) | stats count by user, src_ip | where count >= 10
Finding no further backtick tokens, Splunk compiles the fully resolved SPL into an execution tree.
Loop Detection & Infinite Recursion Prevention
What happens if an administrator accidentally creates a circular reference (e.g., Macro A calls Macro B, and Macro B calls Macro A)?
Splunk includes an internal recursion depth limiter and cycle detection engine .
If a cyclical macro dependency or excessive recursion depth (typically capped at 100 levels) is detected during parse time, Splunk immediately aborts query compilation and displays an error: Search macro 'macro_a' contains a circular reference or exceeds maximum expansion depth.
6. Comprehensive Knowledge Object Comparison
To succeed on the Power User exam, candidates must clearly differentiate search macros from other Splunk knowledge objects:
Knowledge Object Underlying Mechanism Invocation Syntax Primary Use Case Execution Stage in Pipeline
Search Macro Literal string substitution (text interpolation) Enclosed in backticks: `macro_name` Reusable SPL snippets, calculations, filters, or full query templates Pre-Execution (Parse Time) before search compiles
Event Type Search-time event classification and tagging Referenced as eventtype=name or eventtype="name" Categorizing events matching specific search criteria for easy tagging Stage 4 of search pipeline (after calculated fields)
Saved Search / Report Saved SPL query with scheduling and alerting | savedsearch "Report Name" or executed via UI Scheduled reports, alert triggering, dashboard backing searches Independent search job dispatched to search scheduler
Field Alias In-memory field pointer mapping ( orig AS alias ) Querying alias name directly: src_ip=10.0.0.1 Normalizing vendor-specific field names to CIM standards Stage 2 of search pipeline (before calculated fields)
7. Common Exam Traps & Best Practices
The Single / Double Quote Trap:
Exam Trap: A question presents the search query index=web 'web_errors' | stats count and asks why no results were returned.
Fact: Single quotes do not invoke search macros; only backticks ( `web_errors` ) expand macros. In eval / where , single quotes specify field names.
The Missing Pipe Trap:
Exam Trap: A macro calc_ratio is defined as eval ratio = bytes_in / bytes_out . The search runs index=web calc_ratio `` (without a leading pipe).
Fact: Because the macro definition starts with eval (a generating or streaming command requiring a pipe), expanding it into index=web eval ratio = ... produces an SPL syntax error. Either the macro definition must include the leading pipe ( | eval ratio = ... ) or the search string must supply the pipe ( index=web | calc_ratio ``).
Case-Sensitivity in Macro Names:
Exam Trap: An administrator creates a macro named Security_Alerts . A user searches using `security_alerts` .
Fact: Search macro names are case-sensitive during resolution. Calling `security_alerts` fails to resolve Security_Alerts .
The Trailing Space Trap in Macro Definitions:
Best Practice: Ensure macro definitions containing boolean clauses are enclosed in parentheses (e.g., (status>=400 status<=599) ) so they do not inadvertently break adjacent boolean operator evaluation in the base search.