Search Operators

Process data in meaningful ways and provide logic to queries with search operators. This page lists the available search operators in Sumo's search query language.

In this section, we'll introduce the following concepts:

📄️ accum

The accum operator calculates the cumulative sum of a field. It can be used to find a count by a specific time interval and can be used to find a total running count across all intervals.

📄️ as

The as operator is typically used in conjunction with other operators, but it can also be used alone to rename fields or to create new constant fields.

📄️ ASN lookup

Sumo Logic can lookup an Autonomous System Number (ASN) and organization name by an IP address. Any IP addresses that don't have an ASN will return null values.

📄️ backshift

The backshift operator helps you compare values as they change over time. It simply shifts the data points it is given and returns them in your results in a new field.

📄️ base64decode

The base64Decode operator takes a base64 string and converts it to an ASCII string. Input must be a valid base64 string. Invalid input is returned unaltered.

📄️ base64encode

The base64Encode operator takes an ASCII string and converts it to a base64 string.

The bin operator assigns output results to user defined bins. A bin is configured to hold a range of values that can be used for sorting results in a histogram and further aggregation. It is a quick and effective way to visualize the distribution of data.

📄️ cat

You can use the cat operator to view the contents of a lookup table. Not supported in live dashboards or scheduled searches.

📄️ cidr

Sumo Logic's three CIDR operators work with CIDR (Classless Inter-Domain Routing, sometimes pronounced "cider") notation to narrow the analysis of IPv4 networks to specific subnets. CIDR notations specify the routing prefix of IP addresses. Using the CIDR operators, you can determine the amount of traffic between network segments, review events from hosts within a specified network segment, or even use a not operator to find addresses that didn't originate from a particular network segment. CIDR operators can be used to compare the network segment of two IPv4 addresses, or just identify the network segment involved in particular messages.

📄️ compare

The compare operator can be used with the Time Compare button in the Sumo interface, which automatically generates the appropriate syntax and adds it to your aggregate query. See Time Compare for details. The following information can also be found documented in Time Compare.

📄️ concat

The concat operator allows you to concatenate or join multiple strings, numbers, and fields into a single user-defined field. It concatenates strings end-to-end and joins them into a new string that you define. For example, to concatenate the words "foot" and "ball" would give you "football". You can also use punctuation and spaces in quotes to concatenate strings in a readable way.

📄️ contains

The contains operator compares string values of two parsed fields and returns a boolean result based on whether the second field's value exists in the first.

📄️ decToHex

The decToHex operator converts a long value of 16 or fewer digits to a hexadecimal string using Two's Complement for negative values.

📄️ dedup

The dedup operator removes duplicate results. You have the option to remove consecutively and by specific fields. This allows you to filter your results to identify the most recent or last few events based on an identical combination of results.

📄️ diff

The diff operator calculates the rate of change in a field between consecutive rows. To produce results, diff requires that a specified field contain numeric data; any non-numerical values are removed from the search results.

📄️ fields

The fields operator allows you to specify which fields to display and their order in the results of a query. Use a fields operator to reduce the "clutter" of a search output that contains fields that aren't completely relevant to your query.

📄️ fillmissing

The fillmissing operator allows you to specify groups that should be represented in data output. When you run a standard group-by query, Sumo Logic only returns non-empty groups in the results. For example, if your query is grouping by timeslice, then only the timeslices that have data are returned.

📄️ filter

Use the filter operator to filter the output of a search based on the filtering criteria of a child query. The filter operator keeps only the records that match the filter criteria, allowing you to restrict search results to the most relevant information.

📄️ format

The format operator allows you to format and combine data from parsed fields. Numbers, strings, and dates can be formatted into a user-defined string. This allows data in logs, such as dates or currency amounts, to be formatted as human readable, when otherwise it would be hard to decipher.

📄️ formatDate

The formatDate operator allows you to format dates in log files as a string in the format you require, such as US date formatting, European formatting, and timestamps.

📄️ Geo Lookup (Map)

Sumo Logic can match a parsed IPv4 or IPv6 address to its geographical location on a map. To create the map the lookup operator matches parsed IP addresses to their physical location based on the latitude and longitude of where the addresses originated. The precision for latitude and longitude degrees is up to five decimal places.

📄️ geoip

Sumo Logic can match a parsed IPv4 or IPv6 address to its geographical location on a map chart. To create the map, the geoip operator matches parsed IP addresses to their physical location based on the latitude and longitude of where the addresses originated. The precision for latitude and longitude degrees is up to five decimal places.

📄️ hash

The hash operator uses a cryptographic hash algorithm to obscure data into a random string value. The operator supports MD5, SHA1, SHA2, and MurmurHash3 algorithms. The default is MD5 if no algorithm is specified.

📄️ haversine

The haversine operator returns the distance between latitude and longitude values of two coordinates in kilometers. Coordinates need to be positive or negative values based on being north/south or east/west, instead of using the terms N/S, E/W.

📄️ hexToAscii

The hexToAscii operator converts a hexadecimal string to an ASCII string.

📄️ hexToDec

The hexToDec operator converts a hexadecimal string of 16 or fewer characters to a long data type using Two's Complement for negative values.

📄️ if, ?

There are two forms of ternary expression you can use in Sumo Logic queries: one is constructed using the if operator, and the other uses the question mark (?) operator. The syntax varies slightly, but the results are equivalent. You can use the syntax you are most comfortable with.

📄️ in

The in operator returns a Boolean value: true if the specified property is in the specified object, or false if it is not.

📄️ ipv4ToNumber

The ipv4ToNumber operator allows you to convert an Internet Protocol version 4 (IPv4) IP address from the octet dot-decimal format to a decimal format. This decimal format makes it easier to compare one IP address to another, rather than relying on IP masking.

📄️ isNull, isEmpty, isBlank

The isNull operator checks a string and returns a boolean value: true if the string is null, or false if the string is not null.

📄️ isnumeric

The isNumeric operator checks whether a string is a valid Java number. Valid numbers include hexadecimals marked with the 0x or 0X qualifier, octal numbers, scientific notation and numbers marked with a type qualifier, like 123L.

📄️ isPrivateIP

The isPrivateIP operator checks if an IPv4 address is private and returns a boolean.

📄️ isPublicIP

The isPublicIP operator checks if an IPv4 address is public and returns a boolean.

📄️ isReservedIP

The isReservedIP operator checks if an IPv4 address is reserved as defined by RFC 5735 and returns a boolean.

📄️ isValidIP, isValidIPv4, isValidIPv6

The isValidIP operator checks if the value is a valid IP address. The isValidIPv4 and isValidIPv6 operators check if the value is a valid IPv4 or IPv6 address respectively.

📄️ join

The join operator combines records of two or more data streams. Results are admitted on-the-fly to allow real time tables to be built. Values common to each table are then delivered as search results. The join operator in Sumo Logic works much like an inner SQL join.

📄️ length

The length operator returns the number of characters in a string. You can use it in where clauses or to create new fields.

📄️ limit

The limit operator reduces the number of raw messages or aggregate results returned. If you simply query for a particular term, for example "error" without using an aggregation operator such as group by, limit will reduce the number of raw messages returned. If you first use group-by or other aggregation operator, the limit operator will reduce the number of grouped results instead.

📄️ lookup

The lookup operator can return one or more fields from a lookup table hosted by Sumo Logic and add the fields to the log messages returned by your query. You create a lookup table using the lookup UI or the Lookup API. You can populate a lookup table by uploading a CSV file using the Lookup API, or by using the save operator to save the results of a log query.

📄️ lookupContains

Use the lookupContains operator to determine whether a key exists in a lookup table. It will return a boolean value.

📄️ lookup (Classic)

The lookup (classic) operator maps data in your log messages to meaningful information saved in Sumo or on an HTTPS server. For example, you'd use a lookup operator to map "userID" to a real user's name. Or, you'd use a lookup operator to find deny-listed IP addresses.

📄️ Luhn

The luhn operator uses Luhn’s algorithm to check message logs for strings of numbers that may be credit card numbers and then validates them. It takes a string as an input, strips out all characters that are not numerals, and checks if the resulting string is a valid credit card number, returning true or false accordingly.

📄️ Manually cast data to string or number

Most data in Sumo Logic is stored as a string data type. Metadata fields are stored as string data and parsed fields are by default parsed as string type data. Sumo Logic will implicitly cast string data to a number type assuming it is clear that you need a number to perform an action, such as a math calculation or when using a function like sum or avg. However, if there is any ambiguity about whether a number is required, the data remains string data.

📄️ matches

The matches operator can be used to match a string to a wildcard pattern or an RE2 compliant regex. The operator returns a boolean value; the operator can be used with where or if operators.

📄️ now

The now returns the current epoch time in milliseconds. It can be used with the formatDate operator to get the formatted current time.

📄️ num

The num operator converts a field to a floating point number. Using num in a query is useful for sorting results by number instead of alphabetically, which is the default.

📄️ outlier

Given a series of time-stamped numerical values, using the outlier operator in a query can identify values in a sequence that seem unexpected, and would identify an alert or violation, for example, for a scheduled search.

📄️ predict

Uses a series of time-stamped numerical values to predict future values. The predict operator can be useful in the following cases:

📄️ queryEndTime()

The queryEndTime() operator returns the end time of the search time range in milliseconds. You can use it in combination with queryStartTime() to establish times and ranges for your non-continuous queries.

📄️ queryStartTime()

The queryStartTime() operator returns the start time of the search time range in milliseconds. You can use it in combination with queryEndTime() to establish times and ranges for your non-continuous queries.

📄️ queryTimeRange()

The queryTimeRange() operator returns the time duration for the query being executed in milliseconds. You can use it to establish time ranges for your continuous queries (CQs). This is a preferred operator for queries that are run in live dashboards or real time scheduled searches since it is more accurate than queryStartTime() and queryEndTime() operators in these cases.

📄️ replace

The replace operator allows you to replace all instances of a specified string with another string. You can specify the string to replace with a matching regex or literal text. You might use it to find all instances of a name and change it to a new name or to replace punctuation in a field with different punctuation. This operator is useful anytime you need to rename something.

📄️ rollingstd

The rollingstd operator finds the rolling standard deviation of a field, allowing you to identify changes over time.

📄️ save

The save operator allows you to save the results of a query to a lookup table you have already created, as described in Create a Lookup Table. You can use the lookup and cat operator to access the saved data.

📄️ save (Classic)

The save (classic) operator works with the classic Lookup Tables feature. For information about the new, more scalable Lookup Tables feature and the new save operator that works with it, see Lookup Tables and save. The new save operator allows you to merge new and changed rows, whereas, this classic save operator can only append to existing rows.

📄️ sessionize

The sessionize operator allows you to use an extracted value from one log message (generated from one system) to find correlating values in log messages from other systems. After you run sessionize, these related events are displayed on the same page. The thread of logs woven together is called a session.

📄️ smooth

The smooth operator calculates the rolling (or moving) average of a field, measuring the average of a value to "smooth" random variation. Smooth operator reveals trends in the data set you include in a query.

📄️ sort

The sort operator orders aggregated search results. The default sort order is descending. Then you can use the top or limit operators to reduce the number of sorted results returned.

📄️ substring

The substring operator allows you to specify an offset that will output only part of a string, referred to as a substring. You can use this operator to output just a part of a string instead of the whole string, for example, if you wanted to output an employee’s initials instead of their whole name.

📄️ threatip

The threatip operator correlates CrowdStrike's threat intelligence data based on IP addresses from your log data, providing security analytics that helps you to detect threats in your environment, while also protecting against sophisticated and persistent cyber-attacks.

📄️ timeslice

The timeslice operator aggregates data by time period, so you can create bucketed results based on a fixed interval (for example, five-minute buckets). Timeslice also supports creating a fixed-target number of buckets, for example, 150 buckets over the last 60 minutes.

📄️ tolowercase, touppercase

The toLowerCase operator takes a string and converts it to all lower case letters. The toUpperCase operator takes a string and converts it to all uppercase letters.

📄️ top

Use the top operator with the sort operator, to reduce the number of sorted results returned.

📄️ topk

Allows you to select the top values from fields and group them by fields. The topk operator can replace the top operator and adds the ability to choose the top of top.

📄️ total

The total operator inserts the sum of a set of fields into every row of the set. Unlike the sum operator, which produces an aggregate value, the total operator inserts the total value as a new column, enabling expressions that compare an individual value to the total.

📄️ tourl

The tourl operator provides you the ability to assign a short name that describes the URL. It is similar to creating a href for the URL with a short name. URLs are generally long and they don't tell you what information is displayed when the URL is opened. A common benefit of using this operator is to provide a description of a URL to display in dashboards.

📄️ trace

The trace operator acts as a highly sophisticated filter to connect the dots across different log messages. You can use any identifying value with a trace operator, such as a user ID, IP address, or session ID, to retrieve a comprehensive set of activity associated to that original ID.