{"id":22683250,"url":"https://github.com/mtchavez/cuckoo","last_synced_at":"2025-10-05T11:24:22.989Z","repository":{"id":41364431,"uuid":"95849850","full_name":"mtchavez/cuckoo","owner":"mtchavez","description":"Cuckoo Filter in golang for set membership approximation","archived":false,"fork":false,"pushed_at":"2023-03-01T16:58:26.000Z","size":91,"stargazers_count":12,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T12:46:43.323Z","etag":null,"topics":["cuckoo-filter","filter","go","golang","item-count","sketching-algorithm"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtchavez.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-30T04:51:30.000Z","updated_at":"2025-03-24T14:34:32.000Z","dependencies_parsed_at":"2024-06-19T05:41:04.038Z","dependency_job_id":null,"html_url":"https://github.com/mtchavez/cuckoo","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtchavez%2Fcuckoo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtchavez%2Fcuckoo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtchavez%2Fcuckoo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtchavez%2Fcuckoo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtchavez","download_url":"https://codeload.github.com/mtchavez/cuckoo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248611685,"owners_count":21133154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuckoo-filter","filter","go","golang","item-count","sketching-algorithm"],"created_at":"2024-12-09T21:11:23.118Z","updated_at":"2025-10-05T11:24:22.914Z","avatar_url":"https://github.com/mtchavez.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cuckoo Filter\n\n[![Latest Version](http://img.shields.io/github/release/mtchavez/cuckoo.svg?style=flat-square)](https://github.com/mtchavez/cuckoo/releases)\n[![Test](https://github.com/mtchavez/cuckoo/actions/workflows/test.yml/badge.svg)](https://github.com/mtchavez/cuckoo/actions/workflows/test.yml)\n[![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](http://godoc.org/github.com/mtchavez/cuckoo)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mtchavez/cuckoo)](https://goreportcard.com/report/github.com/mtchavez/cuckoo)\n[![Maintainability](https://api.codeclimate.com/v1/badges/3e295a8cb3cfe6f8c1ee/maintainability)](https://codeclimate.com/github/mtchavez/cuckoo/maintainability)\n[![Test Coverage](https://codecov.io/gh/mtchavez/cuckoo/branch/master/graph/badge.svg?token=5xaMOOsXEd)](https://codecov.io/gh/mtchavez/cuckoo)\n\nCuckoo Filter in Go\n\n## Install\n\nInstall via `go get`\n\n`go get -v github.com/mtchavez/cuckoo`\n\n## Usage\n\n- [New Filter](#new-filter)\n- [Configuring](#configuration)\n- [Insert](#insert)\n- [Insert Unique](#insert-unique)\n- [Lookup](#lookup)\n- [Delete](#delete)\n- [Item Count](#item-count)\n- [Save](#save)\n- [Load](#load)\n\n### New Filter\n\nCreate a new filter with default configuration\n\n```go\npackage main\n\nimport \"github.com/mtchavez/cuckoo\"\n\nfunc main() {\n  cuckoo.New()\n}\n```\n\n### Configuration\n\nYou can configure a filter via a `ConfigOption` type and the composed config option\nfunctions provided.\n\n```go\npackage main\n\nimport \"github.com/mtchavez/cuckoo\"\n\nfunc main() {\n  options := []cuckoo.ConfigOption{\n    cuckoo.BucketEntries(uint(24)),\n    cuckoo.BucketTotal(uint(1 \u003c\u003c 16)),\n    cuckoo.FingerprintLength(uint(1)),\n    cuckoo.Kicks(uint(250)),\n  }\n  cuckoo.New(options...)\n}\n```\n\n### Insert\n\nInserting items into a filter\n\n```go\npackage main\n\nimport \"github.com/mtchavez/cuckoo\"\n\nfunc main() {\n  filter := cuckoo.New()\n  filter.Insert([]byte(\"special-items\"))\n}\n```\n\n### Insert Unique\n\nInserting items into a filter only if they do not already exist\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := cuckoo.New()\n  filter.InsertUnique([]byte(\"special-items\"))\n  filter.InsertUnique([]byte(\"special-items\"))\n  if filter.ItemCount() != 1 {\n    fmt.Println(\"Expected only 1 item\")\n  }\n}\n```\n\n### Lookup\n\nCheck if items exist in the filter using Lookup\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := cuckoo.New()\n  filter.Insert([]byte(\"special-items\"))\n  found := filter.Lookup([]byte(\"special-items\"))\n  if !found {\n    fmt.Println(\"Expected to find item in filter\")\n  }\n}\n```\n\n### Delete\n\nDeleting an item if it exists in the filter\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := cuckoo.New()\n  filter.Insert([]byte(\"special-items\"))\n  deleted := filter.Delete([]byte(\"special-items\"))\n  if !deleted {\n    fmt.Println(\"Expected to delete item from filter\")\n  }\n}\n```\n\n### Item Count\n\nGetting the item count of filter. **Using Insert with duplicates will cause the\nitem count to be more like a total items inserted count**. Using InsertUnique\nand checking the ItemCount will be more of a *real* item count.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := cuckoo.New()\n  filter.InsertUnique([]byte(\"special-items\"))\n  filter.InsertUnique([]byte(\"special-items\"))\n  if filter.ItemCount() != 1 {\n    fmt.Println(\"Expected only 1 item\")\n  }\n}\n```\n\n### Save\n\nEncode and save a filter to be able to re-build or re-load back into memory.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := New()\n  item := []byte(\"Largo\")\n  filter.InsertUnique(item)\n  filter.Save(\"./tmp/example_save.gob\")\n}\n```\n\n### Load\n\nLoad a filter back into memory from an encoded filter saved to a file.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n\n  \"github.com/mtchavez/cuckoo\"\n)\n\nfunc main() {\n  filter := New()\n  item := []byte(\"Largo\")\n  filter.InsertUnique(item)\n  filter.Save(\"./tmp/example_save.gob\")\n\n  loadedFilter, _ := Load(\"./tmp/example_save.gob\")\n  fmt.Printf(\"Loaded filter has same item? %v\\n\\n\", loadedFilter.Lookup(item))\n}\n```\n\n## Benchmarks\n\nThere are benchmark tests to check performance of the filter. The following results\nwere ran on a 2.3 GHz Intel Core i7\n\n```txt\n# Updated: 2022-07-01\n\ngoos: darwin\ngoarch: arm64\npkg: github.com/mtchavez/cuckoo\n\nBenchmarkCuckooNew-10                 48            23354917 ns/op\nBenchmarkInsert-10               3342568               806.5 ns/op\nBenchmarkInsertUnique-10         6203035               194.7 ns/op\nBenchmarkLookup-10               6465182               196.3 ns/op\n```\n\n## Tests\n\nRun tests via `go test` or with provided `Makefile`\n\n`go test -v -cover ./...` or `make test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtchavez%2Fcuckoo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtchavez%2Fcuckoo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtchavez%2Fcuckoo/lists"}