Skip to content
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

# Query Functions

LogScale query functions take a set of events, parameters, or configurations. They produce, reduce, or modify values within that set, or in the events themselves within a query pipeline.

The Query Functions table is an alphabetical listing of all LogScale query functions:

Table: Query Functions

Function | Type | Default Argument | Availability | Description
--- | --- | --- | --- | ---
`array:append(array, values)` | array, data-manipulation | `array` | added in 1.145 | Appends single or multiple values to an array, or creates a new array if it does not already exist.
`array:contains(array, value)` | array, data-manipulation, filter | `array` |  | Checks whether the given value matches any of the values of the array and excludes the event if no value matches.
`array:eval(array, [asArray], function, [var])` | array | `array` |  | Evaluates the function argument on all values in the array under the array argument overwriting the array.
`array:filter(array, [asArray], function, [var])` | array, data-manipulation, filter | `array` |  | Drops entries from the input array using the given filtering function.
`array:length(array, [as])` | array, array-length | `array` |  | Counts the number of elements in an array.
`array:reduceAll(array, function, var)` | aggregate, array, data-manipulation | `array` |  | Computes a value from all events and array elements of the specified array.
`array:regex(array, [flags], regex)` | array, filter, regular-expression | `array` |  | Checks whether the given pattern matches any of the values of the array and excludes the event from the search result.
`asn([as], [field])` | network | `field` |  | Determines autonomous system number and organization associated.
`avg([as], field)` | aggregate, statistics | `field` |  | Calculates the average for a field of a set of events.
`base64Decode([as], [charset], field)` | parsing | `field` |  | Performs Base64 decoding of a field.
`bitfield:extractFlags(field, [onlyTrue], output)` | data-manipulation |  |  | Interprets an integer as a bit field and extracts the specified flags.
`bucket([buckets], [field], [function], [limit], [minSpan], [span], [timezone], [unit])` | aggregate | `span` |  | Extends the `groupBy()` function for grouping by time.
`callFunction([as], field, function)` | aggregate | `function` |  | Calls the named function on a field over a set of events.
`cidr([column], field, [file], [negate], [subnet])` | filter, network | `field` |  | Filters events using CIDR subnets.
`coalesce([as], expressions, [ignoreEmpty])` | data-manipulation | `expressions` |  | Selects the value of the first expression from a list of expressions
`collect(fields, [limit], [multival], [separator])` | aggregate | `fields` |  | Collects fields from multiple events into one event.
`communityId([as], destinationip, [destinationport], [icmpcode], [icmptype], proto, [seed], sourceip, [sourceport])` | network |  |  | Computes the Community ID, a standard for hashing network flows.
`concat([as], field)` | data-manipulation, string | `field` |  | Concatenates the values of a list of fields into a value in a new field.
`concatArray([as], field, [from], [prefix], [separator], [suffix], [to])` | array, data-manipulation, string | `field` |  | Concatenates values of all fields with same name and an array suffix into a new field.
`copyEvent(type)` | data-manipulation, event | `type` |  | Duplicates an event so that the pipeline will see both events.
`count([as], [distinct], [field])` | aggregate, statistics | `field` |  | Counts given events.
`counterAsRate([as], field)` | aggregate | `field` |  | Calculates the rate for a counter field.
`createEvents(rawstring)` | aggregate-testing, event | `rawstring` |  | Generates temporary events as part of the query.
`crypto:md5([as], field)` | hash | `field` |  | Computes a cryptographic MD5-hashing of an input string.
`default(field, [replaceEmpty], value)` | event, format | `value` |  | Creates a field to given parameter and given value.
`drop(fields)` | data-manipulation, event | `fields` |  | Removes specified fields from each event.
`dropEvent()` | data-manipulation, event |  |  | Drops completely an event in parser pipeline to stop it from being ingested.
`duration([as], duration)` | time-date | `duration` |  | Computes the number of milliseconds denoted by a human-readable specification.
`end([as])` | time-date | `as` |  | Assign the end of the search time interval to the field provided by parameter `as`.
`eval()` | data-manipulation |  |  | Creates a new field by evaluating the provided expression.
`eventFieldCount([as])` | event |  |  | Computes number of fields event uses internally for the values.
`eventInternals([prefix])` | event |  |  | Add a set of fields describing the storage locations of this event.
`eventSize([as])` | event |  |  | Determines the number of bytes that this event uses internally for the values, not counting the bytes for storing the field names.
`fieldset()` | event |  |  | Retrieves a list of available fields.
`fieldstats([limit])` | aggregate, event |  |  | Displays statistics about fields.
`findTimestamp([addErrors], [as], [field], [timezone], [timezoneAs])` | time-date |  |  | Finds timestamp in given field and parses, trying multiple timestamp formats.
`format([as], field, format, [timezone])` | data-manipulation, format | `format` |  | Formats a string using printf-style.
`formatDuration([as], field, [from], [precision])` | format, time-date | `field` |  | Formats a duration into a more readable string.
`formatTime(as, [field], format, [locale], [timezone], [unit])` | format | `format` |  | Formats a string according to `strftime()`.
`geography:distance([as], lat1, lat2, lon1, lon2)` | geolocation |  |  | Calculates the distance between two geographical coordinates along an ideal earth surface.
`geohash([as], [lat], [lon], [precision])` | geolocation |  |  | Calculates a geohash value given two fields representing latitude and longitude.
`getField([as], source)` | data-manipulation |  |  | Reads dynamically-named fields that are computed from an expression.
`groupBy(field, [function], [limit])` | aggregate | `field` |  | Groups events by specified fields and executes aggregate functions on each group.
`hash([as], field, [limit], [seed])` | event, hash | `field` |  | Computes a non-cryptographic hash of a list of fields.
`hashMatch([bits], [field], [hash], input, salt)` | security | `input` |  | Calculates a secure hash of a field and uses it to match events as a filter.
`hashRewrite([as], [bits], field, [hash], [replaceInRawstring], salt)` | security | `field` |  | Calculates a secure hash of a field for storing in the event.
`head([limit])` | aggregate | `limit` |  | Returns the oldest events from an event stream.
`if([as], condition, else, then)` | condition | `condition` |  | Computes a value in one of two ways (evaluates one of two expressions).
`in(field, [ignoreCase], values)` | comparison, filter | `field` |  | Filters records by values where field is in given values.
`ioc:lookup([confidenceThreshold], field, [include], [prefix], [strict], type)` | security | `field` |  | Look up IOCs (Indicators of Compromise).
`ipLocation([as], [field])` | geolocation, network | `field` |  | Determines country, city, longitude, and latitude for given IP address.
`join([end], field, [include], [key], [limit], [live], [max], [mode], query, [repo], [start], [view])` | join | `query` |  | Join two LogScale searches.
`json:prettyPrint([as], [field], [step], [strict])` | data-manipulation, format | `field` |  | More readable output to a JSON field.
`kvParse([as], [excludeEmpty], [field], [onDuplicate], [override], [separator], [separatorPadding])` | parsing | `field` |  | Key-value parse events.
`length([as], field)` | string | `field` |  | Computes the number of characters in a string field.
`linReg([prefix], x, y)` | aggregate |  |  | Computes linear relationship model between two variables using least-squares fitting.
`lower([as], field, [locale], [type])` | format | `field` |  | Changes text of a given string field to lower case letters.
`lowercase(field, [include], [locale])` | data-manipulation, format, string | `field` |  | Changes field name or content to lowercase for parsers.
`match([column], field, file, [glob], [ignoreCase], [include], [mode], [nrows], [strict])` | filter | `file` |  | Searches text using a CSV or JSON file and can enhance entries.
`math:abs([as], field)` | math | `field` |  | Calculates the absolute value of a field; the result is always a positive number or 0.
`math:arccos([as], field)` | math | `field` |  | Calculates the arc cosine of a field.
`math:arcsin([as], field)` | math | `field` |  | Calculates the arc sine of a field.
`math:arctan([as], field)` | math | `field` |  | Calculates the arc tangent of a value.
`math:arctan2([as], x, y)` | math |  |  | Calculates the arc tangent of a value.
`math:ceil([as], field)` | math | `field` |  | Rounds field value to smallest integer that's larger than or equal to it.
`math:cos([as], field)` | math | `field` |  | Calculates the cosine of a field.
`math:cosh([as], field)` | math |  |  | Computes the hyperbolic cosine of a double field.
`math:deg2rad([as], field)` | math | `field` |  | Converts angles from degrees to radians.
`math:exp([as], field)` | math | `field` |  | Calculates Euler's number e raised to the power of a double value in a field.
`math:expm1([as], field)` | math | `field` |  | Calculates the exponential value of a number minus 1.
`math:floor([as], field)` | math | `field` |  | Computes the largest integer value not greater than the field value given.
`math:log([as], field)` | math | `field` |  | Calculates the natural logarithm (base e) of the value in a double field.
`math:log10([as], field)` | math | `field` |  | Calculates the base 10 logarithm of a double field.
`math:log1p([as], field)` | math | `field` |  | Calculates the natural logarithm of the sum of field's value and 1.
`math:log2([as], field)` | math | `field` |  | Calculates the base 2 logarithm of a double field.
`math:mod([as], divisor, field)` | math | `field` |  | Calculates the floor modulus of field value and the divisor.
`math:pow([as], exponent, field)` | math | `field` |  | Calculates the field value to the exponent power.
`math:rad2deg([as], field)` | math | `field` |  | Converts angles from radians to degrees.
`math:sin([as], field)` | math | `field` |  | Calculates the sine of a field.
`math:sinh([as], field)` | math | `field` |  | Calculates the hyperbolic sine of a double field.
`math:sqrt([as], field)` | math | `field` |  | Calculates the rounded positive square root of a double field.
`math:tan([as], field)` | math | `field` |  | Calculates the trigonometric tangent of an angle in a field.
`math:tanh([as], field)` | math | `field` |  | Calculates the hyperbolic tangent of a field.
`max([as], field, [type])` | aggregate, statistics | `field` |  | Finds the largest number for the specified field over a set of events.
`min([as], field, [type])` | aggregate, statistics | `field` |  | Finds the smallest number for the specified field over a set of events.
`now([as])` | time-date | `as` |  | Assign the current time to the field provided by parameter `as`.
`parseCEF([field], [headerprefix], [keeplabels], [labelprefix], [prefix])` | data-manipulation, parsing | `field` |  | Parses CEF version 0.x encoded messages.
`parseCsv(columns, [delimiter], [excludeEmpty], field, [trim])` | data-manipulation, parsing | `field` |  | Parses a CSV-encoded field into known columns.
`parseFixedWidth(columns, [field], [trim], widths)` | parsing | `field` |  | Parses a fixed width-encoded field into known columns.
`parseHexString([as], [charset], field)` | data-manipulation, math, parsing | `field` |  | Parses input from hex encoded bytes, decoding resulting bytes as a string.
`parseInt([as], [endian], field, [radix])` | math, parsing | `field` |  | Converts an integer from any radix or base to base-ten, decimal radix.
`parseJson([exclude], [excludeEmpty], field, [handleNull], [include], [prefix], [removePrefixes])` | data-manipulation, parsing | `field` |  | Parses specified fields as JSON.
`parseLEEF([delimiter], [field], [headerprefix], [keeplabels], [labelprefix], [parsetime], [prefix], [timezone])` | data-manipulation, parsing | `field` |  | Parses LEEF version 1.0 and 2.0 encoded messages.
`parseTimestamp([addErrors], [as], [caseSensitive], field, [format], [timezone], [timezoneAs])` | parsing, time-date | `format` |  | Parses a string into a timestamp.
`parseUri([defaultBase], field, [prefix])` | parsing | `field` |  | Extracts URI components from a field.
`parseUrl([as], [field])` | parsing | `field` |  | Extracts URL components from a field.
`parseXml(field, [prefix], [strict])` | parsing | `field` |  | Parses specified field as XML.
`percentile([accuracy], [as], field, [percentiles])` | aggregate, statistics | `field` |  | Finds one event with a field for each percentile specified.
`range([as], field)` | aggregate, statistics | `field` |  | Finds numeric range between smallest and largest numbers for field over a set of events.
`rdns([as], field, [limit], [server])` | aggregate, network | `field` |  | Events using RDNS lookup.
`readFile(file, [include], [limit])` | data-manipulation, event | `file` |  | Uses a `.csv` lookup file or ad-hoc table as data input for the query.
`regex([field], [flags], [limit], regex, [repeat], [strict])` | filter, regular-expression, string | `regex` |  | Extracts new fields using a regular expression.
`rename([as], field)` | data-manipulation, event | `field` |  | Renames one or more given fields.
`replace([as], [field], [flags], regex, [replacement], [with])` | data-manipulation, regular-expression, string | `regex` |  | Replaces each substring that matches given regular expression with given replacement.
`reverseDns([as], field, [limit], [server])` | transformation | `field` |  | Performs reverse DNS lookups.
`round([as], field, [how])` | math | `field` |  | Rounds an input field up or down, depending on which is nearest.
`sample([field], [percentage])` | filter, statistics | `percentage` |  | Samples the event stream.
`sankey(source, target, [weight])` | aggregate, data-manipulation, widget |  |  | Produces data compatible with Sankey widget.
`select(fields)` | event | `fields` |  | Used to specify a set of fields to select from each event.
`selectFromMax(field, include)` | aggregate | `field` |  | Selects event with the largest value for the specified field.
`selectFromMin(field, include)` | aggregate | `field` |  | Selects event with the smallest value for the specified field.
`selectLast(fields)` | aggregate | `fields` |  | Specify fields to select from events, keeping value of most recent event for each field.
`selfJoin([collect], field, [limit], [postfilter], [prefilter], [select], where)` | join | `field` |  | Used to collate data from events that share a key.
`selfJoinFilter(field, [prefilter], where)` | filter, join | `field` |  | Runs query to determine IDs, and then gets all events containing one of them.
`series(collect, [endmatch], [maxduration], [maxpause], [memlimit], [separator], [startmatch])` | aggregate, data-manipulation | `collect` |  | Collects a series of values for selected fields from multiple events into one or more events.
`session([function], [maxpause])` | aggregate, statistics | `function` |  | Collects events into sessions, and aggregates them.
`setField(target, value)` | data-manipulation |  |  | Sets fields whose names are not known but computed from an expression.
`shannonEntropy([as], field)` | network | `field` |  | Calculates a entropy measure from a string of characters.
`sort([field], [limit], [order], [reverse], [type])` | aggregate | `field` |  | Sorts events by their fields.
`split([field], [strip])` | array, data-manipulation | `field` |  | Splits an event structure created by a JSON array into distinct events.
`splitString([as], by, [field], [index])` | array, data-manipulation, regular-expression, string | `field` |  | Splits a string by specifying a regular expression by which to split.
`start([as])` | time-date | `as` |  | Assign the start of the search time interval to the field provided by parameter `as`.
`stats([function])` | aggregate, statistics | `function` |  | Used to compute multiple aggregate functions over the input.
`stdDev([as], field)` | aggregate, statistics | `field` |  | Calculates the standard deviation for a field over a set of events.
`stripAnsiCodes([as], field)` | data-manipulation, string | `field` |  | Removes ANSI color codes and movement commands.
`subnet([as], bits, field)` | network | `field` |  | Computes a subnet from a IPV4 field.
`sum([as], field)` | aggregate | `field` |  | Calculates the sum for a field over a set of events.
`table(fields, [limit], [order], [reverse], [sortby], [type])` | aggregate, widget | `fields` |  | Used to create a widget to present the data in a table.
`tail([limit])` | aggregate | `limit` |  | Returns the newest events from an event stream.
`test(expression)` | comparison, event, filter | `expression` |  | Evaluates boolean expression and filters events.
`text:contains(string, substring)` | data-manipulation, filter | `string` | added in 1.145 | Tests if a specific substring is present within a given string.
`time:dayOfMonth([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the day of the month of a timestamp field.
`time:dayOfWeek([as], field, [timezone], [timezoneField])` | time-date | `field` |  | Gets day of week from 1 (Mon) to 7 (Sun) of a timestamp.
`time:dayOfWeekName([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the English display name of day of the week of a timestamp field.
`time:dayOfYear([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the day of the year of a timestamp field, from 1 to 365, or 366 in a leap year.
`time:hour([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the hour (24-hour clock) of a timestamp field.
`time:millisecond([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the millisecond of a timestamp field.
`time:minute([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the minute value of a timestamp field.
`time:month([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the month of a timestamp field (from 1 to 12).
`time:monthName([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the English name of month of a timestamp field (for example, January).
`time:second([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the second of a timestamp field.
`time:weekOfYear([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the week number within a year of a timestamp, a value from 1 to 53.
`time:year([as], [field], [timezone], [timezoneField])` | time-date | `field` |  | Gets the year of a timestamp field.
`timeChart([buckets], [function], [limit], [minSpan], [series], [span], [timezone], [unit])` | aggregate, widget | `series` |  | Used to draw a linechart where the x-axis is time.
`tokenHash([as], field)` | hash, string | `field` |  | Calculates a hash by tokenizing the input string (split by spaces), creating a hash for each token and then added the result together. This generates the same hash value, even if the order of the individual values in the source string is different.
`top([as], [error], field, [limit], [max], [percent], [rest], [sum])` | aggregate | `field` |  | Finds the top results based on a given field.
`transpose([column], [header], [limit], [pivot])` | aggregate, data-manipulation | `pivot` |  | Transposes a query results set by creating an event for each attribute.
`unit:convert([as], [binary], field, [from], [keepUnit], [to], [unit])` | data-manipulation, math | `field` |  | Converts values between different units.
`upper([as], field, [locale])` | data-manipulation, format | `field` |  | Changes contents of a string field to upper case letters.
`urlDecode([as], field)` | data-manipulation, format, network | `field` |  | URL-decodes the contents of a string field.
`urlEncode([as], field, [type])` | data-manipulation, format, network | `field` |  | URL encodes the contents of a string field.
`wildcard([field], [ignoreCase], pattern)` | filter | `pattern` |  | Performs a wildcard pattern search with optional case insensitivity.
`window([buckets], [function], [span])` | aggregate | `function` |  | Computes aggregate functions over a sliding window of data.
`worldMap([ip], [lat], [lon], [magnitude], [precision])` | aggregate, widget |  |  | Used to produce data compatible with the World Map widget.
`writeJson([as], [field])` | data-manipulation, format | `field` |  | Writes data, including fields, as a JSON object.
`xml:prettyPrint([as], field, [step], [strict], [width])` | data-manipulation | `field` |  | Nicer output to an XML field.

#### Enter search term