{"id":17369663,"url":"https://github.com/lorenzhs/burr","last_synced_at":"2025-08-22T01:32:51.677Z","repository":{"id":142387494,"uuid":"387404686","full_name":"lorenzhs/BuRR","owner":"lorenzhs","description":"Bumped Ribbon Retrieval and Approximate Membership Query","archived":false,"fork":false,"pushed_at":"2024-12-03T08:30:50.000Z","size":149,"stargazers_count":39,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-11T04:10:55.565Z","etag":null,"topics":["amq","approximate-membership","approximate-membership-query","bloom-filter","bloom-filter-alternative","retrieval"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2109.01892","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lorenzhs.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2021-07-19T09:10:32.000Z","updated_at":"2024-12-03T08:30:54.000Z","dependencies_parsed_at":"2024-09-10T10:45:35.640Z","dependency_job_id":"2abbef60-2326-40bb-991e-0fb9e2447d1f","html_url":"https://github.com/lorenzhs/BuRR","commit_stats":{"total_commits":10,"total_committers":4,"mean_commits":2.5,"dds":0.7,"last_synced_commit":"e8d6a638441321da39896fd345f2d120b2754461"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lorenzhs%2FBuRR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lorenzhs%2FBuRR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lorenzhs%2FBuRR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lorenzhs%2FBuRR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lorenzhs","download_url":"https://codeload.github.com/lorenzhs/BuRR/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230547679,"owners_count":18243227,"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":["amq","approximate-membership","approximate-membership-query","bloom-filter","bloom-filter-alternative","retrieval"],"created_at":"2024-10-16T00:06:17.351Z","updated_at":"2025-08-22T01:32:51.659Z","avatar_url":"https://github.com/lorenzhs.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"## BuRR: Bumped Ribbon Retrieval (and Filters)\n\nBuRR is a static retrieval and approximate membership query data structure with extremely low overhead and fast queries. Our paper introducing BuRR, [\"Fast Succinct Retrieval and Approximate Membership Using Ribbon\"](https://drops.dagstuhl.de/opus/volltexte/2022/16538/), won the best paper award at the 20th International Symposium on Experimental Algorithms 2022 and is available in full as an open-access publication. For additional details and measurements, please [refer to the preprint on arxiv.org](https://arxiv.org/abs/2109.01892).\n\n\"Retrieval\" means that you have a set of key-value pairs that you want to represent very compactly.  The difference to a hash table is that the data structure may return garbage values when queried with keys not in the set.  It's also typically far more compact: a BuRR representation of the data is typically not more than 0.1-0.5% larger than the *values* it represents (no keys are stored).\n\n\"Approximate Membership Query\" (AMQ) means that you have a set and want to check whether an element is likely in the set.  Some well-known examples are Bloom filters, Xor filters, Cuckoo filters, and Quotient filters.  A query for an item in the set will always return `true`, while a query for an item *not* in the set *usually* returns `false`, but may return `true` with some small probability known as the *false-positive probability f*.  The space required to represent this set depends on *f*, and there is a lower bound of *log2(1/f)* bits per item of the set.  Classic Bloom filters use *1.44 log2(1/f)* bits per key, meaning they use 44% more space than needed.  With Xor filters, overhead on the order of 20% can be achieved, and Xor+ filters reduce this to approximately 10% for very small values of *f*.  BuRR can achieve overheads as low as 0.1%, and even configurations that trade overhead for speed achieve overheads of below 0.5%.\n\n## Building and running\n\nMake sure to fetch all submodules with `git submodule update --init --recursive`, then type `make bench` to compile a benchmark runner that includes a wide range of configurations, or `make tests` to compile the test suite.  The scripts used in the evaluation are located in the `scripts` folder.  You may also want to refer to [the fastfilter_cpp repository](https://github.com/lorenzhs/fastfilter_cpp) for a comparison to other filter data structures and more benchmarks used in our paper.\n\nThe library can be used similar to the following example:\n\n```cpp\n#include \"ribbon.hpp\"\n\nstd::vector\u003cstd::pair\u003cuint64_t, uint8_t\u003e\u003e data;\ndata.emplace_back(0xabc, 0); // Key has to be a hash value\ndata.emplace_back(0xdef, 1);\n\nusing namespace ribbon;\nusing Config = FastRetrievalConfig\u003c/* result bits */ 1, uint64_t\u003e;\nusing RibbonT = ribbon_filter\u003c/* depth */ 2, Config\u003e;\nRibbonT retrievalDs(data.size(), /* overload factor */ 0.965, /* seed */ 42);\n\n// Construction\nretrievalDs.AddRange(data.begin(), data.end());\nretrievalDs.BackSubst();\n\n// Queries\nstd::cout \u003c\u003c (int) retrievalDs.QueryRetrieval(0xabc) \u003c\u003c std::endl; // 0\nstd::cout \u003c\u003c (int) retrievalDs.QueryRetrieval(0xdef) \u003c\u003c std::endl; // 1\n```\n\n## Enhancements\n\n- You can find a parallel implementation on the [`parallel` branch](https://github.com/lorenzhs/BuRR/tree/parallel) and its brief announcement paper on [arXiv](https://arxiv.org/abs/2411.12365).\n- [SimpleRibbon](https://github.com/ByteHamster/SimpleRibbon) is a wrapper around BuRR that offers cmake support for setting up dependencies, as well as a non-header library to reduce compile times.\n\n## Citation\n\nIf you use BuRR in the context of an academic publication, we ask that you please cite our paper:\n\n```bibtex\n@inproceedings{BuRR2022,\n    author={Peter C. Dillinger, Lorenz Hübschle-Schneider, Peter Sanders, and Stefan Walzer},\n    title={Fast Succinct Retrieval and Approximate Membership using Ribbon},\n    booktitle={20th International Symposium on Experimental Algorithms (SEA 2022)},\n    pages={4:1--4:20},\n    year={2022},\n    doi={10.4230/LIPIcs.SEA.2022.4}\n}\n```\n\n## License\n\nBuRR is licensed under the Apache 2.0 license. Copyright is held by Lorenz Hübschle-Schneider and Facebook, Inc.  It is based on [Peter C. Dillinger's implementation of Standard Ribbon](https://github.com/pdillinger/fastfilter_cpp/tree/dev/src/ribbon), which is copyright Facebook, Inc. and also licensed under the Apache 2.0 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Florenzhs%2Fburr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Florenzhs%2Fburr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Florenzhs%2Fburr/lists"}