DeepSeek 总结的duckdb-behavioral插件说明

受 ClickHouse 启发的 DuckDB 行为分析函数。

提供 sessionize、retention、window_funnel、sequence_match、sequence_count、sequence_match_events 和 sequence_next_node 函数，作为一个用 Rust 编写的可加载 DuckDB 扩展。完全兼容 ClickHouse 行为分析函数。

个人项目免责声明：这是一个利用个人时间开发的个人项目。它与我的雇主或职业角色没有任何关联、认可或关系。

AI 辅助开发披露

本项目在 Anthropic 的 Claude（AI 辅助编程）的协助下开发。本着完全透明和学术严谨的原则，以下保障措施确保 AI 辅助不会损害正确性、可重复性或可信度：

434 个单元测试 + 1 个文档测试 ，涵盖所有函数、边缘情况、合并结合性、基于属性的测试 (proptest) 以及基于突变测试指导的覆盖率。所有测试通过 cargo test 在 1 秒内运行完成。
27 个端到端 SQL 测试，针对真实的 DuckDB v1.4.4 实例运行，验证从扩展加载到 SQL 执行再到正确结果的完整链路，包括 NULL 输入、空表、全部 6 种漏斗模式、5 个以上条件以及全部 8 种方向/基础组合。
Criterion.rs 基准测试 ，具有 95% 置信区间，每次测量运行 3 次以上，并在 PERF.md 中记录了详细方法。每个性能声明都可以在通用硬件上重现。
88.4% 的突变测试击杀率 （130 个捕获 / 17 个遗漏），通过 cargo-mutants 系统地验证了测试能够检测到真正的故障。
零 Clippy 警告，在 pedantic、nursery 和 cargo lint 组下。
确定性、可重现的构建 --- 锁定依赖版本 (libduckdb-sys = "=1.4.4")，在 CI 中验证 MSRV 1.80，并带有 LTO 和单一代码生成单元的发布配置文件。
每次优化会话都记录了假设、技术、带有置信区间的测量前后数据，负面结果如实报告（PERF.md 中记录了 5 个负面结果）。
所有源代码均可公开审计，遵循 MIT 许可证。

AI 工具被用作实现的加速器。所有正确性保证都依赖于自动化测试、可重现的基准测试和透明的文档------而非假设 AI 输出是正确的。

快速开始

sql 复制代码

-- 从 DuckDB 社区扩展仓库安装
INSTALL behavioral FROM community;
LOAD behavioral;

或者从源代码构建：

bash 复制代码

# 构建扩展
cargo build --release

# 在 DuckDB 中加载（本地构建的扩展需要 -unsigned 标志）
duckdb -unsigned -cmd "LOAD 'target/release/libbehavioral.so';"

sql 复制代码

-- 基于 30 分钟不活动间隔分配会话 ID
SELECT user_id, event_time,
  sessionize(event_time, INTERVAL '30 minutes') OVER (
    PARTITION BY user_id ORDER BY event_time
  ) as session_id
FROM events;

-- 跟踪 1 小时窗口内的转化漏斗步骤
SELECT user_id,
  window_funnel(INTERVAL '1 hour', event_time,
    event_type = 'page_view',
    event_type = 'add_to_cart',
    event_type = 'purchase'
  ) as furthest_step
FROM events
GROUP BY user_id;

函数列表

函数	签名	返回类型	描述
`sessionize`	`(TIMESTAMP, INTERVAL)`	`BIGINT`	窗口函数，基于不活动间隔分配会话 ID
`retention`	`(BOOLEAN, BOOLEAN, ...)`	`BOOLEAN[]`	群组留存分析
`window_funnel`	`(INTERVAL [, VARCHAR], TIMESTAMP, BOOLEAN, ...)`	`INTEGER`	转化漏斗步骤跟踪，支持 6 种可组合模式
`sequence_match`	`(VARCHAR, TIMESTAMP, BOOLEAN, ...)`	`BOOLEAN`	基于 NFA 的事件序列模式匹配
`sequence_count`	`(VARCHAR, TIMESTAMP, BOOLEAN, ...)`	`BIGINT`	计算非重叠模式匹配次数
`sequence_match_events`	`(VARCHAR, TIMESTAMP, BOOLEAN, ...)`	`LIST(TIMESTAMP)`	返回匹配条件的时间戳
`sequence_next_node`	`(VARCHAR, VARCHAR, TIMESTAMP, VARCHAR, BOOLEAN, ...)`	`VARCHAR`	模式匹配后的下一个事件值

所有函数支持 2 到 32 个布尔条件 ，与 ClickHouse 的限制一致。每个函数的详细文档、示例和边缘情况行为：函数参考

性能

以下所有测量结果均来自 Criterion.rs 0.8.2，具有 95% 置信区间，并在通用硬件上跨多次运行验证。

函数	数据规模	墙钟时间	吞吐量
`sessionize`	10 亿	1.20 秒	8.3 亿元素/秒
`retention` (合并)	1 亿	274 毫秒	3.65 亿元素/秒
`window_funnel`	1 亿	791 毫秒	1.26 亿元素/秒
`sequence_match`	1 亿	1.05 秒	9500 万元素/秒
`sequence_count`	1 亿	1.18 秒	8500 万元素/秒
`sequence_match_events`	1 亿	1.07 秒	9300 万元素/秒
`sequence_next_node`	1 千万	546 毫秒	1800 万元素/秒

关键设计选择：

16 字节 Copy 事件 ，带有 u32 位掩码条件------每四个事件占一个缓存行，每个事件零堆分配
sessionize 和 retention 的 O(1) 合并，通过边界跟踪和位掩码 OR 实现
事件收集函数的就地合并------摊余 O(N) 而非重复分配导致的 O(N^2)
NFA 快速路径------常见模式类型分派到专门的 O(n) 线性扫描，而非完整的 NFA 回溯
预排序检测------当事件按时间戳顺序到达时，O(n) 检查可跳过 O(n log n) 排序

优化亮点：

优化项	加速比	技术
事件位掩码	5--13 倍	`Vec<bool>` 替换为 `u32` 位掩码，实现 `Copy` 语义
就地合并	高达 2,436 倍	摊余 O(N) 扩展而非 O(N^2) 合并分配
NFA 惰性匹配	在 1M 事件时达 1,961 倍	交换探索顺序，使 `.*` 在消耗前尝试推进
`Arc<str>` 值	2.1--5.8 倍	引用计数字符串，实现 `sequence_next_node` 中的 O(1) 克隆
NFA 快速路径	39--61%	模式分类将常见形状分派到 O(n) 线性扫描

有五次尝试的优化经测量被认定为回归并已回滚。所有负面结果均在 PERF.md 中记录。

完整的方法论、带有置信区间的每轮优化历史以及可重现的基准测试说明：PERF.md。

社区扩展

此扩展已列入 DuckDB 社区扩展仓库（PR #1306，于 2026-02-15 合并）。安装方式如下：

sql 复制代码

INSTALL behavioral FROM community;
LOAD behavioral;

无需构建工具、编译或 -unsigned 标志。

更新流程

community-submission.yml 工作流自动执行完整的预提交流水线，分为 5 个阶段：

阶段	目的
验证	`description.yml` 架构、版本一致性、必需文件
质量门禁	`cargo test`（434 + 文档测试）、`clippy`、`fmt`、`doc`
构建与测试	`make configure && make release && make test_release`
固定引用	将 `description.yml` 的 ref 更新为已验证的提交 SHA
提交包	上传构建产物，生成逐步的 PR 命令

更新已发布的扩展

将更改推送到此仓库，重新运行提交工作流以固定新的 ref，然后向 duckdb/community-extensions 打开一个新的 PR，更新 extensions/behavioral/description.yml 中的 ref 字段。当 DuckDB 发布新版本时，更新 libduckdb-sys、TARGET_DUCKDB_VERSION 和 extension-ci-tools 子模块。

质量

指标	数值
单元测试	434 + 1 文档测试
端到端测试	27（针对真实的 DuckDB CLI）
基于属性的测试	26 (proptest)
突变测试	88.4% 击杀率 (130/147, cargo-mutants)
Clippy 警告	0（pedantic + nursery + cargo lint 组）
CI 任务	13（检查、测试、clippy、fmt、doc、MSRV、基准测试、deny、semver、覆盖率、跨平台、扩展构建）
基准测试文件	7（Criterion.rs，最高达 10 亿元素）
发布平台	4（Linux x86_64/ARM64，macOS x86_64/ARM64）

每次推送和 PR 都会运行 CI：跨 .github/workflows/ 的 6 个工作流，包括针对真实 DuckDB 的 E2E 测试、CodeQL 静态分析、SemVer 验证以及具有来源证明的 4 平台发布构建。

ClickHouse 兼容性状态

已完成 --- 所有 ClickHouse 行为分析函数均已实现。

函数	状态
`sessionize`	已完成
`retention`	已完成
`window_funnel` (6 种模式)	已完成
`sequence_match`	已完成
`sequence_count`	已完成
`sequence_match_events`	已完成
`sequence_next_node`	已完成
支持 32 个条件	已完成

构建

前提条件：Rust 1.80+ (MSRV)，一个 C 编译器（用于 DuckDB 系统绑定）

bash 复制代码

# 构建扩展（发布模式）
cargo build --release

# 可加载扩展将位于：
# target/release/libbehavioral.so   (Linux)
# target/release/libbehavioral.dylib (macOS)

开发

bash 复制代码

cargo test                  # 434 个单元测试 + 1 个文档测试
cargo clippy --all-targets  # 要求零警告
cargo fmt                   # 格式化
cargo bench                 # Criterion.rs 基准测试

# 通过社区 Makefile 构建扩展
git submodule update --init
make configure && make release && make test_release

本项目遵循语义化版本。有关应用于 SQL 函数签名的完整 SemVer 规则，请参阅版本控制策略。

文档

入门指南 --- 安装、加载、故障排除
函数参考 --- 所有 7 个函数的详细文档
使用案例 --- 5 个包含示例数据的完整真实世界示例
工程概述 --- 架构、测试理念、设计权衡
性能 --- 基准测试、优化历史、方法论
ClickHouse 兼容性 --- 语法映射、语义等价性
贡献指南 --- 开发环境设置、测试、PR 流程

要求

Rust 1.80+ (MSRV)
DuckDB 1.4.4（锁定依赖）
Python 3.x（用于扩展元数据工具）

许可证

MIT

DeepSeek 总结的duckdb-behavioral插件说明

AI 辅助开发披露

目录

快速开始

函数列表

性能

社区扩展

更新流程

更新已发布的扩展

质量

ClickHouse 兼容性状态

构建

开发

文档

要求

许可证