# @cloudbitmaps/roaring 中文文档

规范地址：https://npmcn.com/package/%40cloudbitmaps/roaring/

版本：0\.27\.0
npm 元数据更新时间：2026-11-03T05:51:06.421Z
中文译文更新时间：2026-11-10T04:11:04.616Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudbitmaps/roaring
原文对照：https://npmcn.com/package/%40cloudbitmaps/roaring/?lang=original
项目主页：https://github.com/cloudbitmaps/cloudbitmaps#readme
源码仓库：https://github.com/cloudbitmaps/cloudbitmaps

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.1 MB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：1 个
- 首次发布：2026-07-25T23:45:26.582Z
- 最新版本发布：2026-11-03T05:51:06.064Z
- 近 30 天下载量：2401（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

分布式,云-内生的比特马普斯-查询和相交的十亿级整数直接从对象存储出,从自有桶中不可变的物体上取出一个有界限的RAM缓存,分出一个常有缓存.

## 安装

```sh
npm install @cloudbitmaps/roaring
```

也可以使用：`pnpm add @cloudbitmaps/roaring`、`yarn add @cloudbitmaps/roaring`、`bun add @cloudbitmaps/roaring`

## README

# @ cloudbitmaps/ 摇摆

**大型整数ID,存储在您自己的对象存储中,从任何地方读取.** 装入一组不可改变 文档,然后询问 `has`, (中文(简体) ), `count`, (中文(简体) ), `iterate`, (中文(简体) ), `intersect`, (中文(简体) ), `union` 财务报告和审定财务报表 `andNot`,没有服务器或缓存可运行。 部分 [云位图](https://github.com/cloudbitmaps/cloudbitmaps);这是您导入的软件包.

> **仅限无害环境管理,节点22.12.** 使用 `import`; 用于 `require()`时标和类型脚本,参见 [常见的JS、快取和类型脚本](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#commonjs-jest-and-typescript)。 。 。 .

> 前1.0:API和上盘格式仍然可以更改. 在npm上,这些文件与它们所运送的版本相符;在GitHub上,它们描述 `main`,更改日志则说每个版本都改变了什么.

## 安装

```bash
pnpm add @cloudbitmaps/roaring              # the store, with in-memory and local-disk backends
pnpm add @cloudbitmaps/s3                   # the storage you have: or @cloudbitmaps/gcs, or @cloudbitmaps/azure-blob
pnpm add @cloudbitmaps/tools                # optional: price a store, offline
```

安装每张的同版本 `@cloudbitmaps/*` 软件包:它们一起发行,每个包都标出准确的版本 `core` 它是与建造的.

该店的"咆哮"用TypeScript来写出,没有本土代码: [这是什么意思](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/roaring-codec.md)。 。 。 .

## 使用

不需要设置 : `MemoryStorage` 将一切保存在过程中, 这是正确的第一眼和测试. 另存为 `first-run.mjs` 并运行它与 `node`数字 :

```js
import { CloudRoaring, MemoryStorage } from '@cloudbitmaps/roaring';

const store = new CloudRoaring({ storage: new MemoryStorage() });

await store.load({ segment: 'shoppers' }, [5, 99_999, 1_234_567_890]); // a load replaces the segment
await store.load({ segment: 'active' }, [5, 7, 1_234_567_890]);

const shoppers = store.segment('shoppers');
console.log(await shoppers.has(99_999)); // true
console.log(await shoppers.count()); // 3
for await (const id of shoppers.intersect([store.segment('active')])) console.log(id); // 5, then 1234567890
```

坚持下去,通过一个不同的 **后端** 作为 `storage`。没有其他变化 :

| 后端 | 从 | 用它来 |
| --- | --- | --- |
| `MemoryStorage` | `@cloudbitmaps/roaring` | 测试和第一眼 |
| `LocalFsStorage('./.cloudbitmaps')` | `@cloudbitmaps/roaring` | 一个文件夹上的进程: 笔记本电脑或 CI 任务 |
| `S3Storage({ bucket, prefix })` | `@cloudbitmaps/s3` | 生产:经审定的 |
| `GcsStorage({ bucket, prefix })` | `@cloudbitmaps/gcs` | 谷歌云存储; 外部 [已验证信封](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/ROADMAP.md#the-validated-envelope--whats-proven-and-what-isnt) |
| `AzureBlobStorage({ connectionString, container })` | `@cloudbitmaps/azure-blob` | Azure Blob 存储器; 外部 [已验证信封](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/ROADMAP.md#the-validated-envelope--whats-proven-and-what-isnt) |

`RoaringBitmap` 是解码器的位图作为公用类: 一组可变的无符号的32位代号, 带有可移植的咆哮 字节,在TypeScript中没有本地代码. 从这里导入 `@cloudbitmaps/roaring`,与商店的同一行: `import { CloudRoaring, MemoryStorage, RoaringBitmap } from '@cloudbitmaps/roaring'`一个商店装满一个,而且 `RoaringBitmap.deserialize(bytes)` 是你没有写的字节的唯一门.

两个电话比本地人慢 `roaring` 包件在长椅上的比例为10以上,以及载有数字的船舶。 第一个 `deserialize` 在新工艺中,测量出的比例约为14.6(中位数2.20 ms相对于0.151 ms);这是第一次呼叫的一次性成本(预期原因是代码尚未优化并加上编译时间),后来的解码在五个数据集中测出的比例为2.2比5.9. 64个密集位图与 `orMany` 测量比率约为11。 每个数字都在 [表单](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/roaring-codec.md#the-public-class-against-native-in-memory)。 。 。 .

```ts
import { CloudRoaring, MemoryStorage, RoaringBitmap } from '@cloudbitmaps/roaring';

const store = new CloudRoaring({ storage: new MemoryStorage() });

const vip = new RoaringBitmap([5, 99_999, 1_234_567_890]); // any iterable of ids
vip.add(7);
vip.removeMany([99_999]);
vip.addMany(new RoaringBitmap([8, 9])); // another bitmap, or a Uint32Array, works too

await store.load({ segment: 'vip' }, vip); // read, never changed or kept

// Bytes from another process go through the one safe door: capped, checked, one whole bitmap.
const received = RoaringBitmap.deserialize(vip.serialize());
console.log(received.size, received.minimum(), received.maximum()); // 5 5 1234567890
```

[API 参考文献](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-and-combine-bitmaps-by-themselves--roaringbitmap) 拥有所有的方法 以及它与 `roaring` 软件包.

存储的部分没有 `add` 或者说 `remove` (单位:千美元)`RoaringBitmap` does, for a bitmap in memory):只有装入新一代的片段才会改变. 负载是批量工作 不是 请求处理器. `store.exists(ref)` 说明是否装入了一段 。 负载需要识别码, 或是您已经位图 持有 : `store.load(ref, bitmap)` (单位:千美元) `RoaringBitmap` (或 a 个) `RoaringBitmap32`),或 `{ serialized }` 手提式咆哮字节,选中 在任何事物被写入和装入没有每作一作的作品之前, 进入一代, 持有块块, 块块的id将写( 它的脚带有自己的写作身份) .

要写很多结果 在同一存储的操作, `store.materializeMany` 读取每首歌一整批 `and` 编号 : `or` 编号 : `andNot` 产出而不是每产出一次 `*Into` 调用, 以及您已在内存流中保存的一组 供养. [一次考试产生的许多产出](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#many-outputs-from-one-pass-materializemany) 二者相盖.

## 选项

`new CloudRoaring({ storage, ...options })`。仅限 `storage` 需要时间。 商店不取的密钥被拒绝 名称.

| 选项 | 它所持有的 |
| --- | --- |
| `storage` (必须) | a 后端(见上文) |
| `cache` | `maxChunks`, (中文(简体) ), `ttlMs` (缓存块的可选年龄限制;省略了块,直到被拆迁为止), `genTtlMs` (读者如何很快看到新的负载,默认2000ms), `readerMax`, (中文(简体) ), `readerMaxBytes` |
| `encryption` | `{ keystore, required }`: 以自己的密钥加密片段 |
| `retry` | 调制读取的重试,或 `false` 关闭它 |
| `metrics` | 参数沉入;默认关闭 |
| `budget` | `{ maxRequests }` 或者说 `false`: 逐名请求上限 |
| `seams` | `{ clock, rng, entropy }`: 确定性,用于测试和可重放的工作; 每代书写身份的来源是最后一个 |

## 付出的代价

凉了 `intersect` 在两个50万分之一的片段中 分享了他们的1,999个块中的100个块 使6个在中位数上得到107.87毫秒, **每笔2.40美元 百万个** 按列表价格计算:在S3区域内计量,运行时间为2026-10-30,其客户拥有128个套接字. 在散开的布局上,它读取更多 字节比它需要的,跨区域可以花费比它所保存的请求还要多. 一个部分的第一个单段 `store.load()` 已制作 2个PUT+3 得到, **每百万美元11.20美元** 按默认价格计算,指针包括: 请求在S3区域内,在同一跑道上进行计量. 一个稳定的单段 `store.load()` 时间 `keep: 12` 删除代号成本 **每百万美元12.00美元**,对于 2 PUT + 5 GET 和一个免费删除,在 S3 区域内测量的请求,在同一运行中。 凉了 `count()` 是一个 指针读取:它读取了没有有效载荷和物体.

交易是明确的。 缺少缓存的会员资格检查 相对于对象存储, 成本范围是一定的, 其中,进程内存储会花费读取的内存。 如果你需要次毫秒的答案 在一个工作集,适合 绑定缓存,使用Redis. [基准](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/benchmarks.md) 给出方法 和数字不能确定的。 从大小到价格 `seg.stat()` 报告,使用 `@cloudbitmaps/tools` (单位:千美元)[成本指南](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/cost.md)) (中文(简体) ).

## 生产前

-   运行 `await store.preflight()` 第一次载货之前 它读登记册、写作、试图再写、读取、列出和 删除一个探测对象并检查后端的生命周期规则,以及答案 `{ ok, checks }`; 见 [`store.preflight()`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#check-the-setup-with-storepreflight)。 。 。 . 它不检查 `s3:AbortMultipartUpload`,登记簿的 `If-Match`,或删除后读取,除其他外: [完整列表](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#what-preflight-does-not-check)。 。 。 .
-   授予库问题权限并添加一个生命周期规则来中止不完整上传. S3和GCS系统 后端为 `checkLifecycle()` 阅读桶的规则 并说是删除还是存档什么商店 保留; Azure Blob 的答案 `unchecked` 并说如何用手检查; `MemoryStorage` 财务报告和审定财务报表 `LocalFsStorage` 没有 规则和答案 `ok`。 。 。 .
-   使用一个尊重有条件写作并具有强烈一致性的桶(读取或写作后的列表) 删除它) `@aws-sdk/client-s3` 3.700.0 或以后通过自己的S3客户端. 飞行前报告第二个成功(即3.640.0或以上的SDK如何显示)和读取或列出 而不是从3.641.0到3.699.0 `If-None-Match` 但会下降 `If-Match`: SDK地板留你检查.
-   在您的存储客户端上设定请求超时 。 自己读取重试,每个后端都可以计时(`readTimeoutMs`); 瞬间失败的写作由您重新运行.
-   用数据备份注册簿, 如果您加密的话, 键盘也会备份 。 如果你丢了钥匙 数据就不见了.
-   排好你的载荷,和 `retireExpired` 如果你使用保留。 运行载入请求路径 .

这个 [生产清单](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) 覆盖每个项目.

## 来自Redis位图?

`GETBIT` 实值 `has`, (中文(简体) ), `BITCOUNT` 实值 `count`,以及 `BITOP AND` 编号 : `OR` 编号 : `DIFF` 为: `intersect` 编号 : `union` 编号 : `andNot`,与 `intersectInto`, (中文(简体) ), `unionInto` 财务报告和审定财务报表 `andNotInto` 以新一代方式公布结果 `materializeMany` 出版 许多这样的结果 一次通过. `EXPIRE` 变成 `setRetention` 加一个 `retireExpired` 扫描你的时间表,每段,从来没有每个id. `SETBIT` 没有等效的 : 没有每个字。 将设定建立为上游并加载, 并且一次不循环一个 ID 。 删除一个 ID 到处都是 `eraseSubject`重写遵守,而不是热路动词。 这不是一个临时替代,和 不结转的是书写模型和生字节: `exportSegments` 写可移植的咆哮和ndjson,而不是雷迪斯的布局. [全面测绘](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#coming-from-redis-bitmaps) 说还有什么不同.

## 文档

-   [开始](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md)
-   [生产前](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md)
-   [API 参考](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md)
-   [更改日志](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md)
-   [隐私和分担责任](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/PRIVACY.md)

## 贷项

咆哮比特玛克格式及其算法是丹尼尔·莱米尔和同僚的作品. 见 [(原始内容存档于2018-03-26). rawingbitmap.org](https://roaringbitmap.org/) 编辑 [咆哮格式规格](https://github.com/RoaringBitmap/RoaringFormatSpec), (中文(简体) ), 定义可移植字节 `.crbm` 对象持有。 商店的编码器执行这种格式和那些 typeScript 中的算法 ([它是如何被控制在克罗林](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/roaring-codec.md#the-guarantee-the-same-bytes); 骑行,通过 `roaring` 具有拘束力,是其测试的参照物。 文件:

-   S. Chambi, D. Lemire, O. Kaser, R. Godin,"用Roaring bitmaps更好的位图性能","R, _软件: 经历_ 46(5), 2016 (英语). [arXiv:1402.6407 (中文(简体) )](https://arxiv.org/abs/1402.6407)
-   D.Lemire,G.Ssi-Yan-Kai,O.Kaser,"与Roaring一致的更快和更小的压缩位图","持续", _软件: 实践和经验_ 46 (11), 2016 (英语). [arXiv:1603.06549 (英语)](https://arxiv.org/abs/1603.06549)
-   D.Lemire,O.Kaser,N.Kurz,L.Deri,C.O'Hara,F.Saint-Jacques,G.Ssi-Yan-Kai,"Roaring Bitmaps:执行" “优化软件库”, _软件:实践和经验_ 48(4), 2018 (英语). [arXiv:1709.07821 (中文(简体) )](https://arxiv.org/abs/1709.07821)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @cloudbitmaps/roaring 是什么？

分布式,云-内生的比特马普斯-查询和相交的十亿级整数直接从对象存储出,从自有桶中不可变的物体上取出一个有界限的RAM缓存,分出一个常有缓存\.

### 如何安装 @cloudbitmaps/roaring？

在项目目录运行 npm install @cloudbitmaps/roaring，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 export-segments，可以用 npx export-segments 直接运行。

### @cloudbitmaps/roaring 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudbitmaps/roaring 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cloudbitmaps/roaring 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudbitmaps/roaring 可以商用吗？

@cloudbitmaps/roaring 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbitmaps/roaring 的下载量有多少？

根据 npm 官方下载统计，@cloudbitmaps/roaring 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,401 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudbitmaps/roaring 还在维护吗？

最新版本 0\.27\.0 发布于 2026/11/03（6 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 40 个；首次发布于 2026/07/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。