bin - Administrator Guide - Cortex XSIAM - Cortex

bin - Administrator Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Documentation

Product

Cortex XSIAM

Creation date

2024-03-06

Last date published

2024-10-13

Syntax

Quantity
```
bin <field> bins = <number>
```

Time Span

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

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 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
```