1. Druid 多维查询为什么绕不开 Bitmap 索引时序数据库的查询需求大致分两类一类是按时间线拉原始数据另一类是在多个维度上做过滤、聚合、TopN。前者靠时间分区和列存就能扛住后者才是真正拉开性能差距的地方。比如select Added from datasource where Gender Female and City Taiyuan这种语句如果没有任何索引引擎只能把整个 segment 扫一遍逐行比对维度值数据量一上来延迟就失控。Bitmap 索引解决的正是这个问题。它把每个维度列的每个取值映射成一条位图位图的下标对应行号值为 1 表示该行在这个维度上取了这个值。多个过滤条件之间做与、或运算本质上就是位图的按位与、按位或一次位运算就能把候选行压缩到极小集合再回表取数值列。Druid 在 segment 落盘阶段批量构建 Bitmap 索引配合 RoaringBitmap 压缩既控制了写入放大又让多维过滤走索引而不是全表扫描。这篇面向时序数据库开发者聚焦 Druid Bitmap 索引在多维查询中的落地配置。我会给出可复制的config.toml骨架把 TaoToken 作为统一的 Key/API 通道接进来方便你在调试查询、验证索引生效时有一个稳定的模型调用入口最后给出索引是否真正生效的验证动作。整套链路的目标是配置可复制、请求可验证、问题可排查。2. TaoToken 前置统一 Key 与 API 通道在动手配 Druid 之前先把调用通道理清楚。TaoToken 在这里扮演的是统一入口的角色你不需要为每个模型或工具单独维护一套 Key而是通过一个 API Key 走同一个 API 地址把模型对话、编码辅助、控制台管理都收敛到一条链路上。对做时序数据库调优的人来说这意味着你在排查查询计划、让模型帮你读 segment 元数据、生成验证脚本时不用来回切换凭证。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里直接写这个即可。控制台和 Key 管理走 deep link模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCodeAnthropichttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite注意API 基址统一用 https://taotoken.net/api 不要拼接首页的 UTM 参数否则部分客户端会把查询串当成路径的一部分导致 404。拿到 Key 之后建议先做一次最小连通性验证确认通道可用再去配 Druid。这样后面如果查询验证失败你能快速区分是索引没生效还是通道本身有问题。3. 可复制配置config.toml 骨架与 Bitmap 索引参数下面这份config.toml骨架把 Druid 的 Bitmap 索引相关配置和 TaoToken 通道配置放在一起你可以直接复制后按需改。Druid 的索引构建发生在 segment 落盘阶段所以关键参数集中在 segment 生成和维度列处理上。# TaoToken 统一通道 [taotoken] api_base https://taotoken.net/api api_key sk-你的Key # 模型对话 / 编码辅助共用同一 Key default_model claude-sonnet timeout_ms 60000 # Druid 索引与 segment [druid] # 实时节点内存数据 persist 到本地磁盘的间隔 persist_period_minutes 10 # 本地多个文件合并成 segment 的间隔 segment_merge_period_minutes 60 [druid.segment] # 维度列构建 Bitmap 索引落盘时批量构建 build_bitmap_index true # 使用 RoaringBitmap 压缩兼顾压缩率与位运算效率 bitmap_compression roaring # 维度字典按字典序排序后落盘支持二分查找 sort_dimension_dictionary true [druid.dimensions] # 需要建 Bitmap 索引的维度列按实际 schema 填 bitmap_columns [Gender, City, Page, Username] # 高基数维度谨慎开启字典和位图都会膨胀 high_cardinality_warn_threshold 100000 [druid.query] # 多维过滤优先走索引 use_index_for_filter true # 结果位图遍历时按行号回表取数值列 cursor_batch_size 4096几个参数值得展开说。persist_period_minutes和segment_merge_period_minutes决定了索引构建的节奏内存里的数据在 persist 之前是没有 Bitmap 索引的这段时间的查询走的是直接扫描所以 persist 间隔越大未索引数据窗口越长。bitmap_compression选roaring是因为维度列位图里连续 0 和连续 1 很多RoaringBitmap 对这类稀疏和稠密混合的位图压缩效果好且与、或运算快。sort_dimension_dictionary必须为 true否则查询时无法用二分查找定位维度值对应的编码只能线性遍历高基数维度会直接拖垮查询。维度列的选择也有讲究。bitmap_columns里放的是经常出现在 where 条件里的列比如 Gender、City 这种低基数枚举列。像 Username 这种基数可能很高的列如果确实要按它过滤可以开但要盯着high_cardinality_warn_threshold超过阈值时字典文件和位图文件都会明显变大落盘和加载成本上升。4. 验证请求确认 Bitmap 索引真正生效配置写完不代表索引就生效了得用实际请求验证。分两步先验证 TaoToken 通道再验证 Druid 查询是否走了索引。先做通道连通性验证用 curl 发一个最小请求curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}], max_tokens: 16 }返回里能看到正常的choices结构说明 Key 和 API 基址都没问题。如果返回 401检查 Key 是否复制完整返回 404检查是不是把首页 UTM 参数拼进了 API 地址。接着验证 Druid 查询。用上面那条多维过滤语句观察查询耗时和返回行数curl -s -X POST http://druid-broker:8082/druid/v2 \ -H Content-Type: application/json \ -d { queryType: timeseries, dataSource: datasource, granularity: all, filter: { type: and, fields: [ {type: selector, dimension: Gender, value: Female}, {type: selector, dimension: City, value: Taiyuan} ] }, aggregations: [{type: longSum, name: added, fieldName: Added}], intervals: [2011-01-01T00:00:00Z/2011-01-02T00:00:00Z] }判断索引是否生效看两个信号。一是查询耗时同样的过滤条件开索引后应该明显低于全表扫描数据量越大差距越明显。二是查询计划Druid 的 broker 日志里会打印 filter 的处理方式如果看到BitmapIndex或bitmap相关字样说明过滤走了索引如果看到scan或全列扫描说明索引没命中回去检查build_bitmap_index是否为 true、维度列是否在bitmap_columns里、以及数据是否已经 persist 落盘。提示刚写入内存还没 persist 的数据不走 Bitmap 索引验证时确保查询的时间区间覆盖的是已经落盘的 segment否则会误判索引没生效。5. 本篇常见错排查实际配置过程中下面几个问题出现频率最高按顺序排查基本能覆盖大部分情况。索引没生效查询还是慢。先确认数据是否已经 persist。内存数据在 persist 之前没有 Bitmap 索引查询走直接扫描。把persist_period_minutes调小可以缩短这个窗口但会增加落盘频率写入吞吐会受一点影响需要权衡。其次确认维度列是否在bitmap_columns里漏配的列不会建索引。维度字典查找慢。检查sort_dimension_dictionary是否为 true。字典不排序的话查询时定位维度值对应的编码只能线性遍历高基数维度下这一步会成为瓶颈。排序后走二分查找复杂度从 O(n) 降到 O(log n)。位图文件过大。多半是维度基数太高。像 Username 这种列取值可能几十万上百万每个取值一条位图字典和位图文件都会膨胀。这类列要么不建 Bitmap 索引要么评估是否真的需要按它做多维过滤。high_cardinality_warn_threshold就是用来提前预警的。TaoToken 请求 401 或 404。401 是 Key 问题去 API Keys 页面重新生成并确认复制完整。404 是地址问题API 基址必须是 https://taotoken.net/api 不要带首页的 UTM 查询串。如果用的是某些客户端注意它可能自动拼接路径确认最终请求 URL 正确。segment 合并后索引丢失。Bitmap 索引文件需要在 segment 合并时一起合并合并过程是逐行读出再重新生成索引。如果合并配置里没开启索引重建合并后的新 segment 可能没有索引。检查合并任务的配置确保build_bitmap_index在合并阶段同样生效。6. 继续深入把通道和索引链路固定下来配好之后建议把这条链路固定成日常调试的默认路径Druid 负责多维查询加速TaoToken 负责模型调用和脚本生成。需要长期做编码辅助、写验证脚本、让模型帮你读查询计划的可以走 Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 只是临时验证模型输出、跑几条对话的用模型对话入口https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 就够Key 的生成和管理在 API Keys 页面https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节看文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。一个实用技巧把上面那份config.toml里的bitmap_columns和实际查询日志对照着看定期统计哪些维度列最常出现在 filter 里把高频列加进索引低频高基数列移出去。索引不是越多越好每条位图都有构建和存储成本按查询模式来配才是正解。
时序数据库技术体系 – Druid 多维查询之Bitmap索引与 TaoToken 配置实战
1. Druid 多维查询为什么绕不开 Bitmap 索引时序数据库的查询需求大致分两类一类是按时间线拉原始数据另一类是在多个维度上做过滤、聚合、TopN。前者靠时间分区和列存就能扛住后者才是真正拉开性能差距的地方。比如select Added from datasource where Gender Female and City Taiyuan这种语句如果没有任何索引引擎只能把整个 segment 扫一遍逐行比对维度值数据量一上来延迟就失控。Bitmap 索引解决的正是这个问题。它把每个维度列的每个取值映射成一条位图位图的下标对应行号值为 1 表示该行在这个维度上取了这个值。多个过滤条件之间做与、或运算本质上就是位图的按位与、按位或一次位运算就能把候选行压缩到极小集合再回表取数值列。Druid 在 segment 落盘阶段批量构建 Bitmap 索引配合 RoaringBitmap 压缩既控制了写入放大又让多维过滤走索引而不是全表扫描。这篇面向时序数据库开发者聚焦 Druid Bitmap 索引在多维查询中的落地配置。我会给出可复制的config.toml骨架把 TaoToken 作为统一的 Key/API 通道接进来方便你在调试查询、验证索引生效时有一个稳定的模型调用入口最后给出索引是否真正生效的验证动作。整套链路的目标是配置可复制、请求可验证、问题可排查。2. TaoToken 前置统一 Key 与 API 通道在动手配 Druid 之前先把调用通道理清楚。TaoToken 在这里扮演的是统一入口的角色你不需要为每个模型或工具单独维护一套 Key而是通过一个 API Key 走同一个 API 地址把模型对话、编码辅助、控制台管理都收敛到一条链路上。对做时序数据库调优的人来说这意味着你在排查查询计划、让模型帮你读 segment 元数据、生成验证脚本时不用来回切换凭证。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里直接写这个即可。控制台和 Key 管理走 deep link模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCodeAnthropichttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite注意API 基址统一用 https://taotoken.net/api 不要拼接首页的 UTM 参数否则部分客户端会把查询串当成路径的一部分导致 404。拿到 Key 之后建议先做一次最小连通性验证确认通道可用再去配 Druid。这样后面如果查询验证失败你能快速区分是索引没生效还是通道本身有问题。3. 可复制配置config.toml 骨架与 Bitmap 索引参数下面这份config.toml骨架把 Druid 的 Bitmap 索引相关配置和 TaoToken 通道配置放在一起你可以直接复制后按需改。Druid 的索引构建发生在 segment 落盘阶段所以关键参数集中在 segment 生成和维度列处理上。# TaoToken 统一通道 [taotoken] api_base https://taotoken.net/api api_key sk-你的Key # 模型对话 / 编码辅助共用同一 Key default_model claude-sonnet timeout_ms 60000 # Druid 索引与 segment [druid] # 实时节点内存数据 persist 到本地磁盘的间隔 persist_period_minutes 10 # 本地多个文件合并成 segment 的间隔 segment_merge_period_minutes 60 [druid.segment] # 维度列构建 Bitmap 索引落盘时批量构建 build_bitmap_index true # 使用 RoaringBitmap 压缩兼顾压缩率与位运算效率 bitmap_compression roaring # 维度字典按字典序排序后落盘支持二分查找 sort_dimension_dictionary true [druid.dimensions] # 需要建 Bitmap 索引的维度列按实际 schema 填 bitmap_columns [Gender, City, Page, Username] # 高基数维度谨慎开启字典和位图都会膨胀 high_cardinality_warn_threshold 100000 [druid.query] # 多维过滤优先走索引 use_index_for_filter true # 结果位图遍历时按行号回表取数值列 cursor_batch_size 4096几个参数值得展开说。persist_period_minutes和segment_merge_period_minutes决定了索引构建的节奏内存里的数据在 persist 之前是没有 Bitmap 索引的这段时间的查询走的是直接扫描所以 persist 间隔越大未索引数据窗口越长。bitmap_compression选roaring是因为维度列位图里连续 0 和连续 1 很多RoaringBitmap 对这类稀疏和稠密混合的位图压缩效果好且与、或运算快。sort_dimension_dictionary必须为 true否则查询时无法用二分查找定位维度值对应的编码只能线性遍历高基数维度会直接拖垮查询。维度列的选择也有讲究。bitmap_columns里放的是经常出现在 where 条件里的列比如 Gender、City 这种低基数枚举列。像 Username 这种基数可能很高的列如果确实要按它过滤可以开但要盯着high_cardinality_warn_threshold超过阈值时字典文件和位图文件都会明显变大落盘和加载成本上升。4. 验证请求确认 Bitmap 索引真正生效配置写完不代表索引就生效了得用实际请求验证。分两步先验证 TaoToken 通道再验证 Druid 查询是否走了索引。先做通道连通性验证用 curl 发一个最小请求curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}], max_tokens: 16 }返回里能看到正常的choices结构说明 Key 和 API 基址都没问题。如果返回 401检查 Key 是否复制完整返回 404检查是不是把首页 UTM 参数拼进了 API 地址。接着验证 Druid 查询。用上面那条多维过滤语句观察查询耗时和返回行数curl -s -X POST http://druid-broker:8082/druid/v2 \ -H Content-Type: application/json \ -d { queryType: timeseries, dataSource: datasource, granularity: all, filter: { type: and, fields: [ {type: selector, dimension: Gender, value: Female}, {type: selector, dimension: City, value: Taiyuan} ] }, aggregations: [{type: longSum, name: added, fieldName: Added}], intervals: [2011-01-01T00:00:00Z/2011-01-02T00:00:00Z] }判断索引是否生效看两个信号。一是查询耗时同样的过滤条件开索引后应该明显低于全表扫描数据量越大差距越明显。二是查询计划Druid 的 broker 日志里会打印 filter 的处理方式如果看到BitmapIndex或bitmap相关字样说明过滤走了索引如果看到scan或全列扫描说明索引没命中回去检查build_bitmap_index是否为 true、维度列是否在bitmap_columns里、以及数据是否已经 persist 落盘。提示刚写入内存还没 persist 的数据不走 Bitmap 索引验证时确保查询的时间区间覆盖的是已经落盘的 segment否则会误判索引没生效。5. 本篇常见错排查实际配置过程中下面几个问题出现频率最高按顺序排查基本能覆盖大部分情况。索引没生效查询还是慢。先确认数据是否已经 persist。内存数据在 persist 之前没有 Bitmap 索引查询走直接扫描。把persist_period_minutes调小可以缩短这个窗口但会增加落盘频率写入吞吐会受一点影响需要权衡。其次确认维度列是否在bitmap_columns里漏配的列不会建索引。维度字典查找慢。检查sort_dimension_dictionary是否为 true。字典不排序的话查询时定位维度值对应的编码只能线性遍历高基数维度下这一步会成为瓶颈。排序后走二分查找复杂度从 O(n) 降到 O(log n)。位图文件过大。多半是维度基数太高。像 Username 这种列取值可能几十万上百万每个取值一条位图字典和位图文件都会膨胀。这类列要么不建 Bitmap 索引要么评估是否真的需要按它做多维过滤。high_cardinality_warn_threshold就是用来提前预警的。TaoToken 请求 401 或 404。401 是 Key 问题去 API Keys 页面重新生成并确认复制完整。404 是地址问题API 基址必须是 https://taotoken.net/api 不要带首页的 UTM 查询串。如果用的是某些客户端注意它可能自动拼接路径确认最终请求 URL 正确。segment 合并后索引丢失。Bitmap 索引文件需要在 segment 合并时一起合并合并过程是逐行读出再重新生成索引。如果合并配置里没开启索引重建合并后的新 segment 可能没有索引。检查合并任务的配置确保build_bitmap_index在合并阶段同样生效。6. 继续深入把通道和索引链路固定下来配好之后建议把这条链路固定成日常调试的默认路径Druid 负责多维查询加速TaoToken 负责模型调用和脚本生成。需要长期做编码辅助、写验证脚本、让模型帮你读查询计划的可以走 Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 只是临时验证模型输出、跑几条对话的用模型对话入口https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 就够Key 的生成和管理在 API Keys 页面https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节看文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。一个实用技巧把上面那份config.toml里的bitmap_columns和实际查询日志对照着看定期统计哪些维度列最常出现在 filter 里把高频列加进索引低频高基数列移出去。索引不是越多越好每条位图都有构建和存储成本按查询模式来配才是正解。
