Bin

This topic describes how to use the function in the .

Description

The Bin function puts continuous numerical values into discrete sets, or bins, by adjusting the value of <field> so that all of the items in a particular set have the same value.

Function Input/Output schema

Function Input

collection<record<R>>

This function takes in collections of records with schema R.

Function Output

collection<record<S>>

This function outputs the same collection of records but with a different schema S.

Syntax

bin

<span-options>

<field> [AS <result>]

How the Bin function works

Use the Bin function to group records by the numerical values in a field. Suppose your incoming data looks like the following:

Body	Timestamp	Hour and minute	Minutes from first timestamp
1	2019-08-22 01:56:37.000	01:56
2	2019-08-22 01:58:21.000	01:58	2 minutes
3	2019-08-22 01:59:59.000	01:59	3 minutes
4	2019-08-22 02:03:16.000	02:03	7 minutes
5	2019-08-22 02:05:43.000	02:05	9 minutes
6	2019-08-22 02:09:38.000	02:09	13 minutes
7	2019-08-22 02:12:31.000	02:12	16 minutes

You decide to add a Bin function to your pipeline that bins the streaming data using a 5 minute time span on the timestamp field.

...| bin span=5m timestamp;

The Bin function groups the timestamps in the timestamp field into 5 minutes intervals. The groups are:

Group	Timestamp values	Timestamp span range for each bin
1	2019-08-22 01:56:37.000 2019-08-22 01:58:21.000 2019-08-22 01:59:59.000	2019-08-22 01:56:37.000 --- 2019-08-22 02:01:36.000
2	2019-08-22 02:03:16.000 2019-08-22 02:05:43.000	2019-08-22 02:01:37.000 --- 2019-08-22 02:06:36.000
3	2019-08-22 02:09:38.000	2019-08-22 02:07:37.000 --- 2019-08-22 02:11:36.000
4	2019-08-22 02:12:31.000	2019-08-22 02:11:37.000 --- 2019-08-22 02:16:36.000

Required arguments

field

Syntax: string

Description: The name of the field to bin. The value of the field must be a numerical data type.

Example: timestamp

span

Syntax: <time-specifier>

Description: Sets the size of each bin, using a span length based on time or log-based span.

Example: 5m

Span options

log-span

Syntax: <num>log<num>

Description: Sets to logarithm-based span. The first number is a coefficient. The second number is the base. The coefficient must be a real number >= 1.0 and < the base number.

Example: span=2log10

span-length

Syntax: <int><timescale>

Description: A span of each bin. If discretizing based on the timestamp field or used with a timescale, this is treated as a time range. If not, this is an absolute bin length.

timescale

Syntax: <subseconds> | <sec> | <min> | <hr> | <day> | <month> | <year>

Description: Time scale units. If discretizing based on the timestamp field.

Default: sec

Time scale	Syntax	Description
<subseconds>	us | ms | cs | ds	Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds).
<sec>	s | sec | secs | second | seconds	Time scale in seconds.
<min>	m | min | mins | minute | minutes	Time scale in minutes.
<hr>	h | hr | hrs | hour	Time scale in hours.
<day>	d | day | days	Time scale in days.
<month>	mon | month | months	Time scale in months.
<year>	y | year | years	Time scale in years.

Optional arguments

aligntime

Syntax: aligntime=<time-specifier>

Description: Align the bin times to something other than base UTC time (epoch 0). The aligntime option is valid only when doing a time-based discretization. Ignored if span is in days, months, or years. Aligntime of earliest and latest are not supported.

Example: 4h

result

Syntax: AS <string>

Description: A new name for the field.

Example: time

Example

An example of a common use case follows. These examples assume that you have added the function to your pipeline.

SPL2 Example: Align the bins to 3 hours and set the span to 1 hour intervals from that time

This example assumes that you are in the SPL View.

... | bin aligntime=3h span=1h timestamp | ...;