bloomfilter

Note

This is a fork of OldPanda/bloomfilter. We’re using this library at Hinge and needed a version without a CGO dependency to simplify deployment. After evaluating the impact on precision, we found the false positive rate remained low and stable for our use case, so we’ve chosen to proceed with the CGO-free implementation. Huge thanks to the original author for the excellent work and Java Guava compatibility — it’s been a great foundation for us.

Overview

Yet another Bloomfilter implementation in Go, compatible with Java's Guava library. This library borrows how Java's Guava libraray implements Bloomfilter hashing strategies to achieve the serialization compatibility.

Installing

First pull the latest version of the library:

go get github.com/OldPanda/bloomfilter

Then import the this library in your code:

import "github.com/OldPanda/bloomfilter"

Usage Examples

Basic Usage

package main

import (
	"fmt"

	"github.com/OldPanda/bloomfilter"
)

func main() {
	// create bloomfilter with expected insertion=500, error rate=0.01
	bf, _ := bloomfilter.NewBloomFilter(500, 0.01)
	// add number 0~199 into bloomfilter
	for i := 0; i < 200; i++ {
		bf.Put(i)
	}

	// check if number 100 and 200 are in bloomfilter
	fmt.Println(bf.MightContain(100))
	fmt.Println(bf.MightContain(200))
}

Serialization

package main

import "github.com/OldPanda/bloomfilter"

func main() {
	// expected insertion=500, error rate=0.01
	bf, _ := bloomfilter.NewBloomFilter(500, 0.01)
	// add 0~199 into bloomfilter
	for i := 0; i < 200; i++ {
		bf.Put(i)
	}

	// serialize bloomfilter to byte array
	bytes := bf.ToBytes()
	// handling the bytes ...
}

Deserialization

package main

import (
	"fmt"

	"github.com/OldPanda/bloomfilter"
)

func main() {
	// create bloomfilter from byte array
	bf, _ := bloomfilter.FromBytes(bytes)
	// check whether number 100 is in bloomfilter
	fmt.Println(bf.MightContain(100))
}

Benchmark

The benchmark testing runs on element insertion and query separately.

» go test -bench . -benchmem ./...
# github.com/OldPanda/bloomfilter.test
goos: darwin
goarch: arm64
pkg: github.com/OldPanda/bloomfilter
BenchmarkBloomfilterInsertion-12                11091939                90.62 ns/op           17 B/op          1 allocs/op
BenchmarkBloomfilterQuery-12                    20389624                53.16 ns/op           15 B/op          1 allocs/op
BenchmarkBloomfilterDeserialization-12            293098              3767 ns/op           13200 B/op         52 allocs/op
PASS
ok      github.com/OldPanda/bloomfilter 3.719s