search

Evaluates each input record against a filter expression and outputs only the records that match the condition.

Command properties

Syntax

Options

limit=N

Maximum number of records to output. Once the number of matching records reaches this value, the command stops processing further input.

Target

EXPR

Filter expression. You can combine conditions using logical operators (and, or, not) and comparison operators (==, !=, >, >=, <, <=). Wildcard (*) string matching is supported.

Output fields

All fields of the input records are passed through unchanged. The search command does not add or remove fields.

Error codes

Parsing errors

N/A

Runtime errors

N/A

Description

The search command evaluates the expression against each input record, determines whether it is true or false, and passes only records where it is treated as true to the next command. What counts as true differs by series. In the 5.0 series (through 5.0.2605.2), boolean true or any non-null value is treated as true — only null and boolean false are treated as false. In the 4.0 series starting with 4.0.2609.0, null, boolean false, the numbers 0 and NaN, an empty string, and an empty list, array, or map are all treated as false, so those records are filtered out; every other value is treated as true. This is the same criteria whether you use the expression by itself or combine it with and/or.

• Filtering only: Does not create new fields or modify existing ones. Use the eval command to add fields.
• Early termination: When the number of records specified by the limit option is reached, the query completes without processing further input.
• Handling of a missing field: If a record does not have the field at all, its value evaluates to null, which the above criteria treat as false, so the record is filtered out.

Examples

1. Filter by a specific HTTP status code

   table WEB_APACHE | search status == "403"
   

   Filters only access requests with HTTP status code 403 (Forbidden).

2. Filter requests with large responses

   table WEB_APACHE | search sc_bytes >= "5000000"
   

   Filters large file download requests where the response size is 5 MB or larger, to identify abnormal data exfiltration.

3. Filter logs containing an error message

   table SYSTEM_EVENT_LOG | search contains(message, "authentication failed")
   

   Filters only authentication-failure events where the message field contains "authentication failed".

4. Identify suspicious activity with compound conditions

   table WEB_APACHE | search (src_ip == "203.0.113.15" or src_ip == "203.0.113.89") and status >= "400"
   

   Filters requests from specific IP addresses (203.0.113.15 or 203.0.113.89) with error status codes (400 or higher).

5. Extract top events using the limit option

   table SYSTEM_EVENT_LOG | search limit=50 status == 500
   

   Extracts the first 50 records with HTTP status code 500 (server error), then completes the query.

6. Exclude bot traffic

   table WEB_APACHE | search not contains(user_agent, "bot")
   

   Extracts only genuine user access requests whose user_agent field does not contain "bot".

7. The number 0 and an empty string — result differs by series

   json "[{'flag': 1}, {'flag': 0}, {'flag': ''}, {'flag': 'x'}]" | search flag
   | # 5.0 series (through 5.0.2605.2): all 4 records are output (0 and '' are non-null, so treated as true).
   | # 4.0 series (4.0.2609.0 and later): only the records where flag is 1 or 'x' are output; 0 and the empty string are treated as false and excluded.
   

Change history