> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 演示日 - 2026-09-10

> 2026-09-10 的 ClickStack 演示日

<h2 id="required-dashboard-filters">
  必填的 dashboard 过滤器
</h2>

*演示者：[@pulpdrew](https://github.com/pulpdrew)*

<iframe width="768" height="432" src="https://www.youtube.com/embed/W7Z32B1Xtng" title="YouTube 视频播放器" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

现在可以将 dashboard 过滤器标记为必填，在为其选定值之前，卡片不会加载。此前所有过滤器都是可选的，打开一个基于大型 source 构建的 dashboard 时，在你尚未缩小范围之前，所有卡片就已经在无任何过滤条件的情况下运行了。

过滤器定义新增了 **Required** toggle。单独启用时，它只会阻塞真正用到该过滤器的卡片：即将其作为变量引用的卡片，以及接收其广播值的卡片。在演示中，一个同时广播到 logs 和 链路追踪 source 的 service name 过滤器阻塞了 dashboard 上的所有卡片；而仅存在于 logs 表中的 severity 过滤器只阻塞了日志卡片，链路追踪卡片照常加载。

另一个选项则可将该必填要求扩展到 dashboard 上的所有卡片，无论卡片是否将该过滤器用作变量，或是否接收其广播值。底层实现上，每种过滤器类型都新增了两个 field：`minSelections`，值为 1 即表示必填；以及用于 dashboard 全局的 `isGlobalRequirement`。`minSelections` 之所以采用数值而非布尔值，是为了后续仍能支持相应的 `maxSelections` 上限，以及大于 1 的最小值。

依赖型过滤器目前还不会被其所依赖的必填过滤器阻塞，因此如果某个过滤器的选项查询引用了必填变量，它仍会在该变量尚无值时就去查询选项。

正如 Brandon 在评审必填过滤器 PR 时所建议的，dashboard 过滤器与变量的选择现在也会应用到卡片编辑器中的图表预览。此前变量和核心过滤器会传递到预览中，广播过滤器却不会，这本身就不一致；而在引入必填过滤器之后，用与 dashboard 一致的过滤条件来编辑卡片在性能上也更合理。**Apply filters** toggle 默认开启，你也可以将其关闭，以对比查看卡片在两种情况下的效果。

如果卡片上配置了 alert，该 toggle 会被强制关闭，因为 alert 在求值时不会应用任何过滤器。这样预览结果才与 alert 实际查询的内容一致。

当预览被某个必填过滤器阻塞时，卡片编辑器中的提示信息现在会指引你关闭 **Apply filters** 来解除阻塞。

**相关 PR：** [#3078](https://github.com/hyperdxio/hyperdx/pull/3078) Support configuring dashboard filters as required、[#3093](https://github.com/hyperdxio/hyperdx/pull/3093) Optionally apply dashboard filters to tile editor preview、[#3098](https://github.com/hyperdxio/hyperdx/pull/3098) Add getBlockingRequiredFilterNames, update tile editor blocked copy

<h2 id="live-query-progress-on-the-search-page">
  搜索页面上的实时查询进度
</h2>

*演示者：[@wrn14897](https://github.com/wrn14897)*

<iframe width="768" height="432" src="https://www.youtube.com/embed/W7Z32B1Xtng?start=143" title="YouTube 视频播放器" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

此前，较慢的搜索在整个执行期间只会显示一个看不出进度的加载动画。你无从得知 ClickHouse 是刚扫描了某个区间的 5% 还是已经到了 95%，甚至无法确认它究竟是否在干活——而当某个 source 的 primary key 并不适合该 查询 时，遇到的正是这种情形。现在，结果表的 footer，以及 histogram 上显示已扫描 行 与 elapsed time 的那一栏，都会报告 ClickHouse 自身的 progress counters：查询 已运行多久、已扫描多少 行，以及完成百分比。这与 查询 流式返回时 ClickHouse 命令行客户端所展示的内容十分接近。

进度信息来自 `JSONEachRowWithProgress` format，它会在 response body 中把 `{"progress":...}` 行与数据 行 交错输出。走 请求头 这条路行不通：一旦 body 开始输出，ClickHouse 就不再发送 `X-ClickHouse-Progress`，而且 `fetch()` 本身也无法增量地暴露 请求头。该 format 需要 ClickHouse 25.1 或更高版本，因此会根据上报的 server version 按 connection 决定是否启用，较旧或版本未知的 servers 仍沿用原有的非流式路径。

搜索页面每次只 fetch 一个 time window，而不是一次性拉取整个区间，因此为期一周的搜索会逐天执行，取到足够的 行 后就停止。进度基于全部 windows 计算，并且有意在各个 window 之间的 gap 中保持延续：如果在这一临界点清除进度，进度条就会消失、elapsed 计时器也会在每个 window 重新开始——在跨度一个月的区间里，这会发生几十次。window 在开始读取之前会先以 0% 注册为进行中，这样刚开启的 window 就不会被直接算上其整个区间的进度。

该功能仅出现在主搜索页面。在 live tail 期间会被隐藏，因为那里的 查询 每隔几秒就会重新 fetch，进度条只会不停闪烁。由于第一个 window 较短，如果某次搜索立即填满了 `LIMIT`，会先短暂显示约 0%，随后进度条消失。

流式传输的是进度，而不是结果。行 仍然按 window 逐批返回；要做到边扫描边返回，需要 ClickHouse side 提供流式支持，这项工作正在进行中，Jordan 在电话会议上也问到了这一点。加上中间还有一层 proxy，复杂度更高，因此目前尚未实现。

分块处理还有一个相关的欠缺，这也是收到的反馈之一：虽然 histogram 会逐块填充，但目前无法区分某个 window 是仍在查询中还是已返回空数据，若能在 图表 本身上给出某种进度提示会更有帮助。这部分代码与本次改动不在同一处。

**相关 PR：** [#3103](https://github.com/hyperdxio/hyperdx/pull/3103) 在搜索期间显示实时 ClickHouse 查询 进度 (尚未合并) 。进度条所依据的按天搜索分窗机制属于更早的工作，不在本次改动范围内；增量搜索 windows 于 [#1125](https://github.com/hyperdxio/hyperdx/pull/1125) 合入，图表 分块则在 [#1233](https://github.com/hyperdxio/hyperdx/pull/1233)。