cuckoo: Haskell Implementation of Cuckoo Filters

[ bsd3, data, library ] [ Propose Tags ] [ Report a vulnerability ]

Haskell implementation of Cuckoo filters as described in

B. Fan, D.G. Anderson, M. Kaminsky, M.D. Mitzenmacher. Cuckoo Filter: Practically Better Than Bloom. In Proc. CoNEXT, 2014.

Cuckoo filters are a data structure for probabilistic set membership. They support insertion, deletion, and membership queries for set elements.

Membership queries may return false positive results. But queries don't return false negative results.

Unlike Bloom filters, Cuckoo filters maintain an upper bound on the false positive rate that is independent of the load of the filter. However, insertion of new elements in the filter can fail. For typical configurations this probability is very small for load factors smaller than 90 percent.


[Skip to Readme]

library cuckoo

library cuckoo:random-internal

Flags

Manual Flags

NameDescriptionDefault
mwc-random

Use mwc-random instead of the random package

Disabled
pcg-random

Use pcg-random instead of the random package

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.0.0, 0.2.0.0, 0.2.0.1, 0.2.1, 0.2.2, 0.3.0, 0.3.1
Change log CHANGELOG.md
Dependencies base (>=4.11 && <5), bytestring (>=0.10), cuckoo, hashes (>=0.2), primitive (>=0.6.4.0), random (>=1.1) [details]
Tested with ghc ==9.0.1, ghc ==8.10.7, ghc ==8.8.4
License BSD-3-Clause
Copyright Copyright (c) 2019-2021 Lars Kuhtz <lakuhtz@gmail.com>
Author Lars Kuhtz
Maintainer lakuhtz@gmail.com
Category Data
Home page https://github.com/larskuhtz/cuckoo
Bug tracker https://github.com/larskuhtz/cuckoo/issues
Source repo head: git clone https://github.com/larskuhtz/cuckoo.git
Uploaded by larsk at 2021-10-21T06:10:44Z
Distributions
Downloads 2394 total (19 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2021-10-21 [all 1 reports]

Readme for cuckoo-0.3.1

[back to package description]

Hackage

Haskell implementation of Cuckoo filters as described in

B. Fan, D.G. Anderson, M. Kaminsky, M.D. Mitzenmacher. Cuckoo Filter: Practically Better Than Bloom. In Proc. CoNEXT, 2014.

Cuckoo filters are a data structure for probabilistic set membership. They support insertion, deletion, and membership queries for set elements.

Membership queries may return false positive results. But queries don't return false negative results.

Unlike Bloom filters, Cuckoo filters maintain an upper bound on the false positive rate that is independent of the load of the filter. However, insertion of new elements in the filter can fail. For typical configurations this probability is very small for load factors smaller than 90 percent.

The implementation allows the user to specify the bucket size and the fingerprint size in addition to the capacity of the filter. The user can also provide custom functions for computing the primary hash and fingerprint.

Installation

cabal install cuckoo

For running the test-suites

cabal test cuckoo

For running the benchmarks

cabal bench cuckoo

Example

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeApplications #-}
{-# LANGUAGE TypeFamilies #-}
{-# OPTIONS_GHC -fno-warn-orphans #-}

import Control.Monad (filterM)
import Data.Cuckoo
import Data.List ((\\))

-- Define CuckooFilterHash instance (this uses the default implementation)
instance CuckooFilterHash Int

main :: IO ()
main = do
    -- Create Filter for a minimum of 500000 entries
    f <- newCuckooFilter @4 @8 @Int 0 500000

    -- Insert 450000 items
    failed <- filterM (fmap not . insert f) [0..500000-1]

    -- Query inserted items
    missing <- filterM (fmap not . member f) [0..500000-1]

    -- Test for false positives
    false <- filterM (member f) [500000..1000000 - 1]

    -- Report results
    putStrLn $ "failed inserts: " <> show (length failed)
    putStrLn $ "false positives: " <> show (length false)
    putStrLn $ "false positive rate (%): " <> show @Double (fromIntegral (length false) * 100 / 500000)
    putStrLn $ "missing (must be 0): " <> show (length $ missing \\ failed)

    -- Filter properties
    putStrLn $ "capacity: " <> show (capacityInItems f)
    putStrLn $ "size in allocated bytes: " <> show (sizeInAllocatedBytes f)

    -- computing the following is a bit slow
    c <- itemCount f
    putStrLn $ "item count: " <> show c
    lf <- loadFactor f
    putStrLn $ "load factor (%): " <> show lf
    putStrLn $ "bits per item: " <> show @Double (fromIntegral (sizeInAllocatedBytes f) * 8 / fromIntegral c)

Which produces the following results:

$ ghc -o main -threaded -O -with-rtsopts=-N Main.hs
[1 of 1] Compiling Main             ( Main.hs, Main.o )
Linking main ...
$ ./main
failed inserts: 0
false positives: 14796
false postive rate (%): 2.9592
missing (must be 0): 0
capacity: 524288
size in allocated bytes: 524292
item count: 500000
load factor (%): 95.367431640625
bits per item: 8.388672

Another example can be found in the file bench/SpellChecker.hs.