User Manual

 


About the search language

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

About the search language

When you search, you're either retrieving events from an index or summarizing results into a tabular or visual format. A Splunk search consists of search terms, search commands, functions, arguments, and clauses.

The search terms are keywords, phrases, boolean expressions, key/value pairs, etc. that specify what you want to retrieve from the index(es).

The matching events can then be passed as inputs into a search command using a pipe character, "|". This enables you to refine or enhance the data at each step along the pipeline. The "search pipeline" refers to the structure of a Splunk search, in which consecutive commands are chained together using a pipe character that tells Splunk to use the output or result of one command as the input for the next command.

Search commands tell Splunk what to do to the events you retrieved from the indexes. For example, you might use commands to filter unwanted information, extract more information, evaluate new fields, calculate statistics, reorder your results, or create a chart. Some commands have functions and arguments associated with them. These functions and their arguments enable you to specify how the commands act on your results and which fields to act on; for example, how to create a chart, what kind of statistics to calculate, and what fields to evaluate. Some commands also enable you to use clauses to specify how you want to group your search results. For the complete list of search commands, refer to the Search Reference manual and the individual search command reference topic for its syntax and usage.

The anatomy of a search

To better understand how search commands act on your data, it helps to visualize all your indexed data as a table. Each search command redefines the shape of your table. This topic illustrates how the different types of search commands act on your data.

Also, if you want to just jump right in and start searching, the Search command cheatsheet is a quick reference complete with descriptions and examples.

Anatomy of a search.png

Start with a table of indexed data

Before you search, think of your indexed data as a table. In this table, each indexed event is a row. Each of these events contain indexed or extracted fields, which are name and value pairs of information. In this table, the field names are columns, and the field values are the individual cells in each row.

You can approximate this data table in Splunk if you search for everything in an index and select the Events Table view for your results. Restrict your time range to a short period of time, such as the Last 15 minutes or last hour and search for index=_internal. Then, use the field picker to add all the fields to the results view. Your table should look similar to this:

HowCmdsWork 1.png


This table shows columns for a few of the internal and default fields Splunk automatically adds to the data. In your own results, you should see columns for many more default fields. These default columns are followed by columns for all other extracted fields.

Search at the beginning or elsewhere

You can search at any point in the search command pipeline. A search results in a smaller table that contains the exact same number of columns minus the rows of events that did not match the search conditions. Searches do not change any cell values.

Searching commands: crawl, savedsearch, search.

Example: Search for matching host.

Let's say you have this beginning table:

You want to find all the HTTP servers in your events:

host=http*

Filter unwanted information

Filtering commands produce the same results as a search: a smaller table. However, depending on the search command, the smaller table may have fewer rows or fewer columns. Filtering commands also do not change any cell values.

Filtering commands: dedup, fields, head, localize, regex, search, set, tail, where.

The following 3 examples use the same beginning table from the previous search example.

Example: Remove duplicates of cell values in a column with dedup.

You want to remove duplicate events based on the hostname:

* | dedup host

Example: Remove or keep columns with fields.

You want to see only the host and sourcetype information:

* | fields + host, sourcetype

Example: Remove all rows after the number specified with head.

You want to see only the first three results of your search:

* | head 3

Evaluate your data

Evaluating commands can change specific column names or cell values. Depending on the command, evaluating commands may or may not add columns.

Evaluating commands: abstract, addtotals, bucket, cluster, collect, convert, correlate, diff, eval, eventstats, format, fillnull, format, kmeans, makemv, mvcombine, mvexpand, nomv, outlier, overlap, replace, strcat, transaction, typelearner, xmlunescape.

The next example uses this beginning table; each succeeding example builds on it.

Example: Create a new column where the cells are the results of an eval expression.

You want to create a new field for the sum of count1 and count2 values.

* | eval sum=count1+count2

Example: Change one or more column names with rename. This does not create a new column.

Using the previous resulting table, you want to change the column name of sum to total

* | rename sum as total

Example: Overwrite cell values with replace. This does not create a new column.

Using the previous resulting table, you want to change all host values that are host1 to localhost.

* | replace host1 with localhost in host

Example: Create new columns for the concatenated string value of other columns with eval.

Using the previous resulting table, you want to add a new column called hosttype that combines the host and sourcetype values, separated by a hyphen.

* | eval hostsourcetype=host."-".sourcetype

Reorder your results

Reordering commands sort the rows of the entire table based on the values of the specified column name. These commands do not add or remove rows and do not change any cell values.

Reordering commands: reverse, sort.

Example: Reorder the table with sort.

Using the previous resulting table, reorder the rows in ascending order of total.

* | sort + total

Extract more information

Extracting commands create new rows or columns from information found in the _raw column for each row.

Extracting commands: addinfo, extract/kv, iplocation, multikv, rex, top, typer, xmlkv.

Example: Create new columns from key/value pairs in your events with extract/kv.

Example: Create new rows from information found in multi-line or tabular events with multikv.

Transform your data into statistical results

Transforming commands create an entirely new table of data. These commands change the specified cell values for each event into numerical values that Splunk can use for statistical purposes.

Transforming commands: chart, contingency, highlight, rare, stats, timechart, top.

Example: chart

This documentation applies to the following versions of Splunk: 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!