Wang Fenjin

SwanLake: An Arrow Flight SQL Datalake Service Built on DuckDB + DuckLake

Sat, 21 Feb 2026 00:00:00 +0000

After handing duckdb-rs over to the DuckDB team in 2023, one question kept coming back to me:

If DuckDB is already great in-process, how do we turn that power into a service that is easier to integrate, deploy, and operate?

SwanLake is my answer to that question.

It is a Rust-based Arrow Flight SQL server, powered by DuckDB, with DuckLake-oriented extensions for datalake scenarios. In practice, SwanLake is built around a three-part combination: DuckDB + DuckLake + Flight SQL.

Why I started SwanLake

With duckdb-rs, the primary goal was clear: make DuckDB feel natural in Rust. That part worked well, but new constraints became obvious:

Most teams are not single-language; they need one service interface across stacks.
Real workloads involve object storage, metadata services, and multiple cooperating systems.
Production systems need observability, not just logs.

So SwanLake was never “just another wrapper”. I wanted a practical analytics service entrypoint.

Architecture

You can read SwanLake as a five-layer system:

1) Access Layer: Arrow Flight SQL (gRPC)

All query/update traffic enters through Flight SQL. This gives us a protocol that is efficient and language-neutral; the Rust/Go/Python examples in the repo validate this layer directly.

2) Session Layer: Session Registry

swanlake-core manages connection-scoped sessions:

session IDs are created/reused from peer_addr or peer_ip,
prepared statements, transactions, and temp objects remain session-affine,
max sessions + idle timeout protect server resources.

3) Execution Layer: DuckDB

I did not build a new engine. SwanLake wraps DuckDB for service use: each session has an isolated connection, startup preloads ducklake/httpfs/aws/postgres extensions, and SWANLAKE_DUCKLAKE_INIT_SQL can inject bootstrap SQL.

4) Datalake Layer: DuckLake

DuckLake is the key piece. Without it, DuckDB is mainly an excellent local analytical engine. With DuckLake, metadata and object-storage paths can be organized consistently, which makes DuckDB-based datalake services practical.

5) Operations Layer: Metrics + Status + Config

Runtime metrics (latency/slow query/errors), status endpoints (/ + status.json), and env-based configuration (SWANLAKE_*) form the operational surface. This layer is what makes the system observable and manageable in production.

Observability was a first-class requirement

SwanLake has a built-in status page (default :4215) plus status.json for machine consumption. It exposes:

session counts and idle indicators,
query/update latency stats (avg, p95, p99),
slow query and recent error history.

I added this because these are exactly the signals I want when debugging production behavior.

How I read the current benchmark data

BENCHMARK.md (CI artifact dated 2026-02-21) includes TPCH results at SF=0.1 where postgres_local_file outperforms postgres_s3 in that run.

Metric (SF=0.1)	postgres_local_file	postgres_s3
Throughput (req/s)	10.428	4.867
Avg latency (ms)	382.751	818.041
p95 latency (ms)	829.236	1904.023
p99 latency (ms)	1116.002	2661.619

This is expected directionally: object storage paths usually add more variability.

One practical point is critical here: when using S3 or other remote object storage, you should usually enable cache_httpfs, otherwise latency, especially tail latency, can become very unstable.

This is already reflected in the benchmark workflow configuration. See .github/workflows/performance.yml:

postgres_s3 defaults to BENCHBASE_ENABLE_CACHE_HTTPFS=true,
postgres_local_file defaults to BENCHBASE_ENABLE_CACHE_HTTPFS=false,
the workflow input can override this behavior.

But I do not think the takeaway is “local is always better”. A better takeaway is:

choose storage tiers based on workload shape,
run repeated benchmarks and track variance,
keep performance visibility continuous, not one-off.

From duckdb-rs to SwanLake

For me, duckdb-rs and SwanLake are part of the same line of work.

duckdb-rs solved: how to use DuckDB elegantly inside Rust applications.

SwanLake solves: how to provide DuckDB as a shared, deployable, operable service for teams.

What I will keep working on

SwanLake is still evolving. My near-term focus is:

more production-oriented reliability and load testing,
better performance predictability on object storage backends,
a more consistent developer experience across server and clients.

If you used duckdb-rs before, I would love you to try SwanLake and share feedback via issues or PRs.

References

SwanLake：一个基于 DuckDB + DuckLake 的 Arrow Flight SQL 数据湖服务

Sat, 21 Feb 2026 00:00:00 +0000

2023 年我把 duckdb-rs 交给 DuckDB 官方维护之后，心里一直有个没做完的题：

如果 DuckDB 在单机进程里已经足够强，那怎么把这份能力变成一个更容易接入、可部署、可观测的服务？

SwanLake 就是我给这个问题的答案。

它本质上是一个基于 Rust 的 Arrow Flight SQL Server，底层执行引擎是 DuckDB，同时围绕 DuckLake 做了数据湖场景的能力扩展。更准确地说，SwanLake 的核心组合是 DuckDB + DuckLake + Arrow Flight SQL。

为什么是 SwanLake

我最早做 duckdb-rs 的时候，目标是把 DuckDB 更自然地带到 Rust 生态里。这个目标后来基本实现了，但新的问题也很明确：

很多团队不是 Rust 单一语言栈，客户端接入方式需要统一。
业务里常见的不只是“本地查询”，而是对象存储 + 元数据 + 多服务协作。
线上系统需要可观测性，不能只靠日志排障。

所以 SwanLake 从一开始就不是“再封一层 API”，而是想做一个可以真正放进生产系统的分析服务入口。

系统架构

SwanLake 可以按 5 层来理解：

1) 接入层：Arrow Flight SQL（gRPC）

服务对外暴露 Flight SQL 接口，查询和更新请求都从这里进入。这个协议的核心价值是跨语言和高吞吐，仓库里的 Rust/Go/Python 示例就是围绕这层展开的。

2) 会话层：Session Registry

swanlake-core 里有连接级会话管理：

按 peer_addr 或 peer_ip 生成/复用会话 ID。
prepared statement、事务、临时对象都跟随会话。
通过最大会话数和空闲超时做资源保护。

3) 执行层：DuckDB

执行层没有重新造轮子，而是把 DuckDB 封装成服务可用的执行引擎。每个会话持有独立连接，启动时会加载 ducklake/httpfs/aws/postgres 扩展，并支持通过 SWANLAKE_DUCKLAKE_INIT_SQL 注入初始化 SQL。

4) 数据湖层：DuckLake

DuckLake 是这个系统最关键的一层。没有 DuckLake，DuckDB 更多是本地分析引擎；有了 DuckLake，元数据和对象存储路径就能以统一方式组织起来，SwanLake 才能把“DuckDB 做数据湖”变成可部署的服务方案。

5) 运维层：Metrics + Status + 配置

运行时指标（延迟、慢查询、错误）、状态页（/ + status.json）和环境变量配置（SWANLAKE_*）共同组成了运维面。这个层的目标是让系统上线后可观测、可调优、可回滚。

可观测性

SwanLake 内置了状态页（默认 :4215）和 status.json，会展示：

当前会话数、空闲时长等会话状态。
Query/Update 延迟统计（平均、P95、P99）。
慢查询和最近错误。

我做这个页面不是为了“好看”，而是因为这正是我自己排查问题时最想第一时间看到的数据。

当前 benchmark，我怎么看

仓库里的 BENCHMARK.md（2026-02-21）有一组 TPCH（SF=0.1）结果：postgres_local_file 相比 postgres_s3 在这轮测试里更快。

指标（SF=0.1）	postgres_local_file	postgres_s3
Throughput (req/s)	10.428	4.867
Avg latency (ms)	382.751	818.041
p95 latency (ms)	829.236	1904.023
p99 latency (ms)	1116.002	2661.619

这个结果在预期之内：对象存储链路会引入更高的不确定性。

另外这里有一个非常重要的实践建议：如果后端是 S3 或其他远程对象存储，建议默认启用 cache_httpfs，否则延迟（尤其 tail latency）会非常不稳定。

这个策略我已经放进项目基准流程里了，具体可以直接看 .github/workflows/performance.yml：

postgres_s3 默认 BENCHBASE_ENABLE_CACHE_HTTPFS=true。
postgres_local_file 默认 BENCHBASE_ENABLE_CACHE_HTTPFS=false。
也可以通过 workflow input 显式覆盖该参数。

但我不想把它简单总结成“本地一定更好”。更准确的结论是：

你需要根据 workload 做分层（热数据、本地缓存、远端对象存储）。
你需要反复跑 benchmark 看方差，而不是拿一次结果定架构。
你需要把指标做成持续可见的数据，而不是一次性报告。

从 duckdb-rs 到 SwanLake

如果说 duckdb-rs 解决的是“如何让开发者在 Rust 里优雅地用 DuckDB”，那 SwanLake 解决的是另一个问题：

如何把 DuckDB 变成一个团队可共享的、可部署的、可运维的数据服务。

这两个项目对我来说是一条连续的技术路线，而不是两个孤立项目。

后面还会做什么

SwanLake 还在持续迭代，我接下来会继续重点做几件事：

继续补齐生产场景下的稳定性与压测数据。
优化对象存储场景的性能和可预测性。
让客户端和服务端的使用体验更统一，降低接入门槛。

如果你之前用过 duckdb-rs，我也很欢迎你来试试 SwanLake，提 issue、提 PR、或者直接分享你遇到的问题。

参考

2026 年的软件开发流程，会被 AI 改成什么样？

Wed, 31 Dec 2025 00:00:00 +0000

“这就意味着宇宙普适的物理规律不存在，那物理学……也不存在了。“汪淼从窗外收回目光说。

——《三体》

多年以后，面对黑色屏幕上闪动的白色光标，我们将会回想起，那个 AI 编程横空出世的 2025。

2025 年是 AI 编程的大年，从 OpenRouter 的年终统计来看，AI 编程用的 Token 占了整个 Token 使用量的一半左右。

作为“资深程序员”，我今年也贡献了很多的 token 使用量，深切感受到 AI 编程对于软件开发领域带来了不可逆的影响。至少从技术上，我认为这些影响绝大部分都是正向的。

之前写程序一定程度上是“体力劳动”，不管有多宏大的想法，代码总要一行一行写。 AI 编程让程序员向脑力劳动又前进了一步，我们需要更激进地学习新知识、使用新工具，从这个角度来说，我认为 AI 编程是提高了对计算机从业者的要求，而不是某些媒体鼓吹的“技术平权”。

这篇文章总结下我对 AI 编程现状的观察，以及对后续发展的预期。

开发工具

首先从开发工具讲起。明星创业公司 Cursor 因为 VS Code + Claude 一夜走红，算是彻底带火了 AI 编程。但是我想讲的不是这个，而是为什么突然所有的公司都开始做 CLI 工具，比如 Claude Code, Codex, Gemini CLI 等等？

我认为这里有三个方面的原因：

投入太大： IDE 或者可视化编辑器这一块，VS Code已经是绝对的霸主，这可以说是一个已经解决的问题。如果新产品还从这个方向切入，势必要投入不少精力追赶，这在这个快速迭代的时代是不可想象的。虽然市面上还是有不少基于 VS Code fork 出来的编辑器，但是很难像 Cursor 刚出来的时候给人的惊艳感，包括 Amazon 的 Kiro 刚出来的 Spec 模式确实很不错，但是这些模式很容易被同行快速学习和复制，后续也渐渐陷入平庸。
产出太小：其实如果投入大但是又是必须的话，那么还是避免不了要去做。但是对模型来说它并不需要一个 IDE，做 AI 编程最重要的是给模型提供一个高效的环境，而这个环境有命令行已经够了。而且这里有个逻辑是，如果你说你在做个新东西，但是又对过往路径有强依赖的话，可能要重新思考这个方向你到底该不该做，因为大概率竞争不过市场上的领先者。
未来趋势：这个我觉得更加重要。VS Code 这样的编辑器是针对人使用设计的，最大的需求是给人提供便利；但是命令行工具很容易自动化，也很容易和别的工具协同工作。当模型和工具越来越成熟之后，人的参与度会越来越低，而这件事情实际上已经发生了。很多基于 IM、文档、网页等等提供的 AI 编程的工具已经开始被大家使用，我相信这背后肯定是这些 CLI 工具作为支撑。这些工具带来的最大的变化是多会话的管理，因为人同时只能处理一个问题，但是你可以开很多个 CLI 同时让模型做事。

总结来说，2025 年大部分人应该都能通过大模型加速写代码，我认为 2026 年开发者需要找到自己的工具，把工作并发起来，而且这可能不能单纯靠等待市场上产品成熟，也需要自己做好准备，比如开发规范、测试规范、发布流程等都配套跟上。

编程语言

其实目前各大编程语言都已经找到了自己的位置：

JS/TS 除了做 web 应用，几乎还能做一切，不得不感叹前端圈真的太卷了！代表作 VS Code
Python 是数据处理和机器学习领域绝对的王，代表作 PyTorch
Golang 在各种分布式系统中发光发热，代表作 k8s
C/C++/Java 等“传统”的编程语言依旧在企业中大行其道，很难被替代

但是！这个问题我还是实在忍不住要讨论，因为我已经彻底锈化了！这里我不想再列举 Rust 开发的系统或者应用，甚至我也不想提 Rust 已经进入 Linux 内核领域，我觉得大家可以思考一下 AI 编程时代我们需要什么样的编程语言？

一种论调是，AI 编程时代语言已经不重要了，因为反正都是 AI 写。但是如果都是 AI 写，为什么不用一种，往上能编译成 WASM 给 JS 用，中间可以通过 pyo3 把性能敏感部分用 Rust 写成扩展，让 Python 关键路径飞起来，往下还能写数据库和 Linux 内核的语言？

AI 编程在很大程度上缓解了 Rust 之前广受诟病的那些问题：陡峭的学习曲线、和编译器的拉扯等。而且用 AI 写过代码的都知道，Rust 编译器这么强的检查对于功能保障太重要了！一定还会有新的编程语言出来，但是我认为 Rust 就是现在能看到的 AI 编程最佳理想型。

魔法库

魔法库在我这里是个贬义词，魔法库 == 过度设计。最典型的代表，Java 世界的 Spring，各种语言的 ORM 框架，以及炒得火热的 LangChain，其他的项目欢迎自己对号入座。

当然我不是一味否定他们的价值，流行一定有他的原因，有他的场景和受众，而且 AI 编程之前程序员是“体力劳动”的时代，有个代码库帮我们做点事情稍微减少我们的工作量还是有一定帮助的。在很多常见业务场景里，AI 直接帮你现搓一套简单实现往往已经够用，而且代码简洁清晰，想改就改，不必为魔法库的各种配置和绕路方案买单。

我认为在 AI 编程的时代，给公共库的开发者和使用者都提出了更高的要求：

对于开发者：这个库的功能足够单一吗？接口是标准的吗？对使用者系统的侵入性大吗？需要复杂的配置和学习成本吗？里面的魔法多吗？理论上来说越标准、越简洁、确定性越高的公共库，越适合被 AI 使用（当然也包括人，但是人有时候容忍度很高）。作为公共库的开发者，需要以各种语言的标准库的标准来要求自己。
对于使用者：也就是我们大多数人，需要建立自己的审美和世界观。这个库提供了什么功能？是不是最好的实现方式？有没有其他的不对代码太多侵入的方案？我的场景需不需要这么复杂的库？一定程度上，这并不比开发一个公共库更简单，因为理论上你随便写段代码放出去就可以认为自己做了个公共库，但是从使用者角度理论上你需要做好 Fork 任何公共库改为己用的准备，你能不能接受？

计算机的世界没有魔法，如果有，那我们应该成为参与者而不是旁观方。

测试

软件测试是软件开发过程中逃不开的话题，过往就有各种测试相关的技术被提出，各有千秋。在 AI 编程的时代，这件事应该要发生一些改变了。

最大的调整在于，在绝大多数业务系统里，我认为可以把对单元测试的执念放低，把精力更多迁移到集成测试或接口测试上。这里的原因很简单，因为 AI 实在是太会改代码了，在几分钟就能输出大块大块的代码，如果有一堆单元测试，势必会造成很多测试都失效，而且 AI 自己给自己的代码写的单元测试，很难保证能有什么用。

接口测试不一样，我们可以把测试当成一个一个的产品功能或者说故事：

功能稳定性得以保证，不管 AI 怎么发挥，就算它还避免不了一些低级错误，只要基本的故事是通的，不至于出现大的问题
维护成本较低，对于后端开发来说，除非预期中，我们很少会破坏现有的功能；接口测试一旦写好，不管代码细节怎么改，接口行为不能改变
降低沟通成本，这个测试文件甚至可以作为前后端联调的文档，通过这个文档后端可以告诉前端该怎么使用这些接口，参数和返回值的预期是什么

推荐一个 HTTP 测试工具叫 HURL ，谁用谁知道

Code Review

大厂里面，代码 Review 是一个永恒的问题，所有人都希望有人 review 他的代码，所有人都不愿意 review 别人的代码。这里最主要的原因在于，reviewer 作为不是写这份代码的人，很可能不了解需求或者代码库的细节，所以往往只能找找变量命名之类的错误，或者提一些代码组织上可有可无的变动，很难给出实际有效的建议。

AI 就不一样了，只要你开口，他可以孜孜不倦地帮你 review，并且如果你想，他还甚至直接给你把问题修复了，它不怕麻烦，也不怕承担责任（虽然它也不承担）。体感上，AI reviewer 给提交代码的人感觉不是一个”挑刺者“，而是一个帮我们减少问题的好伙伴。

目前市面上做得好的 code reviewer 不多，包括很多大厂做的工具。但是这里不得不夸一夸 OpenAI 的 Codex，不管是本地 review，还是和 github 集成的工具，都非常有效，真的能发现各种实际的问题，除了慢没毛病。

我相信 2026 年 code review 会变得越来越成熟可靠，和开发流程的结合也会越来越紧密，毕竟”资深程序员“都知道提交代码之前自己先 review 一遍。

单体架构

微服务架构过去几年已经一定程度上被祛魅了，随着新一波 AI 公司的兴起，以及 AI 编程的发展，我觉得单体架构会重新变得伟大。这里面主要有这样几个原因：

从 AI 编程的角度，单体架构能更好地让 AI 了解整个系统的上下文，避免各种微服务像魔法一样封装了各种不确定的行为，让 AI 只能靠猜。当然组织良好的微服务或者接口能一定程度上缓解这个问题，但是这会牵涉到第二点
从维护的角度，单体架构维护成本较低，只要配置好一套 CI/CD 流程，所有人都可以共享，Devops 的投入相对很少。并且开发的维护成本也比较低，如果是微服务想变个接口，还需要各种上下游协调，长期下去接口会变的臃肿和混乱

其实说到底微服务更多是团队组织上的需求，因为公司拆出来了各种团队，团队间为了有一个清晰的边界，所以服务也需要定义边界。AI 编程的普及首先会让公司对于团队规模的需求极度缩小，在不需要这么大团队规模的前提下，微服务的必要性就没那么高了。

可观测性

这个方向不知道什么原因，看到的相关新闻不多，但是我觉得是一个很好的方向。跟上面提到的代码 Review 类似，可观测性是系统上线后运维很重要的一部分。

目前我觉得机会很多：

过往监控系统最为人诟病的就是误报和漏报，一方面是因为监控规则实在晦涩难写（bosun 谁用谁崩溃），另一方面静态规则实在难以适应线上不断变化的场景，所以很多大厂做的“智能监控”实在很难称得上智能。
另外接入这些监控系统的门槛也不低，metrics 怎么打点，日志怎么格式化，这些长期需要占据研发很多心力
最后线上的问题往往是架构迭代方向的重要指导，过去往往是线上出事故了再来复盘，如果有 AI 能长期盯盘，防患于未然，那么 AI 又离“资深程序员”更进了一步随着这一波 AI 应用的野蛮生长进入稳定期，系统可观测性和服务稳定性一定会进入舞台中央，这一块的创业者们准备接受洗礼吧。

慢就是快

其实软件开发还涉及到很多其他方面，篇幅太长就写这些吧。最后想写一点，就是关于快与慢。

大模型跟过往工业革命一样，好像把世界变小了，时间变快了。一个最明显的例子，仅仅是过去几个月发布的模型，效果也不错，过了几个月好像就过时了一样。包括媒体上或者社区上，也不断会有人说一个周末做出了什么应用，一个月发布好几个版本，以及不到一年就数十亿美金卖了。所有的东西看起来都那么快在变化，如果不去学就跟不上了。作为浩瀚宇宙一个渺小的个体，我们应该如何自处？

我的建议，不要把自己变成别人的生意！不要以为点进去一条 twitter 看看也没什么，不要总在抖音浪费 15s，不要只看到“美颜”后的光鲜，要去看背后的真相。不管看到什么，先问问自己，我为什么看到这个信息？他为什么发这个信息？这个信息对我的影响是什么？这个信息对他的价值是什么？学会这个真的很简单吗？不学这个真的影响很大吗？

我想变成一个什么样的人？

没有什么毫无道理的横空出世。如果你觉得别人随随便便就成功了，那是因为你不了解他人在背后的积累和付出。在这样一个快速发展和变化的时代，我们反而应该慢下来思考、学习和沉淀。

多年以后，当你再面对黑色屏幕上闪动的白色光标时，你便会想起那个遥远的2026。那时，各种技术和工具层出不穷，人们兴奋地看着每天爆出来的新闻，指指点点。

感恩字节

Mon, 04 Aug 2025 00:00:00 +0000

如果用一个词来总结我在字节的日子，我想我会用成长。用这个词也很自然吧，毕竟初入职场后最重要的十年待在字节，并且还是一家成长这么快的公司，经常我还会反思自己的成长速度远远没有跟上公司的需要。对于字节我只有感恩，他不仅给了我超预期的工资回报，更重要的是给我有挑战的项目帮助我成长和证明自己，也给了我很多可以联系一辈子的朋友。

我要感谢我在字节的 leader 们，谢谢你们对我的指导和信任，特别是早期的 leader 容忍了我很多不成熟的做法；对一起合作过的同学，过往如果有沟通方式或者做事方式不对的地方，这里说一声抱歉；对于我之前指导过或者帮助过的同学，你们都有一个美好的未来，而且其中有不少已经做到了比我更重要的岗位。

字节依旧是一家伟大的公司，依旧会有很好的发展，祝福在字节奋斗的小伙伴们！

duckdb-rs will be the offical DuckDB rust client

Wed, 26 Jul 2023 00:00:00 +0000

Background

DuckDB is an in-process SQL OLAP database management system implemented in C++. When it was first open-sourced, it was positioned as a columnar database comparable to SQLite, providing the same ease of use. With just a header file and a cpp file, it could be easily embeded in any program, even offering a SQLite-compatible interface, which caught the attention of many people source.

I started paying attention to DuckDB a long time ago and began writing the first line of duckdb-rs code on June 7, 2021. About a month later, I wrote a blog post introducing the process of building this library, marking the completion of the initial version. Over the past two years, I have released approximately 19 versions, get more than 200 stars in GitHub.

In the past year, there have been many requirements and ideas for optimization, but I found myself lacking the time, and the number of received issues has been increasing. As a result, I will transfer this library to DuckDB offical organization, believing that make duckdb-rs an official client will lead to further progress and bigger success. Also I’d like to take this chance to thanks Mark and Hannes for building DuckDB and agree to accept duckdb-rs as the official rust client.

This blog post summarizes the main tasks I have undertaken during my maintenance period and points out areas that I believe can be improved.

Key Decisions

This library is the Rust client of DuckDB, so the primary audience interested in this library are users who appreciate DuckDB and use the Rust tech stack. Below are some key factors that I consider contributed to the “success” of this library:

Initial version based on rusqlite development. As a Rust beginner myself, I had previously only worked on one Rust project, and this was my second time using Rust. Based on rusqlite, a mature repository, allowed me to quickly obtain a usable version. Additionally, the code structure and API design had already been validated, reducing the likelihood of taking wrong turns. Moreover, the overall code quality could be reasonably assured.
Data exchange based on the arrow format. Arrow is now considered the columnar storage data exchange standard and is used in many open-source projects. DuckDB has good support for arrow as well. Although DuckDB has its native C interface, using the arrow format for data exchange allows relatively stable interactions between Rust and the C API. This approach ensures that we won’t need to make frequent changes due to DuckDB iterations, thus reducing maintenance efforts and minimizing the impact of interface changes on users.
Robust CI process. I believe that all open-source projects should strive for this. With a CI process, we can ensure that the code merged into the master branch was error-free. The CI process also included memory leak detection, avoiding potential safety issues introduced by the FFI. The release process was automated as well, with crates being automatically published by tagging.

Notable MRs

I’ve selected a few MRs that I consider significant and that weren’t contributed by me:

Add github workflow: This was the first MR to add CI checks, which was very meaningful as I used to push directly to master before CI was in place.
Add r2d2 connection pool: This MR added a connection pool, improving the library’s performance.
Rework bundled compilation to support included extensions: This was the largest MR and allowed the library to support extensions, reworking the logic of bundling DuckDB source code to include various extensions without requiring additional installations.
Feat: Develop query polars: This MR added support for converting query results into polars data structures. polars is a popular data processing tool written in Rust. This feature bridged the gap between DuckDB and polars.

Apart from the daily maintenance, I didn’t contribute to the development of major features significantly. Support table function can be considered one, and I believe writing extensions in Rust is simpler and safer compared to C/C++.

Outstanding Issues

Due to limited time and resources, there are still some unresolved issues in this library:

Better documentation. Writing documentation has always been a headache for me since English is not my strong suit. While this library inherited some documentation from rusqlite, it lacks ongoing maintenance, especially regarding documentation specific to DuckDB features. Good documentation and blog posts are key to the success of an open-source project.
Support for more data types. There are two categories of data types: those mapped to Rust data types for results, which are not a high priority since arrow-rs already provides comprehensive data types for users working with arrow data. The other category is query parameters, where we need to support a wider range of data types for better user convenience. Currently, we only support some basic query data types.
Improved support for data insertion. Columnar databases require the ability to insert data in batches, such as using DuckDB’s built-in append interface or supporting insertion of arrow data.
Compilation process optimization. As DuckDB’s features expand, the compilation process for this library has become slower and resource-consuming, resulting in larger build artifacts.
Support for specific DuckDB interfaces, such as streaming query or relation API. These have been raised as issues by some users.

To achieve the same level as DuckDB in terms of documentation and interfaces, there is still much work to be done.

Future Plans

With the publication of this article, it means I am no longer the maintainer of duckdb-rs. However, this does not mean that I will no longer contribute code to duckdb-rs. I will continue to follow DuckDB and duckdb-rs and contribute code in my spare time.

If I have time, I may also work on other projects based on duckdb-rs, such as:

Creating a Rust extension for DuckDB to become a vector database
Or building a storage server based on duckdb-rs primarily using the arrow-flight protocol. If I have even more time, I might add support for Raft to enable distribution. I’m not sure how useful these projects would be, but they sound like fun.
Another possibility is creating a distributed data processing tool, using DuckDB as intermediate data storage or for computation acceleration.

Translated from CN Version using ChatGPT and polished manually.

duckdb-rs 即将成为 DuckDB 官方 rust 客户端

Wed, 26 Jul 2023 00:00:00 +0000

背景

DuckDB 是一个 C++ 编写的单机版嵌入式分析型数据库。它刚开源的时候是对标 SQLite 的列存数据库，并提供与 SQLite 一样的易用性，编译成一个头文件和一个 cpp 文件就可以在程序中使用，甚至提供与 SQLite 兼容的接口，因此受到了很多人的关注。

我很久之前就开始关注 DuckDB，并在 2021-06-07 开始写第一行 duckdb-rs 的代码，在一个多月后写了一篇博客介绍了构建这个库的过程，算是实现了第一个版本。到今天差不多2年的时间，前后发布了19个版本，收获了 200 多个star。

最近一年其实还有很多需求和想法去做优化，但是发现自己并没有那么多时间，收到的 issue 也越来越多。经过沟通，我会把这个库转给 DuckDB 官方来维护，相信 duckdb-rs 一定会发展得越来越好。同时也非常感谢 Mark 和 Hannes 愿意接手这个仓库并把它作为官方的 rust 客户端。

这篇博客总结下我维护的这段时间主要做的事，以及我认为可以改善的点，算是对过去的总结和对未来的憧憬。

关键决策

这个库是 duckdb 的 rust 客户端，所以关注这个库的群体首先是认可 duckdb 的用户，其次因为他们是 rust 技术栈。下面我列举一些我认为是让这个库“成功”的一些关键点。

初始版本基于 rusqlite 开发。因为我也是一个 rust 初学者，之前只拿 rust 做过一个项目，这是第二次使用 rust。基于 rustqlite 这样一个成熟的仓库做改造，能让我很快得到一个可用的版本，快速建立信心；另外整个程序的组织，API 的设计都已经经过了验证，不容易走弯路；整体的代码质量也能有基本保障。
基于 arrow 格式来交换数据。arrow 现在基本上算是列存储的数据交换标准，在很多开源项目中都有使用，duckdb 对 arrow 的支持也比较完善。虽然 duckdb 有自己的原生 C 接口，但是基于 arrow 格式来做数据交换，能让 rust 和 c-api 调用相对稳定，不会因为 duckdb 迭代导致 C 接口的变更，我们也需要一直变更，一定程度上减轻了维护的工作量，也减少了接口变更对用户的影响。
完善的 CI 流程，我认为所有的开源项目都应该要做到这一点。因为继承自 rusqlite，这个库从一开始就有 CI 流程，能保证合并到 master 的代码是没问题的，并且 CI 里面还有关于内存泄漏的检测，避免了 ffi 带了的可能不安全的问题。发布过程也是自动化的，只要打个 tag 就自动发布到 crate。CI 的机制保障了任何感兴趣的人都可以提交 MR 并得到检验，也保证自己如果长时间不维护了不至于都不知道从哪里开始改。

几个 MR

下面我挑选几个我认为比较关键的，并且不是我贡献的 MR：

Add github workflow，之前我都是直接 push master，这是第一个 MR 添加 CI 检测，非常有意义！
add r2d2 connection pool，添加连接池。
Rework bundled compilation to support included extensions，收到最大的一个 MR，为了支持 extension，重做了 bundle duckdb 源码的逻辑，让这个仓库也能打包进去各种扩展而不用额外安装。
Feat: Develop query polars，支持把 query 的结果转成 polars 的数据结构，polars 是目前 rust 写的一个非常流行的数据处理工具，这个功能打通了 duckdb 和 polars。

我自己除了日常维护之外，实际上大的功能开发比较少，Support table function 算是一个，并且我认为基于 rust 写扩展远比基于 c/c++ 来写更简单，更安全！

遗留问题

因为精力有限，这个库还有一些问题需要解决：

更好的文档。因为我的英语也是半路出家，所以写文档一直是想起来就头疼的问题。这个库因为是基于 rusqlite，所以继承了一部分文档，所以基本质量还在，但是后续缺少维护，特别是针对 duckdb 特性的一些文档资料比较少。好的文档和博客也是开源项目成功的关键。
支持更多数据类型。这里的数据类型分两类，一类是对于结果，映射到 rust 的数据类型，这部分的需求倒是不高优，特别是用户如果是使用的 arrow 数据的话，arrow-rs 本身有完整的数据类型；另一类是查询参数，这部分需要支持更多的数据类型绑定，方便用户使用。目前我们只支持了一些基础的数据类型。
更完善的数据插入支持。列存数据库需要有批量插入数据的能力，比如 duckdb 自带的 append 接口，或者支持插入 arrow 的数据等，目前这一块支持得不太好。
编译过程优化。随着 duckdb 功能丰富，这个库的编译也越来越慢，对资源的消耗也越来越多，编译的产物也越来越大。
一些 duckdb 或者列存特定的接口支持，比如 streaming query 或者 relation api，这些都有人提过 issue。

从文档和接口上，要达到和 duckdb 一样的水准，还有不少工作要做。

后续计划

这篇文章发布的时候，意味着我不再是 duckdb-rs 的维护者。但是这不代表着后续我不再给 duckdb-rs 贡献代码，我还是会继续关注 duckdb 和 duckdb-rs，并且在闲暇的时候贡献一些代码。

如果有时间还可以基于 duckdb-rs 做一些其他的项目，比如用 rust 给 duckdb 做一个向量数据库的扩展，或者基于 duckdb-rs 搭建一个存储的 server，主要是基于 arrow-flight 协议，如果再有时间还可以加上 raft 支持分布式。不知道有什么用，但是感觉是个很好玩的项目。也可以考虑做一个分布式数据处理的工具，用 duckdb 做中间数据的存储或者计算加速等。

基于 apache-arrow 的 duckdb rust 客户端

Tue, 27 Jul 2021 00:00:00 +0000

背景

duckdb 是一个 C++ 编写的单机版嵌入式分析型数据库。它刚开源的时候是对标 SQLite 的列存数据库，并提供与 SQLite 一样的易用性，编译成一个头文件和一个 cpp 文件就可以在程序中使用，甚至提供与 SQLite 兼容的接口，因此受到了很多人的关注。

本文介绍笔者近期开发的 duckdb-rs 库，让大家可以很方便地在 rust 代码库中使用 duckdb 的功能。

libduckdb-sys

了解过 rust 的同学可能知道，rust 提供了 ffi 的方式与其他语言互通。因为 duckdb 本身是 C++ 编写的，想要在 rust 里面使用 duckdb，就需要考虑 ffi 的问题。而基于 ffi 对其他语言程序封装的基础库，一般会被命名为 libxxx-sys，这也就是 libduckdb-sys 的由来。

为了方便大家使用，duckdb 提供了 C++ 原生接口，C 接口，以及与 SQLite3 兼容的 C 接口。我在做 libduckdb-sys 的时候对这三种接口都尝试过，相关的讨论可以参见 Rust Support，我这里介绍一下当时的情况。

基于 SQLite3 接口

最开始我使用的是 SQLite3 的接口，原因主要有三个：

我对 SQLite 比较熟悉，想必用起来会比较方便；
觉得 SQLite 的接口被广泛使用，接口比较稳定，以后不至于大改；
也许是最重要的一点，市面上已经有 SQLite 的 rust 封装rusqlite，基于 SQLite 的接口应该能最大程度复用 rusqlite 的代码。

尝试之后确实发现很快能把程序跑起来，基本的功能也能使用。但是随着进一步的深入以及对 duckdb 更多的了解，发现了一些弊端：

虽说 duckdb 是想最大程度兼容 SQLite，但是毕竟一个是行存一个是列存，有区别在所难免，接口肯定也没办法做到 100% 兼容；
有一个区别需要特别提出来，SQLite 是动态数据类型，而 duckdb 是静态类型，也就是说在 SQLite 中你可以认为所有的数据都是存成 Text，在读取的时候根据 schema 来解析数据；而 duckdb 是会根据数据类型来存储数据，并且根据列存的特性做一些存储优化。有了这个区别之后，如果我们使用 SQLite 的接口的话，会做一些不必要的数据格式转换，性能有损，程序也不直观。
duckdb 可以被编译成一个 so 使用，如果想使用 SQLite 的接口，需要再编译一个 sqlite3_api_wrapper 出来，两个库合作才能使用 SQLite 的接口，这给程序分发引入了额外的负担；另外目前 duckdb 在 release 的时候没有自带 sqlite3_api_wrapper，需要用户自己去编译，使用上又多了一些不便。
由于上面的封装的问题，数据类型的问题，以及通过 SQLite 接口查询 duckdb 的数据时候，结果集会被复制一遍，资源占用必定上升。

基于上面一些原因，我最终放弃了基于 SQLite 接口来开发，转而尝试使用原生的 C++ 或者 C 接口。

基于 C++ 接口

既然为了性能和接口丰富性，使用 C++ 接口当然是首选，毕竟 duckdb 本身主要都是拿 C++ 开发的，duckdb 的 python 封装也是拿 C++ 接口来做的。

市面上也有方便 rust 与 C++ 交互的一些代码库，比如 cxx 和 autocxx。其中 autocxx 入手门槛低使用上更简单，而 cxx 的可定制性更强，功能更丰富。在尝试了几次之后发现了一些问题，主要还是 rust ffi 只能支持部分的 C++ 语法，大部分情况下可能是够用的，但是对于 duckdb 这样比较大型的数据库代码，还是有很多不支持的地方。除非自己再基于现有的 C++ 接口封装一份支持 cxx 的版本，否则就算这一次编译过了，也很难保证以后 duckdb 的作者以后不会引入其他的特性导致不能兼容。

而 rust 基于 C 语言的 ffi 是原生支持的，所以最终还是下定决心基于 C 接口来开发。

基于 C 接口

因为有 rusqlite 作为参考，所以很快实现了基于 C 接口的版本。简单来说，主要是通过 cbindgen、build.rs 和 rust 的 features 功能来实现。其中：

cbindgen 用于生成基于 C 接口的 rust 代码，方便 rust 其他程序使用
build.rs 和 features 用于控制整个编译流程，用户可以根据需要是当场编译依赖库，还是使用机器上已经安装好的版本
build.rs 中还可以选择使用 cc 来实时编译 duckdb 实现，这样其他使用 rust 封装的人不用关心 duckdb 的安装问题

应该说这是一个很通用的提供 C 接口 rust 封装的解决方案，感兴趣的同学可以参考。

duckdb-rs

完成了 libduckdb-sys 之后其实只是第一步，因为这样生成的代码都是 unsafe 代码，具体的使用例子可以参考 lib.rs 中的测试代码。但是我们使用 rust 主要是为了他的安全性，rust 希望我们尽量减少 unsafe 的使用。所以一般的 rust 封装都会基于 libxxx-sys 提供一个内存安全的版本，这就是 duckdb-rs 的部分。

小试牛刀

还是因为有 rusqlite 的参考，所以花了一些时间终于实现了最初始的版本，并且我已经把这个版本发布到 crates.io 上了。这个版本的目标是基于 rusqlite 做最小的改动，并删掉 SQLite 特有的功能，让整个程序跑起来。完成之后效果不错，下面是文档中给的一个使用范例：

use duckdb::{params, Connection, Result};

#[derive(Debug)]
struct Person {
 id: i32,
 name: String,
 data: Option<Vec<u8>>,
}

fn main() -> Result<()> {
 let conn = Connection::open_in_memory()?;

 conn.execute_batch(
 r"CREATE SEQUENCE seq;
 CREATE TABLE person (
 id INTEGER PRIMARY KEY DEFAULT NEXTVAL('seq'),
 name TEXT NOT NULL,
 data BLOB
 );
 ")?;

 let me = Person {
 id: 0,
 name: "Steven".to_string(),
 data: None,
 };
 conn.execute(
 "INSERT INTO person (name, data) VALUES (?, ?)",
 params![me.name, me.data],
 )?;

 let mut stmt = conn.prepare("SELECT id, name, data FROM person")?;
 let person_iter = stmt.query_map([], |row| {
 Ok(Person {
 id: row.get(0)?,
 name: row.get(1)?,
 data: row.get(2)?,
 })
 })?;

 for person in person_iter {
 println!("Found person {:?}", person.unwrap());
 }
 Ok(())
}

可以看到，接口设计非常优雅，代码也非常符合 rust 的风格，使用上也非常方便。实现过程中发现有些 duckdb 的 C 接口还不支持的部分，我也通过提 issue 或者 PR 去解决了。这里必须要提一点，duckdb 的维护者非常耐心，不管是回答问题还是 review 代码都非常专业。

剩下的问题有一个是之前提到的，duckdb 是静态类型的数据，所以需要支持很多数据类型，这里面工作量不小。另外，因为我之前也有关注 Apache Arrow，做过 OLAP 数据库的同学可能知道，Apache Arrow 是一个通用的列式内存格式，方便在内存中做大数据量的计算或者传输，有很多 OLAP 数据引擎都在用。刚好 duckdb 也支持 arrow 格式，所以就想尝试使用 arrow 格式来查询数据，这样至少有两个好处，一个是这样我们就可以暴露 arrow 格式的数据给用户，在使用的时候就可以用上 arrow 生态的其他功能，有可能会产生一些化学反应；另外 arrow 也是有丰富的数据类型和明确的定义，反正我们是要支持很多数据类型的，现在的 C 接口本身也不完善，用 arrow 格式反而更加清晰。

通过 Apache Arrow 查询数据

基于上面的考虑，我把目标又看向了 arrow-rs，并给 duckdb 的 C 接口也加上了 arrow 的功能，最终在 duckdb-rs 中实现了通过 Arrow 格式来查询数据，实现参见这里。

实现之后，之前通过行来读取数据的接口完全不变，还能直接查询到 Arrow 格式的数据，下面是一个测试的例子：

fn test_query_arrow_record_batch_large() -> Result<()> {
 let db = Connection::open_in_memory().unwrap();
 db.execute_batch("BEGIN TRANSACTION")?;
 db.execute_batch("CREATE TABLE test(t INTEGER);")?;
 for _ in 0..300 {
 db.execute_batch("INSERT INTO test VALUES (1); INSERT INTO test VALUES (2); INSERT INTO test VALUES (3); INSERT INTO test VALUES (4); INSERT INTO test VALUES (5);")?;
 }
 db.execute_batch("END TRANSACTION")?;
 let rbs = db.query_arrow("select t from test order by t", [])?;
 assert_eq!(rbs.len(), 2);
 assert_eq!(rbs.iter().map(|rb| rb.num_rows()).sum::<usize>(), 1500);
 assert_eq!(
 rbs.iter()
 .map(|rb| rb
 .column(0)
 .as_any()
 .downcast_ref::<Int32Array>()
 .unwrap()
 .iter()
 .map(|i| i.unwrap())
 .sum::<i32>())
 .sum::<i32>(),
 4500
 );
 Ok(())
}

可以看到，我们查询到 Arrow 格式的数据之后，还能通过 arrow-rs 中提供的其他能力做进一步的计算，十分方便。

总结

本文主要介绍了 duckdb-rs 的设计和实现，笔者之前有一些开发 OLAP 数据的经验，但是对于 rust 算是新手，之前虽然写过一些但是没有深入学习，做这个项目也有一个目的是为了重新学习一下 rust。好在有 rusqlite 作为参考，所以没有碰到特别多语言层面的问题。

希望这篇文章对于其他对 rust 和数据库感兴趣的同学有一些帮助。同时这个库还有很多没解决的问题，比如支持更多的数据类型，支持连接池，支持更快的数据导入接口等等，我已经建了一些 issues，感兴趣的同学可以回复 issue 认领，我也会竭力提供需要的帮助，大家一起讨论和学习。

参考

duckdb 的官网：https://duckdb.org/
duckdb 的代码库：https://github.com/duckdb/duckdb
SQLite 的 rust 封装，duckdb-rs 也是基于它改的：https://github.com/rusqlite/rusqlite
duckdb-rs 的代码库：https://github.com/wangfenjin/duckdb-rs
Apache Arrow 的 rust 实现：https://github.com/apache/arrow-rs

Simple: SQLite3 结巴分词插件

Sun, 21 Feb 2021 00:00:00 +0000

一年前开发 simple 分词器，实现了微信在两篇文章中描述的，基于 SQLite 支持中文和拼音的搜索方案。具体背景参见这篇文章。项目发布后受到了一些朋友的关注，后续也发布了一些改进，提升了项目易用性。

最近重新体验微信客户端搜索功能，发现对于中文的搜索已经不是基于单字命中，而是更精准的基于词组。比如搜索“法国”，之前如果句子中有“法”和“国”两个字时也会命中，所以如果一句话里包含“国法”就会被命中，但是这跟“法国”没有任何关系。

本文描述对 simple 分词器添加的基于词组命中的实现，从而实现更好的查找效果。另外本文也会基于之前在 issue 中大家提到的问题，提供一个怎么使用 SQLite FTS 表的建议。

背景

先简单回顾一下之前的实现，因为结巴分词只跟中文有关，所以本文会略去拼音的部分。

搜索主要分为两部分，建立索引和命中索引。为了实现中文的搜索，我们先把句子按照单字拆分，按照单字建立索引；然后对于用户的输入，也同样按照单字拆分，这样 query 就能命中索引了。为了支持词组搜索，再按照单字拆分就很难满足需求了，所以可以考虑的方案是要么改索引，要么改 query。如果改索引的话会有一些问题，比如如果用户就输入了一个字比如“国”，但是我们建索引的时候把“法国”放到了一起，那“国”字就命中不了了，所以最好是保持单字索引不变，通过改写 query 来达到检索词组的效果。

实现

simple 分词器之前提供了一个 simple_query() 函数来帮助用户生成 query，我们也可以加一个新的函数来实现词组的功能。经过简单的调研，我们发现 cppjieba 用 C++ 实现了结巴分词的功能，很适用与我们的需求。

所以我实现了一个新的函数叫做 jieba_query() ，它的使用方式跟 simple_query() 一样，内部实现时，我们会先使用 cppjieba 对输入进行分词，再根据分词的结果构建 SQLite3 能理解的 query ，从而实现了词组匹配的功能。具体的逻辑可以参考这里。对于不需要结巴分词功能的用户，可以在编译的时候使用 -DSIMPLE_WITH_JIEBA=OFF 关闭结巴分词的功能，这样能减少编译文件的大小，方便客户端对文件大小敏感的场景使用。

使用

本文想着重介绍一下 SQLite3 FTS5 功能使用的问题，这些问题都是有朋友在项目的 issue 中提到过的，都是非常好的问题，但是也说明有不少人对怎么使用 FTS 表不太清楚，希望本文能解决一些疑惑。

首先第一点，FTS5 表虽然是一个虚拟表，提供了全文搜索的功能，但是它整体还是跳不出 SQL 的范畴，所以其实很多用法和其他 SQL 表是一样的，当然它也跳不出 SQL 的限制。比如有一个 issue 问如果表中有多列的时候，能不能检索全表，但是只返回命中的那些列？答案是不行的，因为按照 SQL 的语法规则，SELECT 语句后面必须显示说明你想要 SELECT 哪些列，所以结果列是必须用户指定的，如果我们像知道哪些列命中了，只能通过其他一些手段，感兴趣的朋友可以看这个 issue36。

另外 simple 分词器提供了不少额外的功能，比如 simple_query() 和 simple_highlight() 等辅助函数，但是它并不影响我们使用原有 FTS5 的功能，比如如果想按照相关度排序，FTS5 自带的 order by rank 功能还是可以继续可以使用，也就是说 FTS5 页面提供的所有功能都是可以和 simple 分词器一起使用的。

最后也是最重要的一个问题，FTS5 表到底该怎么用？有一个 issue26 提到的问题非常好，我把它放到这里：

《微信全文搜索优化之路》一文中针对索引表的介绍，我对索引有几个问题想请教一下：

业务表是正常的程序的数据表，还要再为了全文搜索再多建立一份索引表，是吗？我直接将我的业务数据表在创建的时候按虚表建立行吗？（例如create virtual table tablename using fts5(列名1,列名2,tokenize = ‘simple’)）

如果再多建立一份索引表，那是不是每一个业务表和对应的索引表的表字段是完全相同？

如果再多建立一份索引表，那数据库的大小是不是加倍了，尤其是把文件或图片影片存入数据库的情况（BLOB类型）？

原文中【为了解决业务变化而带来的表结构修改问题，微信把业务属性数字化】，这也是我想要的，能否帮助贴下原文中提到的【索引表-IndexTable】和【数据表-MetaTable】的建表语句？

核心的问题是：想让表数据支持全文搜索，需要把数据复制一份吗？这样会不会导致数据库膨胀？在用户的手机上我们可不想占用太多无谓的空间。

externel content table

其实这个问题在 FTS5 的官方文档中已经给出了解决方案那就是 externel content table，大家也可以参考这篇文章。

它的意思是我们可以建一张普通表，然后再建一张 FTS5 表来支持全文索引，这张虚拟表本身不会存储真实的数据，如果 SELECT 语句用到具体的内容，都会通过关联关系去原表获取，这样就不存在数据重复的问题了。但是这里就会涉及到数据一致性的问题，怎么保证原表的数据和索引表是一致的呢？通过 trigger 也就是触发器来实现：对于原表的增删改，都会通过触发器同步到 FTS 表。这样基本上就完美解决了上面用户的问题。

可能有人会问为什么不直接用 FTS5 表呢？这样普通表就不用了，也省了触发器的逻辑。原因是 FTS 表提供了全文索引的能力，但是它也有限制，对于基于 ID 或者其他普通索引的请求它是不支持的，如果我们想有一个时间列并且基于时间列索引排序，FTS表就不行，还是需要普通表。通过普通表和 FTS 表结合的方案，我们就能同时使用两者的能力。

微信的方案

需要注意的是，微信并没有使用上面提到的方案，而是单独建了一张打平的索引表，把所有需要全文索引的数据放到一张单独的表里面，再通过外键关联到具体的业务去。这样的好处在微信的文章中有所提及，主要是其他关联的表结构变更的时候，FTS 表不用动，这样很容易添加想要搜索的字段，只需把该字段写入 FTS 表及关联关系的表就行，表结构见下图：

个人觉得对于微信这个复杂度的业务，可以考虑这个方案，毕竟需要搜索的信息非常多，这样方便各个业务复用搜索能力。但是对于大部分的业务，用 external content table 可能是更简单的方案，毕竟在数据写入和读取的时候都更快更方便，微信的方案在数据操作流程上会复杂不少，需要逻辑上做更多的封装。

总结

上面主要介绍了 simple 分词器最新的功能，基于结巴分词实现基于词组的搜索功能，实现更精准的匹配。另外也介绍了在实际项目中使用 FTS 表的方案，希望对大家有所助益。

Reference

Simple 分词器: https://github.com/wangfenjin/simple
sqlite 官方文档：https://www.sqlite.org/fts5.html
微信全文搜索优化之路：https://cloud.tencent.com/developer/article/1006159
微信移动端的全文检索多音字问题解决方案：https://cloud.tencent.com/developer/article/1198371
Simple: 一个支持中文和拼音搜索的 sqlite fts5插件：https://www.wangfenjin.com/posts/simple-tokenizer/
Full Text Search With Sqlite SQLite：https://kimsereylam.com/sqlite/2020/03/06/full-text-search-with-sqlite.html

xeus-clickhouse: Jupyter 的 ClickHouse 内核

Sun, 28 Jun 2020 00:00:00 +0000

在科学计算领域，Jupyter 是一个使用非常广泛的集成开发环境，它支持多种主流的编程语言比如 Python, C++, R 或者 Julia。同时，数据科学最重要的还是数据，而 SQL 是操作数据最直观的语言。前段时间看到一篇文章，有人给 sqlite 做了一个 jupyter 的内核，感觉很有意思。所以我尝试给 ClickHouse 做了一个 jupyter 的内核，目前已经有了一个可以试用的版本，下面做一个简单介绍。

现状

新内核允许用户用 ClickHouse SQL 的语法直接操作远程 CH 数据库，通过一些扩展操作比如 %CONNECT 支持与 ch cli 一样的连接参数，后续也有计划使用 jupyter magics 支持更多的数据可视化操作。

项目参考了 jupyter sqlite 内核的实现方式，是基于 xeus 框架来实现的。xeus 是一个 c++ 的 lib 库，它对 jupyter 的内核做了很好的封装，我们只需要专注于内核相关的功能就可以了。目前对于 ch 的操作基于 clickhouse-cpp 来实现，它是 ch 的 cpp 客户端。

目前实现处于早期阶段，但是基础功能已经可用。它支持了几乎 CH 所有 SQL 语法，具体例子可以参考 clickhouse.ipynb。xeus-clickhouse 在 jupyter notebook 和 jupyter lab 中以 HTML 表格的形式展示数据；在 jupyter console 中，我们使用 tabulate 库只做纯文本的表格。

未来

对于 xeus-clickhouse 未来的规划是，先打磨好稳定性，目前已知的还有一个非法字符导致内核崩溃的问题，已经提交 issue 给 xeus 仓库；另外clickhouse-cpp 不支持 ssl 连接。除了基础功能的打磨，还计划通过支持更多的 jupyter magic 来实现数据的可视化渲染，提供更方便的数据可视化能力。

使用

我制作了一个 Docker 镜像发布在 docker-hub，不需要安装任何环境就可以试用：

# start jupyter with clickhouse kernal
docker run -p 8888:8888 wangfenjin/xeus-clickhouse:v0.1.0

# start a local clickhouse for testing
docker run -d --name jupyter-clickhouse-server -p 8123:8123 --ulimit nofile=262144:262144 yandex/clickhouse-server

# open the example/clickhouse.ipynb and connect to local server by 
# %CONNECT --host host.docker.internal --port 8123

在 docker 里面连接另外一个 docker 中的 ch 可能会有问题，感觉是目前 clickhouse-cpp 对于网络的处理不太完善。感兴趣的同学也可以下载代码自己编译，具体的编译流程见 github 仓库。欢迎大家试用！

用 od 查看 ClickHouse 的索引文件

Wed, 18 Mar 2020 00:00:00 +0000

背景

学习 ClickHouse (后面简称 CH) 的时候，会对 CH 到底怎么组织磁盘上的 MergeTree 文件有很多疑惑。关于 MergeTree 的介绍可以参考[1]，但是如果想具体看下磁盘上的文件，没有现成的工具。本文参考 [2] 介绍通过 od 查看磁盘文件的方法，感兴趣的话可以自己试一下，会对 MergeTree 有更深的理解。

本文以官方Tutorial 中的 hits_v1 表为例来说明。下面主要描述怎么看 primary.idx 文件和 [column].mrk 文件。在 MergeTree 数据结构中，primary.idx 可认为是一级索引，mrk 文件是用作定位具体文件偏移量的，他们的行数是相同且一一对应。

查看 primary.idx

primary.idx 里面的文件是把主键的索引写入到磁盘文件中，hits_v1 的主键为 order by 语句中的字段，即 ORDER BY (CounterID, EventDate, intHash32(UserID))，CounterID 类型是 uint32，存储为4字节；EventDate 类型是 Date，存储是 2字节整型；intHash32 是4字节整型。CH 的文件内容非常紧凑，每个字段是紧挨着写入的，没有其他类似空格符等浪费。所以 primary.idx 的存储格式是 4+2+4，然后每隔 8192 行写一行索引。查看内容的方法为：

# sql 选择第一行索引的内容
Select CounterID,toRelativeDayNum(EventDate),intHash32(UserID) from tutorial.hits_v1 limit 0,1;

# od 查看 3 个字段
od -An -i -j 0 -N 4 primary.idx
od -An -i -j 4 -N 2 primary.idx
od -An -i -j 6 -N 4 primary.idx

# 类似的，sql 选择第二行索引的内容
Select CounterID,toRelativeDayNum(EventDate),intHash32(UserID) from tutorial.hits_v1 limit 8192,1;

# od 查看 3 个字段
od -An -i -j 10 -N 4 primary.idx
od -An -i -j 14 -N 2 primary.idx
od -An -i -j 16 -N 4 primary.idx

关于 od 的选项介绍如下：

-An 是不让输出偏移只输出文本内容
-i 是说把选择的位当作长度为 4 的整型输出；对于 EventDate 虽然存储的是 2，但是我们把它当作 4 位输出也没问题，主要控制在 -j -N
-j 偏移的起始字节数
-N 从偏移量开始读取的字节数

-A,-j, -N 这几个选项是必须有的，-i 得看数据类型是啥，还支持其他的比如字符、浮点类型等

从上面可以看到，想查看 primary.idx 的文件，需要知道主键的排列顺序和主键的类型，没办法像 parquet tools 一样很简单地写一个通用程序来直接查看文件。

查看 [column].mrk

mrk 文件是辅助定位 bin 文件设置的。bin 文件被分成小的数据块，每个数据块压缩后存放到一起。可以参考从 [1] 中的截图：

mrk 文件行数与 idx 文件一致，每行包含两个固定为 8 字节的整型，第一个整型是 [column].bin 文件的偏移量定位到具体的数据块，第二个整型是把数据块解压后定位解压后的文件偏移。查看 mrk 的脚本如下：

#!/bin/bash

if [ -z "$1" ]; then
 echo "Missing filename, mrk.sh file.mrk"
 exit 1
fi

filename=$1
len=$(wc -c < $filename)
offset=0
maxline=10
if [ $((len/16)) -gt $maxline ]; then
 echo "$filename first $maxline lines:"
else
 echo "$filename content:"
fi
while [ $((offset+16)) -le $len ] && [ $maxline -gt 0 ]; do
 line=$(od -An -t d8 -j $offset -N 8 $filename)","$(od -An -t d8 -j $((offset+8)) -N 8 $filename)
 echo $line
 offset=$(($offset+16))
 maxline=$(($maxline-1))
done

查看 mrk 文件的脚本是通用的，传入文件名就可以了。它的正确性也是可以验证的，比如对于 UserID 这个字段，它是 uint64 型，即占用 8 个字节，8192 行就是 65536 个字节；刚好 bin 文件中数据块的默认最小值是 65536，所以会发现 UserID.mrk 文件第二列的值永远为 0，因为刚好解压缩后的偏移量是 0。

对于 CounterID.mrk 文件，它是 int32 占用 4 个字节，所以能看到第二列的值是可能出现非 0 的。

总结

CH 没有提供简单的方案查看 idx 和 mrk 文件的内容，我们可以通过 od 来模拟实现，能帮助我们更好了解 MergeTree 这个数据结构。

参考

朱凯老师关于 MergeTree 的介绍：https://github.com/ClickHouse/clickhouse-presentations/blob/master/meetup32/朱凯.ppt
一个俄语的 PPT 提到 od 的使用，想自己看 PPT 的话可以用 Google 翻译：https://github.com/ClickHouse/clickhouse-presentations/blob/master/meetup27/adaptive_index_granularity.pdf

Spacemacs Intro

Thu, 12 Mar 2020 00:00:00 +0000

Intro video: https://www.ixigua.com/i6803300850765660676/

What’s spacemacs?

A emacs configuration framework
Support both emacs and vim editing styles
Great programming tool

Project management: SPC+p

projectile

SPC+p+p
SPC+p+f
SPC+p+t

Search: SPC+s

ripgrep

SPC+*
SPC+/
SPC+s+s

lsp

Code: gd, SPC+j+i
Buffer: SPC+b
Window: SPC+w, ALT+num
SPC+a

Editing: vim

evil

Version Control: magit

Shell: SPC+'

eshell

Help: SPC+?, SPC+h

Simple: 一个支持中文和拼音搜索的 sqlite fts5插件

Sun, 08 Mar 2020 00:00:00 +0000

之前的工作关系，需要在手机上支持中文和拼音搜索。由于手机上存储数据一般都是用 sqlite，所以是基于 sqlite3 fts5 来实现。这段时间再次入门 c++，所以想用 c++ 实现一下，一来用于练手，二来当时做的时候发现网络上这方面开源的实现不多，也造福下其他人。

背景

搜索现在几乎是每个 APP 必备的功能，用户已经习惯了搜索框搜一下，避免到处去找。搜索也是帮助用户查找旧信息，发现新功能的一个重要手段。平常我们用微信的时候经常会搜索联系人和聊天记录，发现微信这一块做的还是非常好的。关于微信的全文搜索，可以看看这两篇文章：微信全文搜索优化之路和微信移动端的全文检索多音字问题解决方案。

第一篇文章主要是问题和原理的概述，第二篇文章是核心分词器的实现。我写的这个项目主要是实现了 simple 分词器，并提供一些辅助函数帮助使用。

Simple 分词器

搜索的核心是建倒排索引，建索引的核心是分词器。跟名字一下，Simple 分词器的规则非常简单：

空白符跳过
连续的数字作为整体是一个索引
连续的英文字母作为整体并转换成小写索引
中文字单独建索引，并且把中文字转成拼音后也建搜索，这样就能同时支持中文和拼音检索。另外把拼音首字母也建索引，这样搜索 zjl 就能命中 “周杰伦”。
其他字符统一单独建索引，这样搜索 😊 也能搜到

上面的 5 条都比较好理解，关于中文为什么这么做（而不是连续的中文一起建索引），是由于客户端搜索的需求决定的。具体可以参考上面微信的两篇文章。

有了上面的规则，代码写起来就很简单了，核心逻辑 30 行就解决了。这块代码运行效率也比较高，一遍扫描 O(n) 的复杂度就完成了分词操作。

query 拆分

索引建好之后，query 需要根据分词规则来写才能查询到数据。比如根据上面的逻辑：

如果查数字，我们要把搜索词当作前缀来用，比如用户搜索 123， query 就需要换成 123*，这样如果索引里面有 12345 也能被搜索出来
对于英文，除了要当作前缀，还需要把搜索词转成小写，比如用护搜索 Hello，query 就需要换成 hello*, 这样如果索引里面有 HelloWorld 也能被命中
对于中文和其他字符，都要拆成单个的才能命中索引
最后对于拼音（其实我们没办法区分英文和拼音，统一当作拼音处理就行），需要把拼音按照规则拆分，因为我们的拼音索引是单字建立的。这样如果用户搜索 “zhangliangy”，拼音就可以被拆成 ‘zhang AND liang AND y*’，从而命中"张靓颖"。具体规则微信的文章中也有详述。

可以看到 query 词重构的逻辑也比较多，在之前的项目中没有好的办法，所以是自己在应用层代码里面组装好了 query 再给 sqlite 去搜的，这样其实不太方便。在这个项目中，我实现了一个 simple_query 的字符串函数，输入一个 string，它会给转换成组装好的搜索词，用法跟使用 sqlite 内置函数一样，这样就方便很多了，下面是一个例子：

-- 完整例子：https://github.com/wangfenjin/simple/blob/master/test.sql

-- load so file
.load libsimple.so

-- set tokenize to simple
CREATE VIRTUAL TABLE t1 USING fts5(x, tokenize = "simple");

-- add some values into the table
insert into t1 values ("周杰伦 Jay Chou:最美的不是下雨天，是曾与你躲过雨的屋檐"),

-- query result: [周杰伦] Jay Chou:最美的不是下雨天，是曾与你躲过雨的屋檐
select simple_highlight(t1, 0, '[', ']') from t1 where x match simple_query('zhoujiel');

可以看到， match 后面用 simple_query 这个函数，传入用户输入的搜索词就可以用了。

另外 sql 中还有一个 simple_highlight 函数，它的作用和内置的 highlight 函数一样，只是它会把连续命中的词一起高亮。比如对于文档"周杰伦"，如果搜索词是 ‘zhou AND jie’，那么 highlight 函数会返回 “[周][杰]伦”，simple_highlight 会返回 “[周杰]伦”。

总结

最后说几句关于 sqlite fts5 的使用的问题。个人建议通过 trigger 的方式来维护索引的这张表，具体使用的方式可以在官方文章中搜索 trigger 找到例子。这样使用的好处是没有复杂的逻辑去保证文档数据和索引数据一致，微信的文章中很大一部分复杂度在描述怎么保证数据一致的问题。他们可能有自己的业务复杂性，但是对于一般的场景来说， trigger 是最好的方式。

从这个项目我们能学到：

怎么给 sqlite3 做一个支持中文和拼音的 fts5 拓展
怎么给 sqlite3 添加用户自定义的函数
在一个项目中同时使用 c 和 c++ ，并合理处理边界问题

大家可以下载使用，也可以根据自己的需求去改进，定制更多的函数和策略。

Reference

Simple 分词器: https://github.com/wangfenjin/simple
sqlite 官方文档：https://www.sqlite.org/fts5.html
微信全文搜索优化之路：https://juejin.im/entry/59e6cd266fb9a0451968ab02
微信移动端的全文检索多音字问题解决方案：https://cloud.tencent.com/developer/article/1198371

About

Sun, 01 Mar 2020 00:00:00 +0000

Hi there

github: https://github.com/wangfenjin

Showcase

Wed, 18 Jul 2018 00:00:00 +0000

Header 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec interdum metus. Aenean rutrum ligula sodales ex auctor, sed tempus dui mollis. Curabitur ipsum dui, aliquet nec commodo at, tristique eget ante. Donec quis dolor nec nunc mollis interdum vel in purus. Sed vitae leo scelerisque, sollicitudin elit sed, congue ante. In augue nisl, vestibulum commodo est a, tristique porttitor est. Proin laoreet iaculis ornare. Nullam ut neque quam.

Fusce pharetra suscipit orci nec tempor. Quisque vitae sem sit amet sem mollis consequat. Sed at imperdiet lorem. Vestibulum pharetra faucibus odio, ac feugiat tellus sollicitudin at. Pellentesque varius tristique mi imperdiet dapibus. Duis orci odio, sodales lacinia venenatis sit amet, feugiat et diam.

Header 3

Nulla libero turpis, lacinia vitae cursus ut, auctor dictum nisl. Fusce varius felis nec sem ullamcorper, at convallis nisi vestibulum. Duis risus odio, porta sit amet placerat mollis, tincidunt non mauris. Suspendisse fringilla, odio a dignissim pharetra, est urna sollicitudin urna, eu scelerisque magna ex vitae tellus.

/* PostCSS code */

pre {
 background: #1a1a1d;
 padding: 20px;
 border-radius: 8px;
 font-size: 1rem;
 overflow: auto;

 @media (--phone) {
 white-space: pre-wrap;
 word-wrap: break-word;
 }

 code {
 background: none !important;
 color: #ccc;
 padding: 0;
 font-size: inherit;
 }
}

// JS code

const menuTrigger = document.querySelector('.menu-trigger')
const menu = document.querySelector('.menu')
const mobileQuery = getComputedStyle(document.body).getPropertyValue('--phoneWidth')
const isMobile = () => window.matchMedia(mobileQuery).matches
const isMobileMenu = () => {
 menuTrigger.classList.toggle('hidden', !isMobile())
 menu.classList.toggle('hidden', isMobile())
}

isMobileMenu()

menuTrigger.addEventListener('click', () => menu.classList.toggle('hidden'))

window.addEventListener('resize', isMobileMenu)

<!-- HTML code -->

<section id="main">
 <div>
 <h1 id="title">{{ .Title }}</h1>
 {{ range .Pages }}
 {{ .Render "summary"}}
 {{ end }}
 </div>
</section>

Header 4

Curabitur scelerisque felis viverra varius scelerisque. Ut enim libero, molestie gravida blandit at, mollis ornare tellus. Cras arcu mi, ultrices vel pulvinar vel, volutpat eu tortor. Nullam nec eros quis massa ultrices iaculis sed in metus. Praesent sollicitudin sem sit amet orci tempor gravida.

Maecenas elementum vitae nibh vitae porttitor.
Aenean consequat, risus ut cursus placerat, arcu nulla sodales risus, ut molestie tellus tellus et dui.
Integer imperdiet turpis vitae lacus imperdiet, ut ornare ligula auctor. Integer in mi eu velit vehicula suscipit eget vulputate nulla.
Etiam vitae enim quis velit lobortis placerat a ut sem.
- Curabitur lobortis ante sit amet orci pulvinar, sollicitudin viverra nunc accumsan.
- Praesent fermentum orci quis leo facilisis posuere.

Aliquam erat volutpat. In hac habitasse platea dictumst. Nunc ut tincidunt mauris. Sed at gravida risus, id semper magna. Nullam vitae enim mattis, sodales neque non, pharetra elit. Cras sit amet sagittis augue, et finibus turpis. Ut tempus tincidunt diam vel pharetra. Nulla porttitor odio sit amet nulla scelerisque, quis aliquam mi imperdiet. Sed tincidunt dui vel tellus vestibulum rhoncus. Donec tempus ultrices velit.