On October 30, 2022, all 1.2.x versions of the Splunk Data Stream Processor will reach its end of support date. See the Splunk Software Support Policy for details.
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: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 | ...;
Batch Records | Break Events |
This documentation applies to the following versions of Splunk® Data Stream Processor: 1.2.0, 1.2.1-patch02, 1.2.1, 1.2.2-patch02, 1.2.4, 1.2.5, 1.3.0, 1.3.1, 1.4.0, 1.4.1, 1.4.2, 1.4.3, 1.4.4, 1.4.5, 1.4.6
Feedback submitted, thanks!