base/bif/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.

See also: topk_init, topk_get_top, topk_count, topk_epsilon, topk_size, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_init, topk_add, topk_get_top, topk_epsilon, topk_size, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_init, topk_add, topk_get_top, topk_count, topk_size, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_init, topk_add, topk_count, topk_epsilon, topk_size, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_add, topk_get_top, topk_count, topk_epsilon, topk_size, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_init, topk_add, topk_get_top, topk_count, topk_epsilon, topk_size, topk_sum, topk_merge_prune

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.

See also: topk_init, topk_add, topk_get_top, topk_count, topk_epsilon, topk_size, topk_sum, topk_merge

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.

See also: topk_init, topk_add, topk_get_top, topk_count, topk_epsilon, topk_sum, topk_merge, topk_merge_prune

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.

See also: topk_init, topk_add, topk_get_top, topk_count, topk_epsilon, topk_size, topk_merge, topk_merge_prune