bin command syntax details

Syntax

The required syntax is in bold.

bin

[<bin-options>...]

<field> [AS <newfield>]

The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can specify the keyword in uppercase or lowercase.

Required arguments

field

Syntax: <field>

Description: Specify a field name.

Optional arguments

bin-options

Syntax: bins | minspan | span | <start-end> | aligntime

Description: Discretization options. See the Bin options section for the syntax and description for each of these options.

newfield

Syntax: AS <string>

Description: A new name for the field.

Bin options

bins

Syntax: bins=<int>

Description: Sets the maximum number of bins to discretize into.

minspan

Syntax: minspan=<span-length>

Description: Specifies the smallest span granularity to use to automatically infer the span from the data time range.

span

Syntax: span = <span-length> | <log-span>

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

<start-end>

Syntax: start=<num> | end=<num>

Description: Sets the minimum and maximum extents for numerical bins. The data in the field is analyzed and the beginning and ending values are determined. The start and end arguments are used when a span value is not specified.

You can use the start or end arguments only to expand the range, not to shorten the range. For example, if the field represents seconds the values are from 0-59. If you specify a span of 10, then the bins are calculated in increments of 10. The bins are 0-9, 10-19, 20-29, and so forth. If you do not specify a span, but specify end=1000, the bins are calculated based on the actual beginning value and 1000 as the end value.

If you set end=10 and the values are >10, the end argument has no effect.

aligntime

Syntax: aligntime=(earliest | latest | <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.

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. If the first number is supplied, it must be a real number >= 1.0 and < the base number. Base, if supplied, must be real number > 1.0 (strictly greater than 1).

Example: span=2log10

span-length

Syntax: <int>[<timescale>]

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

timescale

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

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

Default: sec

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

See also

bin command

bin command overview

bin command usage

bin command examples

Related information

Specifying time spans in the SPL2 Search Manual