{"id":26281924,"url":"https://github.com/aviggiano/redis-roaring","last_synced_at":"2025-12-29T13:50:09.624Z","repository":{"id":41458020,"uuid":"90567267","full_name":"aviggiano/redis-roaring","owner":"aviggiano","description":"Roaring Bitmaps for Redis","archived":false,"fork":false,"pushed_at":"2024-04-16T20:06:42.000Z","size":57789,"stargazers_count":355,"open_issues_count":13,"forks_count":56,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-30T05:03:57.589Z","etag":null,"topics":["redis","redis-module","roaring-bitmaps"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aviggiano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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-05-07T23:03:08.000Z","updated_at":"2025-03-27T03:16:03.000Z","dependencies_parsed_at":"2024-06-19T12:21:53.468Z","dependency_job_id":null,"html_url":"https://github.com/aviggiano/redis-roaring","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/aviggiano%2Fredis-roaring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fredis-roaring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fredis-roaring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviggiano%2Fredis-roaring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aviggiano","download_url":"https://codeload.github.com/aviggiano/redis-roaring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441049,"owners_count":20939239,"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":["redis","redis-module","roaring-bitmaps"],"created_at":"2025-03-14T16:17:35.119Z","updated_at":"2025-12-29T13:50:09.612Z","avatar_url":"https://github.com/aviggiano.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"redis-roaring [![Coverage Status](https://coveralls.io/repos/github/aviggiano/redis-roaring/badge.svg?branch=master)](https://coveralls.io/github/aviggiano/redis-roaring?branch=master) [![CI/CD](https://github.com/aviggiano/redis-roaring/actions/workflows/ci.yml/badge.svg)](https://github.com/aviggiano/redis-roaring/actions/workflows/ci.yml) [![Static Badge](https://img.shields.io/badge/documentation-passing-blue)](https://redisroaring.com)\n===========\nRoaring Bitmaps for Redis\n\n## Intro\n\nThis project uses the [CRoaring](https://github.com/RoaringBitmap/CRoaring) library to implement roaring bitmap commands for Redis.\nThese commands can have the same performance as redis' native bitmaps for *O(1)* operations and be [up to 8x faster](#performance) for *O(N)*\ncalls, according to microbenchmarks, while consuming less memory than their uncompressed counterparts (benchmark pending).\n\nPull requests are welcome.\n\n## Dependencies\n\n- CRoaring (bitmap compression library used by this redis module)\n- cmake (build tools needed for compiling the source code)\n- redis (server needed for integration tests)\n- hiredis (redis client library needed for performance tests)\n\n## Redis Version Compatibility\n\nThis module is compatible with **Redis 6.0 and later**.\n\n- **Redis 7.4+**: Full feature support including custom ACL categories, command ACL categories, and command introspection\n- **Redis 7.2 - 7.3**: Command introspection and command ACL categories supported\n- **Redis 7.0 - 7.1**: Command introspection (COMMAND INFO, COMMAND DOCS) supported\n- **Redis 6.0 - 6.2**: Core roaring bitmap functionality supported\n\nThe module automatically detects the Redis version at runtime and adjusts its behavior accordingly:\n- Command metadata (via `RedisModule_SetCommandInfo`) is only registered on Redis 7.0+\n- Command ACL categories (via `RedisModule_SetCommandACLCategories`) are only set on Redis 7.2+\n- Custom ACL categories (via `RedisModule_AddACLCategory`) are only registered on Redis 7.4+\n\nAll core roaring bitmap commands work on Redis 6.0+.\n\n## Getting started\n\n```\n$ git clone https://github.com/aviggiano/redis-roaring.git\n$ cd redis-roaring/\n$ configure.sh\n$ cd dist \n$ ./redis-server ./redis.conf  \n```\nthen you can open another terminal and use `./redis-cli` to connect to the redis server\n\n## Docker\n\nIt is also possible to run this project as a docker container.\n\n```bash\ndocker run -p 6379:6379 aviggiano/redis-roaring:latest\n```\n\n## Tests\n\nRun the `test.sh` script for unit tests, integration tests and performance tests.\nThe performance tests can take a while, since they run on a real dataset of integer values.\n\n## Fuzzing\n\nredis-roaring includes fuzz testing using libFuzzer with AddressSanitizer and UndefinedBehaviorSanitizer. Four fuzz targets test 32-bit operations, 64-bit operations, complex bitwise operations, and data parsing. Fuzzing runs automatically on every push to master.\n\nBuild and run fuzzers locally with `./scripts/build_fuzzers.sh` (requires Clang). Run individual fuzzers with `./scripts/run_fuzzer.sh \u003cfuzzer_name\u003e \u003cduration\u003e` or all fuzzers with `./scripts/run_all_fuzzers.sh`.\n\nSee [docs/fuzzing.md](docs/fuzzing.md) for complete documentation.\n\n## API\n\n**📖 Complete Documentation**: For detailed command documentation including syntax, parameters, examples, and usage notes, see [docs/commands/index.md](docs/commands/index.md)\n\nThe following operations are supported\n\n- `R.SETBIT` (same as [SETBIT](https://redis.io/commands/setbit))\n- `R.GETBIT` (same as [GETBIT](https://redis.io/commands/getbit))\n- `R.BITOP` (same as [BITOP](https://redis.io/commands/bitop))\n- `R.BITCOUNT` (same as [BITCOUNT](https://redis.io/commands/bitcount) without `start` and `end` parameters)\n- `R.BITPOS` (same as [BITPOS](https://redis.io/commands/bitpos) without `start` and `end` parameters)\n- `R.SETINTARRAY` (create a roaring bitmap from an integer array)\n- `R.GETINTARRAY` (get an integer array from a roaring bitmap)\n- `R.SETBITARRAY` (create a roaring bitmap from a bit array string)\n- `R.GETBITARRAY` (get a bit array string from a roaring bitmap)\n\nAdditional commands\n\n- `R.APPENDINTARRAY` (append integers to a roaring bitmap)\n- `R.RANGEINTARRAY` (get an integer array from a roaring bitmap with `start` and `end`, so can implements paging)\n- `R.SETRANGE` (set or append integer range to a roaring bitmap)\n- `R.SETFULL` (fill up a roaring bitmap in integer)\n- `R.STAT` (get statistical information of a roaring bitmap)\n- `R.OPTIMIZE` (optimize a roaring bitmap)\n- `R.MIN` (get minimal integer from a roaring bitmap, if key is not exists or bitmap is empty, return -1)\n- `R.MAX` (get maximal integer from a roaring bitmap, if key is not exists or bitmap is empty, return -1)\n- `R.DIFF` (get difference between two bitmaps)\n\n64-bit bitmap commands (for handling values beyond 32-bit range)\n\n- `R64.SETBIT` (64-bit version of SETBIT)\n- `R64.GETBIT` (64-bit version of GETBIT)\n- `R64.SETINTARRAY` (create a 64-bit roaring bitmap from an integer array)\n- `R64.GETINTARRAY` (get an integer array from a 64-bit roaring bitmap)\n- `R64.RANGEINTARRAY` (get an integer array from a 64-bit roaring bitmap with `start` and `end`)\n- `R64.APPENDINTARRAY` (append integers to a 64-bit roaring bitmap)\n- `R64.DIFF` (get difference between two 64-bit bitmaps)\n- `R64.SETFULL` (fill up a 64-bit roaring bitmap)\n\nMissing commands:\n\n- `R.BITFIELD` (same as [BITFIELD](https://redis.io/commands/bitfield))\n\n## API Example\n```\n$ redis-cli\n# create a roaring bitmap with numbers from 1 to 99\n127.0.0.1:6379\u003e R.SETRANGE test 1 100\n\n# get all the numbers as an integer array\n127.0.0.1:6379\u003e R.GETINTARRAY test\n\n# fill up the roaring bitmap \n# because you need 2^32*4 bytes memory and a very long time\n127.0.0.1:6379\u003e R.SETFULL full\n\n# use `R.RANGEINTARRAY` to get numbers from 100 to 1000 \n127.0.0.1:6379\u003e R.RANGEINTARRAY full 100 1000\n\n# append numbers to an existing roaring bitmap\n127.0.0.1:6379\u003e R.APPENDINTARRAY test 111 222 3333 456 999999999 9999990\n```\n\n## Performance\n\nTested using CRoaring's `census1881` dataset. Performance tests are run automatically on every push to master branch.\n\n\u003c!-- BEGIN_PERFORMANCE --\u003e\n|               OP |     TIME/OP (us) |     ST.DEV. (us) |\n| ---------------- | ---------------- | ---------------- |\n|         R.SETBIT |            47.48 |            13.65 |\n|       R64.SETBIT |            47.39 |            12.34 |\n|           SETBIT |            45.75 |            11.81 |\n|         R.GETBIT |            46.55 |             7.57 |\n|       R64.GETBIT |            46.38 |             7.16 |\n|           GETBIT |            45.66 |             6.77 |\n|       R.BITCOUNT |            48.37 |             0.10 |\n|     R64.BITCOUNT |            43.09 |             0.07 |\n|         BITCOUNT |            57.34 |             0.12 |\n|         R.BITPOS |            43.63 |             0.07 |\n|       R64.BITPOS |            43.63 |             0.16 |\n|           BITPOS |            49.02 |             0.20 |\n|      R.BITOP NOT |            89.74 |             1.28 |\n|    R64.BITOP NOT |            94.75 |             1.27 |\n|        BITOP NOT |           207.97 |             1.19 |\n|      R.BITOP AND |            49.81 |             0.22 |\n|    R64.BITOP AND |            50.98 |             0.19 |\n|        BITOP AND |           262.08 |             3.69 |\n|       R.BITOP OR |            60.95 |             1.17 |\n|     R64.BITOP OR |            61.12 |             0.68 |\n|         BITOP OR |           418.35 |             6.93 |\n|      R.BITOP XOR |            61.11 |             1.10 |\n|    R64.BITOP XOR |            62.62 |             0.77 |\n|        BITOP XOR |           377.55 |             6.07 |\n|    R.BITOP ANDOR |            47.79 |             0.16 |\n|  R64.BITOP ANDOR |            49.86 |             0.23 |\n|      BITOP ANDOR |           398.88 |             6.34 |\n|      R.BITOP ONE |            71.44 |             0.65 |\n|    R64.BITOP ONE |            79.51 |             0.83 |\n|        BITOP ONE |           426.52 |             7.02 |\n|            R.MIN |            44.65 |             0.16 |\n|          R64.MIN |            43.60 |             0.05 |\n|              MIN |            42.74 |             0.04 |\n|            R.MAX |            43.05 |             0.04 |\n|          R64.MAX |            42.86 |             0.05 |\n|              MAX |            43.15 |             0.04 |\n\u003c!-- END_PERFORMANCE --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviggiano%2Fredis-roaring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faviggiano%2Fredis-roaring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviggiano%2Fredis-roaring/lists"}