Bin

Cortex XDR XQL bin stage enables grouping events by quantity or time.

Synopsis

  • Quantity
    bin <
    field
    > bins = <
    number
    >
  • Time Span
    bin <
    field
    > span = <
    time
    > timeshift = <
    epoch time
    >

Description

The
bin
stage enables you to group events by quantity or time span. The most common use case is for timecharts.
You can add the
bin
stage to your queries using two different formats depending on whether you are grouping events by quantity or time span. Currently, the
bin
stage only supported using the equal sign (
=
) operator in your queries without any boolean operators (
and
,
or
).
When you group events of a particular field by quantity, the
bin
stage is used with
bins
to define how to divide the events.
When you group events of a particular field by time, the
bin
stage is used with
span = <time>
, where
<time>
is a combination of a number and time suffix. Set one time suffix from the list of available options listed in the table below. In addition, you can define a particular start time for grouping the events in your query according to the Unix epoch time by setting
timeshift = <epoch time>
. Yet, this is optional. The query still runs without defining the epoch time. If no
timeshift = <epoch time>
is set, the query runs according to last time set in the log.
When you group events by quantity, the
<field>
in the
bin
stage must be a number, and when you group by time, the
<field>
must be a date type. Otherwise, your query will fail.

Time Suffixes

Time Suffix
Description
MS
milliseconds
S
seconds
M
minutes
H
hours
D
days
MO
months
Y
years
The time suffix is not case sensitive.

Examples

  • Quantity Example
    Return a maximum of 1,000
    xdr_data
    records with the events of the
    action_total_upload
    field grouped by 50MB. Records with the
    action_total_upload
    value set to 0 or null are not included in the results.
    dataset = xdr_data | filter action_total_upload != 0 and action_total_upload != null | bin action_total_upload bins = 50 | limit 1000
  • Time Span Example
    Return a maximum of 1,000
    xdr_data
    records with the events of the
    _time
    field grouped by 1-hour increments starting from the epoch time 1615353499.
    dataset = xdr_data | bin _time span = 1h timeshift = 1615353499 | limit 1000

Recommended For You