top-k.bif.zeek

GLOBAL

Functions to probabilistically determine top-k elements.

Namespace:: GLOBAL

Summary

Functions

`topk_add`: `function`	Add a new observed object to the data structure.
`topk_count`: `function`	Get an overestimated count of how often a value has been encountered.
`topk_epsilon`: `function`	Get the maximal overestimation for count.
`topk_get_top`: `function`	Get the first k elements of the top-k data structure.
`topk_init`: `function`	Creates a top-k data structure which tracks size elements.
`topk_merge`: `function`	Merge the second top-k data structure into the first.
`topk_merge_prune`: `function`	Merge the second top-k data structure into the first and prunes the final data structure back to the size given on initialization.
`topk_size`: `function`	Get the number of elements this data structure is supposed to track (given on init).
`topk_sum`: `function`	Get the sum of all counts of all elements in the data structure.

Detailed Interface

Functions

topk_add

Type:: function (handle: opaque of topk, value: any) : any

Add a new observed object to the data structure.

Note

The first added object sets the type of data tracked by the top-k data structure. All following values have to be of the same type.

Parameters:

handle – the TopK handle.
value – observed value.

topk_count

Type:: function (handle: opaque of topk, value: any) : count

Get an overestimated count of how often a value has been encountered.

Note

The value has to be part of the currently tracked elements, otherwise 0 will be returned and an error message will be added to reporter.

Parameters:

handle – the TopK handle.
value – Value to look up count for.

Returns:

Overestimated number for how often the element has been encountered.

topk_epsilon

Type:: function (handle: opaque of topk, value: any) : count

Get the maximal overestimation for count.

Note

Same restrictions as for topk_count apply.

Parameters:

handle – the TopK handle.
value – Value to look up epsilon for.

Returns:

Number which represents the maximal overestimation for the count of this element.

topk_get_top

Type:: function (handle: opaque of topk, k: count) : any_vec

Get the first k elements of the top-k data structure.

Parameters:

handle – the TopK handle.
k – number of elements to return.

Returns:

vector of the first k elements.

topk_init

Type:: function (size: count) : opaque of topk

Creates a top-k data structure which tracks size elements.

Parameters:: size – number of elements to track.
Returns:: Opaque pointer to the data structure.

topk_merge

Type:: function (handle1: opaque of topk, handle2: opaque of topk) : any

Merge the second top-k data structure into the first.

Parameters:

handle1 – the first TopK handle.
handle2 – the second TopK handle.

Note

This does not remove any elements, the resulting data structure can be bigger than the maximum size given on initialization.

topk_merge_prune

Type:: function (handle1: opaque of topk, handle2: opaque of topk) : any

Merge the second top-k data structure into the first and prunes the final data structure back to the size given on initialization.

Note

Use with care and only when being aware of the restrictions this entails. Do not call topk_size or topk_add afterwards, results will probably not be what you expect.

Parameters:

handle1 – the TopK handle in which the second TopK structure is merged.
handle2 – the TopK handle in which is merged into the first TopK structure.

topk_size

Type:: function (handle: opaque of topk) : count

Get the number of elements this data structure is supposed to track (given on init).

Note

Note that the actual number of elements in the data structure can be lower or higher (due to non-pruned merges) than this.

Parameters:: handle – the TopK handle.
Returns:: size given during initialization.

topk_sum

Type:: function (handle: opaque of topk) : count

Get the sum of all counts of all elements in the data structure.

Note

This is equal to the number of all inserted objects if the data structure never has been pruned. Do not use after calling topk_merge_prune (will throw a warning message if used afterwards).

Parameters:: handle – the TopK handle.
Returns:: sum of all counts.