:tocdepth: 3

base/bif/bloom-filter.bif.zeek
==============================
.. zeek:namespace:: GLOBAL

Functions to create and manipulate Bloom filters.

:Namespace: GLOBAL

Summary
~~~~~~~
Functions
#########
============================================================ ============================================================================================
:zeek:id:`bloomfilter_add`: :zeek:type:`function`            Adds an element to a Bloom filter.
:zeek:id:`bloomfilter_basic_init`: :zeek:type:`function`     Creates a basic Bloom filter.
:zeek:id:`bloomfilter_basic_init2`: :zeek:type:`function`    Creates a basic Bloom filter.
:zeek:id:`bloomfilter_clear`: :zeek:type:`function`          Removes all elements from a Bloom filter.
:zeek:id:`bloomfilter_counting_init`: :zeek:type:`function`  Creates a counting Bloom filter.
:zeek:id:`bloomfilter_decrement`: :zeek:type:`function`      Decrements the counter for an element that was added to a counting bloom filter in the past.
:zeek:id:`bloomfilter_internal_state`: :zeek:type:`function` Returns a string with a representation of a Bloom filter's internal
                                                             state.
:zeek:id:`bloomfilter_intersect`: :zeek:type:`function`      Intersects two Bloom filters.
:zeek:id:`bloomfilter_lookup`: :zeek:type:`function`         Retrieves the counter for a given element in a Bloom filter.
:zeek:id:`bloomfilter_merge`: :zeek:type:`function`          Merges two Bloom filters.
============================================================ ============================================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Functions
#########
.. zeek:id:: bloomfilter_add
   :source-code: base/bif/bloom-filter.bif.zeek 90 90

   :Type: :zeek:type:`function` (bf: :zeek:type:`opaque` of bloomfilter, x: :zeek:type:`any`) : :zeek:type:`any`

   Adds an element to a Bloom filter. For counting bloom filters, the counter is incremented.


   :param bf: The Bloom filter handle.


   :param x: The element to add.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_lookup bloomfilter_clear
      bloomfilter_merge bloomfilter_decrement

.. zeek:id:: bloomfilter_basic_init
   :source-code: base/bif/bloom-filter.bif.zeek 30 30

   :Type: :zeek:type:`function` (fp: :zeek:type:`double`, capacity: :zeek:type:`count`, name: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`opaque` of bloomfilter

   Creates a basic Bloom filter.


   :param fp: The desired false-positive rate.


   :param capacity: the maximum number of elements that guarantees a false-positive
             rate of *fp*.


   :param name: A name that uniquely identifies and seeds the Bloom filter. If empty,
         the filter will use :zeek:id:`global_hash_seed` if that's set, and
         otherwise use a local seed tied to the current Zeek process. Only
         filters with the same seed can be merged with
         :zeek:id:`bloomfilter_merge`.


   :returns: A Bloom filter handle.

   .. zeek:see:: bloomfilter_basic_init2 bloomfilter_counting_init bloomfilter_add
      bloomfilter_lookup bloomfilter_clear bloomfilter_merge global_hash_seed

.. zeek:id:: bloomfilter_basic_init2
   :source-code: base/bif/bloom-filter.bif.zeek 52 52

   :Type: :zeek:type:`function` (k: :zeek:type:`count`, cells: :zeek:type:`count`, name: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`opaque` of bloomfilter

   Creates a basic Bloom filter. This function serves as a low-level
   alternative to :zeek:id:`bloomfilter_basic_init` where the user has full
   control over the number of hash functions and cells in the underlying bit
   vector.


   :param k: The number of hash functions to use.


   :param cells: The number of cells of the underlying bit vector.


   :param name: A name that uniquely identifies and seeds the Bloom filter. If empty,
         the filter will use :zeek:id:`global_hash_seed` if that's set, and
         otherwise use a local seed tied to the current Zeek process. Only
         filters with the same seed can be merged with
         :zeek:id:`bloomfilter_merge`.


   :returns: A Bloom filter handle.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_counting_init  bloomfilter_add
      bloomfilter_lookup bloomfilter_clear bloomfilter_merge global_hash_seed

.. zeek:id:: bloomfilter_clear
   :source-code: base/bif/bloom-filter.bif.zeek 139 139

   :Type: :zeek:type:`function` (bf: :zeek:type:`opaque` of bloomfilter) : :zeek:type:`any`

   Removes all elements from a Bloom filter. This function resets all bits in
   the underlying bitvector back to 0 but does not change the parameterization
   of the Bloom filter, such as the element type and the hasher seed.


   :param bf: The Bloom filter handle.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_add bloomfilter_lookup
      bloomfilter_merge

.. zeek:id:: bloomfilter_counting_init
   :source-code: base/bif/bloom-filter.bif.zeek 78 78

   :Type: :zeek:type:`function` (k: :zeek:type:`count`, cells: :zeek:type:`count`, max: :zeek:type:`count`, name: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`opaque` of bloomfilter

   Creates a counting Bloom filter.


   :param k: The number of hash functions to use.


   :param cells: The number of cells of the underlying counter vector. As there's
          no single answer to what's the best parameterization for a
          counting Bloom filter, we refer to the Bloom filter literature
          here for choosing an appropriate value.


   :param max: The maximum counter value associated with each element
        described by *w = ceil(log_2(max))* bits. Each bit in the underlying
        counter vector becomes a cell of size *w* bits.


   :param name: A name that uniquely identifies and seeds the Bloom filter. If empty,
         the filter will use :zeek:id:`global_hash_seed` if that's set, and
         otherwise use a local seed tied to the current Zeek process. Only
         filters with the same seed can be merged with
         :zeek:id:`bloomfilter_merge`.


   :returns: A Bloom filter handle.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2 bloomfilter_add
      bloomfilter_lookup bloomfilter_clear bloomfilter_merge global_hash_seed

.. zeek:id:: bloomfilter_decrement
   :source-code: base/bif/bloom-filter.bif.zeek 107 107

   :Type: :zeek:type:`function` (bf: :zeek:type:`opaque` of bloomfilter, x: :zeek:type:`any`) : :zeek:type:`bool`

   Decrements the counter for an element that was added to a counting bloom filter in the past.

   Note that decrement operations can lead to false negatives if used on a counting bloom-filter
   that exceeded the width of its counter.


   :param bf: The counting bloom filter handle.


   :param x: The element to decrement


   :returns: True on success

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_lookup bloomfilter_clear
      bloomfilter_merge

.. zeek:id:: bloomfilter_internal_state
   :source-code: base/bif/bloom-filter.bif.zeek 187 187

   :Type: :zeek:type:`function` (bf: :zeek:type:`opaque` of bloomfilter) : :zeek:type:`string`

   Returns a string with a representation of a Bloom filter's internal
   state. This is for debugging/testing purposes only.


   :param bf: The Bloom filter handle.


   :returns: a string with a representation of a Bloom filter's internal state.

.. zeek:id:: bloomfilter_intersect
   :source-code: base/bif/bloom-filter.bif.zeek 178 178

   :Type: :zeek:type:`function` (bf1: :zeek:type:`opaque` of bloomfilter, bf2: :zeek:type:`opaque` of bloomfilter) : :zeek:type:`opaque` of bloomfilter

   Intersects two Bloom filters.

   The resulting Bloom filter returns true when queried for elements
   that were contained in both bloom filters. Note that intersected Bloom
   filters have a slightly higher probability of false positives than
   Bloom filters created from scratch.

   Please note that, while this function works with basic and with counting
   bloom filters, the result always is a basic bloom filter. So - intersecting
   two counting bloom filters will result in a basic bloom filter. The reason
   for this is that there is no reasonable definition of how to handle counters
   during intersection.


   :param bf1: The first Bloom filter handle.


   :param bf2: The second Bloom filter handle.


   :returns: The intersection of *bf1* and *bf2*.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_add bloomfilter_lookup
      bloomfilter_clear bloomfilter_merge

.. zeek:id:: bloomfilter_lookup
   :source-code: base/bif/bloom-filter.bif.zeek 127 127

   :Type: :zeek:type:`function` (bf: :zeek:type:`opaque` of bloomfilter, x: :zeek:type:`any`) : :zeek:type:`count`

   Retrieves the counter for a given element in a Bloom filter.

   For a basic bloom filter, this is 0 when the element is not part of the bloom filter, or 1
   if it is part of the bloom filter.

   For a counting bloom filter, this is the estimate of how often an element was added.


   :param bf: The Bloom filter handle.


   :param x: The element to count.


   :returns: the counter associated with *x* in *bf*.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_add bloomfilter_clear
      bloomfilter_merge

.. zeek:id:: bloomfilter_merge
   :source-code: base/bif/bloom-filter.bif.zeek 153 153

   :Type: :zeek:type:`function` (bf1: :zeek:type:`opaque` of bloomfilter, bf2: :zeek:type:`opaque` of bloomfilter) : :zeek:type:`opaque` of bloomfilter

   Merges two Bloom filters.


   :param bf1: The first Bloom filter handle.


   :param bf2: The second Bloom filter handle.


   :returns: The union of *bf1* and *bf2*.

   .. zeek:see:: bloomfilter_basic_init bloomfilter_basic_init2
      bloomfilter_counting_init bloomfilter_add bloomfilter_lookup
      bloomfilter_clear bloomfilter_merge


