Bin - Reference Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR XQL Language Reference

Product
Cortex XDR
Creation date
2023-10-31
Last date published
2024-03-27
Category
Reference Guide
Abstract

Learn more about the Cortex Query Language bin stage to group events by quantity or time span.

Syntax

  • Quantity

    bin <field> bins = <number>
  • Time Span

    bin <field> span = <time> [timeshift = <epoch time> [timezone = "<time zone>"]]

Description

The bin stage groups 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 is 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> timezone = "<time zone>", which are both optional. You can configure the <time zone> offset using an hours offset, such as “+08:00”, or using a time zone name from the List of Supported Time Zones, such as "America/Chicago". The query still runs without defining the epoch time or time zone. If no timeshift = <epoch time> timezone = "<time zone>" is set, the query runs according to last time set in the log.

Note

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

W

weeks

MO

months

Y

years

Note

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 Examples

    • With a time zone configured using an hours offset:

      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, and includes a time zone using an hours offset of “+08:00”.

      dataset = xdr_data 
      | bin _time span = 1h timeshift = 1615353499 timezone = “+08:00”
      | limit 1000
      
    • With a time zone name configured:

      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, and includes an "America/Los_Angeles" time zone.

      dataset = xdr_data
      | bin _time span = 1h timeshift = 1615353499 timezone = “America/Los_Angeles”
      | limit 1000