Add comments to searches
You can add inline comments to the search string of a saved search by enclosing the comments in backtick characters ( ``` ).
Use inline comments to:
- Explain each "step" of a complicated search that is shared with other users.
- Discuss ways of improving a search with other users.
- Leave notes for yourself in unshared searches that are works in progress.
- Troubleshoot searches by running them with chunks of SPL "commented out".
Here is an example of a search with comments:
sourcetype=accesss_* status=200 ```Get all successful website access events.```
| stats count AS views count(eval(action="addtocart")) AS addtocart count(eval(action="purchase")) AS purchases by productName ```Create counts of site views, add-to-cart actions, and purchase actions. Break them out by product name. ```
| eval cartToPurchases=(purchases/views)*100 ```Find the ratio of site views to purchases.```
|eval cartToPurchases=(purchases/addtocart)*100 ```Find the ratio of add-to-cart actions to purchases.```
| table productName views addtocart purchases viewsToPurchases cartToPurchases ```Put all this data into a table.```
| rename productName AS "Product Name", views AS "Views", addtocart AS "Add To Cart", purchases AS "Purchases" ``` Rename some table columns.```
In the Search Bar, the comments for this search are color-coded to make the comments easier to find:
SPL commenting rules
You insert a comment into a search string by placing three backtick characters ( ``` ) before and after your comment text. Commented text is parsed by the search processor as a blank space.
Here's the full set of SPL comment rules:
|SPL comment rule||Example|
|A comment inserted before a generating command causes the search to fail. Common generating commands are
|You can insert comments anywhere in a line of SPL, except inside a quoted string.|
|Comments ignore the backslash escape character.|
|The search processor replaces comments with a space when the search is run.|
|Comments that do not start and end with a triple backtick cause a fatal syntax error. Single and double backticks within a comment are considered to be part of the comment.|
SPL comments support Unicode characters.
Use comments to troubleshoot a search
You can use the inline comments to troubleshoot a search.
The following search example is attempting to return the bytes for the individual indexes. However, the search has the wrong field in the
stats command <split-by clause>.
index=_internal source=*license* type=usage | stats sum(b) BY index
You can comment out portions of your search to help identify problems. In this search, the
stats portion of the search is commented out.
index=_internal source=*license* type=usage ```| stats sum(b) BY index```
The results show the correct name for the field. You need to specify idx as the field name instead of index.
Here is the revised search with the comments removed and the correct field in the
index=_internal source=*license* type=usage | stats sum(b) BY idx
(Thanks to Splunk user Runals for this example.)
Help reading searches
This documentation applies to the following versions of Splunk® Enterprise: 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 9.0.0