vaex 版本演进全解析：从 2.3 到 4.15 的核心功能、性能优化与架构变迁指南-平芜编程栈

数据分析
数据可视化
大数据
数据科学

【免费下载链接】vaex

Out-of-Core hybrid Apache Arrow/NumPy DataFrame for Python, ML, visualization and exploration of big tabular data at a billion rows per second 🚀

项目地址：https://gitcode.com/gh_mirrors/va/vaex

点击查看免费下载

本文以仓库根目录的 CHANGELOG.md 为权威主线，系统梳理 vaex 从 2.3.0 到 4.15.0 的完整演进脉络：Apache Arrow 深度集成、Out-of-Core 懒加载与任务缓存体系、groupby/join 等高频操作的性能突破，以及 3.0、4.0 两轮破坏性变更的迁移要点。读完本文，你将理解每个版本背后的设计动机，并能依据版本差异评估升级风险、针对性使用 materialize、settings、struct.flatten 等新能力。

一、仓库与版本体系概述

vaex 是一个 Out-of-Core 的混合 Apache Arrow/NumPy DataFrame 库，面向 Python 大规模表格数据的机器学习、可视化和探索，官方定位为"每秒处理十亿行"。当前仓库采用多包架构，核心模块包括：

包名	目录	定位
vaex-core	packages/vaex-core/vaex/	核心引擎：DataFrame、表达式、聚合、join、groupby、任务与缓存系统
vaex-hdf5	packages/vaex-hdf5/vaex/hdf5/	HDF5 读写与导出
vaex-viz	packages/vaex-viz/vaex/viz/	matplotlib/contour 等可视化
vaex-ml	packages/vaex-ml/vaex/ml/	与 scikit-learn、XGBoost、TensorFlow 等集成的机器学习工具
vaex-astro	packages/vaex-astro/vaex/astro/	天体数据（FITS、VOTable、Gadget）支持
vaex-server	packages/vaex-server/vaex/server/	远程/分布式 DataFrame 服务
vaex-jupyter	packages/vaex-jupyter/vaex/jupyter/	Jupyter 交互式可视化组件

CHANGELOG 记录了 vaex 2.3.0（2019-10）至 4.15.0 的全部变更，其中 4.x 系列是 Arrow 深度集成后的主线版本。注意：3.x 与 2.x 之间存在一处版本号错位——vaex 3.1.0 条目下的 vaex-core 被标注为 2.0.3（2020-6-10），这是当时各子包独立发版节奏的产物，阅读历史条目时需留意。

二、vaex 4.x 时代：Apache Arrow 的全面深化

2.1 vaex 4.0.0（2021-03-09）：Arrow 成为核心依赖

4.0.0 是自 3.0 之后的又一次大规模架构升级，CHANGELOG 明确列出的 Breaking changes 包括：

Arrow 成为核心依赖，vaex-arrow 包被废弃（deprecated），所有返回字符串的方法现在返回 Arrow 数组（#517）。
打开.arrow文件时，数组以 Apache Arrow 数组而非 NumPy 数组形式暴露（#984）。
列访问df.column['x']可能返回ColumnProxy而非原始数据，需要切片[:]或用.to_numpy()/.to_arrow()/np.array(...)/pa.array(...)转换（#993）。
所有绘图方法迁移到df.vizaccessor（#923）。

同版本的架构 Refactor 有两个关键点：DataFrame 与 Dataset 分离（#865）——DataFrame 是面向用户的逻辑视图，Dataset 负责底层数据存储与 chunk 迭代；字符串函数改用arrow.compute内核（#885），这是性能提升的底层来源。此外还引入Out-of-Core Parquet 支持（Arrow Dataset 扫描，#993）、Google Cloud Storage 流式读取（#898）、dropinf（#821）、datetime floor（#843）。concat性能提升约 100 倍（#994），同时 vaex-distributed 因"从未真正可用"被废弃并并入 vaex-enterprise。

2.2 vaex 4.5～4.9：哈希、缓存与聚合器大发展

vaex-core 4.5.0（关键性能条目）：

Expression.nunique()结果被缓存（#1565）。
Hashmap 内存在线程间共享，不再随线程数线性增长，且免去合并阶段；hashmap 可高效序列化（#1525），这在 packages/vaex-core/src/ 下的hash_primitives*.cpp、hash_string.cpp、hash_object.cpp中有对应的 C++ 实现。
通过避免 fallback 到 eval 来获取 dtype，提升类型检查速度（#1514）。
文件创建用 lock 文件保护，支持多进程convert=True协作（#1541、#1573）；blob 编码因 blake3 而加速（#1575）。
新增Expression.str.extract，可用正则提取字符串片段为 struct（#1423）。

vaex-core 4.9.0（聚合器与排序）：

新增聚合器：first/last使用不同类型的排序列（#1848）、skew/kurtosis（#1946）、list聚合器（#1987），这些均在 packages/vaex-core/vaex/agg.py 中定义，底层 C++ 实现位于 packages/vaex-core/src/agg_list.cpp、agg_first.cpp、agg_minmax.cpp 等文件。
支持按字符串排序、多列排序、多方向排序（#1963）。
df.export支持 JSON（#1974）。
df.groupby先对分组列预排序以获得更好性能（#1990）；hashmap 不再拷贝、释放 GIL（#1893、#1961），字符串以 Arrow 数组存入 hashmap，使map.key_array()更快（#1976）。

2.3 vaex 4.10～4.15：describe、struct 与 Arrow 生态收官

vaex-core 4.10.0：新增vaex.agg.describe聚合器及groupby(...).describe(...)（#2004）；df.struct.flatten将 Arrow struct 拆成多列（#2072）；isin 复用 hashmap，指纹稳定利于缓存（#2089）；value_counts改为 task 以获得缓存支持（#2085）。
vaex-core 4.11.x：修复空 DataFrame 切片（#2129）；join 在缺失值时的问题（#808）；修正$VAEX_PATH_HOME→$VAEX_PATH环境变量（#2101）；新增dropna/dropinf等用法文档（#2104）。
vaex-core 4.13.0：落地Apache Arrow CSV reader 的 Out-of-Core（懒加载）与常规 CSV 支持（#1028），同时支持 pandas 与 arrow 的压缩 CSV 读取；暴露vaex.DataFrame与vaex.Expression类型用于 typing（#2186）。
vaex-core 4.14.0：export_many支持 Arrow CSV 导出后端（#2220）；懒加载 CSV 读取自动检测类型（#2224）。
vaex-core 4.15.0：materialize允许传入单列或表达式（#2249）；selection 中的 Arrow 数据不再忽略 null（#2196）；支持用 Arrow string 标量构建表达式/过滤器（#2244）；vaex.settings统一管理线程数（#2231）。

三、核心机制源码解读：任务、缓存、指纹与并行

4.x 的多数性能条目都围绕"任务系统 + 缓存 + 指纹"展开，它们是 vaex 每秒十亿行的基石。

3.1 任务系统与执行器

vaex-core 2.0.0 起任务系统重构，任务在 CPU 上执行、更易（反）序列化，数据结构的编码更灵活，支持二进制 blob 与 JSON 在线传输（#557），并支持 async/await（#654）。4.8.0 又调整默认同步执行路径不再使用 asyncio，并让执行器支持多任务异步、提供 auto execute 上下文管理器（#1783、#1784、#1785）。相关实现见 packages/vaex-core/vaex/execution.py、tasks.py。

3.2 指纹（fingerprint）与多级缓存

4.3.0 引入df.fingerprint()——一个跨运行时的唯一缓存键，并支持 Redis 与 diskcache 缓存任务结果（#1393、#1287）。
4.6.0 起指纹在"DataFrame 变化但任务描述不变"时保持稳定以提升缓存命中（#1627），并引入多级缓存（如内存 + 磁盘，#1580）。
4.9.0 修复了"过滤器使用虚拟列导致指纹冲突"的隐患（#1949）；4.10.0 让 isin 复用 hashmap 从而指纹稳定（#2089）。

指纹与缓存的实现集中在 packages/vaex-core/vaex/cache.py、dataset.py；C++ 侧 hashmap 见 packages/vaex-core/src/hash.hpp 与各hash_*.cpp。

3.3 线程、进程与 GIL

4.8.0 将互斥锁移入 C++ 层避免 GIL 问题（#1847），并重构提升整体性能（#1863、#1869）。
4.9.0 减少 multiprocessing 进程数（#1979）。
4.15.0 让线程数统一走vaex.settings（#2231）。在 packages/vaex-core/vaex/settings.py 中可看到默认值逻辑：thread_count默认multiprocessing.cpu_count()，thread_count_io默认thread_count + 1，process_count默认等于thread_count；这些字段可通过环境变量VAEX_NUM_THREADS、VAEX_NUM_THREADS_IO覆盖，整个 settings 结构支持从$VAEX_HOME/main.yml加载。

四、groupby、join 与聚合的性能演进路线

4.1 groupby：从 2x 到 250x

版本	变更	效果
vaex-core 2.0.0	groupby 重构	2x～4x 提速（#730）
vaex-core 2.0.3	isin 用 hashmap	基本类型 2x～4x、字符串场景最高 200x（#822）
vaex-core 4.2.0	稀疏化 groupby	更低内存占用，最高 250x 提速（#1381）；新增排序 groupby（#1339）
vaex-core 4.6.0	支持常规 bins 分组、受限 value 数与 'OTHERS'	对齐 binby（#1589、#1641）；新增`vaex.agg.any`/`all`（#1630）
vaex-core 4.9.0	预排序分组列	更优性能（#1990）

sparse groupby 的 C++ 侧实现可在 packages/vaex-core/src/binner_hash.cpp、binner_combined.cpp 中查看；groupby.describe的快捷入口位于 packages/vaex-core/vaex/groupby.py，其实现等价于df.groupby('pclass').agg({'age': vaex.agg.describe('age')}).struct.flatten()，输出age_count、age_count_na、age_mean、age_std、age_min、age_max等列。

4.2 join：缺失值处理是持久战役

join 相关的修复贯穿多个版本，CHANGELOG 记录：

2.0.0：右表仅有 join 列时 join 失败、名称冲突、虚拟列与变量处理修复（#570、#573、#2010）。
2.0.1：右表缺失左表值时"罕见情况下指向 row 0"的修复（#765）。
4.2.0：join 支持 datetime 列。
4.9.x、4.10.0、4.11.0：连续修复缺失值/nan 导致的 join 问题（#2077、#808）。

join 的 Python 层实现在 packages/vaex-core/vaex/join.py，C++ 哈希与字符串处理在 packages/vaex-core/src/ 的hash_string.cpp、string_utils.cpp等文件中。

4.3 聚合器生态

除了skew、kurtosis、describe、list、first/last、any/all，4.x 还新增了percentile_approx进度条（#1889）、unique/nunique的limit与limit_raise（#1801）、nunique对数字列带 selection 时错误结果的修复（#2199）。聚合器的完整清单见 packages/vaex-core/vaex/agg.py，对应 C++ 内核在 packages/vaex-core/src/agg_*.cpp。

五、CSV 读取与 Out-of-Core 懒加载实战

CHANGELOG 中 CSV 能力是 4.13～4.15 的重点，核心 API 为vaex.from_csv_arrow（定义于 packages/vaex-core/vaex/init.py）：

import vaex # 常规（非懒加载）读取 df = vaex.from_csv_arrow("data.csv") # Out-of-Core 懒加载：不将数据全部载入内存，按块读取 df = vaex.from_csv_arrow("huge.csv", lazy=True, chunk_size="10MiB", # 每块读取大小，默认 10MiB newline_readahead="64kiB", # 换行探测预读缓冲，默认 64kiB schema_infer_fraction=0.01) # 用于推断 schema 的文件比例，默认 1%

lazy=True时返回基于 packages/vaex-core/vaex/csv.py 中DatasetCsvLazy的 DataFrame，lazy=False时用DatasetCsv全量读取。
三个 options 直接透传 PyArrow 的ReadOptions/ParseOptions/ConvertOptions，可精细控制列类型推断、null 值处理、块大小。
4.14.0 的"自动检测类型"（#2224）让懒加载读取时无需手动指定 schema。

传统vaex.from_csv则保留 pandas 后端路径（packages/vaex-core/vaex/init.py），支持chunk_size分块迭代与大文件convert=True转 HDF5（默认 5M 行/块，约 1GB 内存，需双倍磁盘空间）。

六、materialize 与内存/性能取舍

materialize是 4.6.0 引入的"将数据集列物化为原生 CPU 格式"的能力（#1625），对非内存映射文件（如 parquet）尤其重要。源码见 packages/vaex-core/vaex/dataframe.py：

df = vaex.open('somewhatslow.parquet') df.x.sum() # 慢：每次都要解码 parquet 块 df = df.materialize() # 将真实列缓存到内存 df.x.sum() # 首次调用填缓存，仍慢 df.x.sum() # 之后走内存，速度最快

要点：

materialize(column=None, inplace=False)：column接受列名或表达式（4.15.0 起支持单个列/表达式，#2249），为 None 时物化全部列（含隐藏列）；inplace=True时原地修改。
虚拟列会被立即evaluate并转为真实列（通过DatasetArrays），真实列则包装进DatasetCached首次访问时缓存。
4.15.0 还修复了df.extract()的线程安全问题（#2182），并在无法执行时抛出更明确的异常（#2232）；4.15 前 materialize 只接受虚拟列名列表。
需要警惕：materialize可能占用大量内存（源码 docstring 中明确警告）。

七、selections、过滤与缺失值处理

7.1 selection 相关修复

2.4.0/2.5.0：表达式针对过滤数据与 selection 不重复求值（#483、#496、#505）；过滤与 selection 支持布尔自动广播实现"条件过滤"（#489）。
4.1.0：df.extract()改用 mask 而非 indices（commit 398b682f）。
4.9.0：按布尔列过滤时正确记录列依赖（#2016）。
4.13.0：修复过滤 DataFrame 的负索引（#2163）。
4.15.0：Arrow 数据用于 selection 时不再忽略 null 或失败（#2196）；selection-dropna支持非标识符表达式（#2208）。

selections 的实现位于 packages/vaex-core/vaex/selections.py，过滤在 dataframe.py 的filter相关方法中。

7.2 dropna / dropinf / fillna

4.0.0 新增dropinf（#821）。
4.8.0 修复fillna/fillmissing在需要时对整数列向上转型（#1869）。
4.11.0 补充 dropna/dropinf 等方法的文档说明（#2104）。

八、vaex 3.0：破坏性变更与迁移清单

vaex 3.0.0（2020-05-24）是一次面向 Python 3 的现代化，CHANGELOG 列出的 Breaking changes 对升级者影响重大：

放弃 Python 2；DataFrame 内部改用普通 dict（要求 Python ≥ 3.6）。
变量不再能访问pi和e常量。
df.rename_column改为df.rename（同时重命名变量）。
绘图等默认 limits 变为 minmax，避免遗漏离群点。
df.get_column_names()返回别名（非法标识符）名，传alias=False取内部列名。
df.export/to_dict/to_items/to_arrays的virtual默认值为 True。
df.dtype变为属性；表达式数据类型用df.data_type()，df.expr.dtype行为不变。
df.categorize接受min_value/max_value，不再需要check参数，labels 不必是字符串；新增inplace参数。
vaex.open/from_csv默认不再拷贝 pandas index（#756）。

vaex-core 2.0.0（2020-05-24，作为 vaex 3.0 的配套核心）还完成：打印 DataFrame 单次 evaluate（#571）、join 2x 提速与更低内存（#586）、按列 dtype=object 时更快的类型检查（#612）、DataFrame/Executor 线程安全（支持 Dash/Flask，#670）、percentile_approx支持百分比序列（#527）、polygon 测试（利于 geo/geojson，#685）、dt.quarter与dt.strftime（#682）。

九、子包版本节奏与配套生态演进

CHANGELOG 同时记录了各子包的独立发版，便于排查兼容性问题：

vaex-hdf5：0.12.0 支持在 HDF5 中存储 Arrow Dictionary 编码（categorical）（#1814）；0.13.0 需 vaex-core 4.13.0（dataset 重构）；0.14.0 用 null bitmask 在 HDF5 中存 Arrow 数组（#2245）；0.12.2 关闭 HDF5 文件时不持有 NumPy 数组引用（#2066）；0.10.0 支持写高维数组（#1563）。
vaex-viz：0.5.4 修正 matplotlib 3.6.0 下 colorbar 位置（#2215）；0.5.3 改善 histogram 的 selection 行为（#2143）。
vaex-astro：0.9.2 修复 eq2gal 拼写（#2206）。
vaex-ml：0.18.0 支持 metrics 中使用 selections（#2073）；0.17.0 依赖vaex.datasets.iris()；0.16 起依赖统一 settings（需 vaex-core 4.7）；0.15 起 dot product 用专用函数；0.14.0 新增 MultiHotEncoder 与多种 ML metrics；0.13.0 支持 TensorFlow/keras（#1510）；0.12.0 集成 River、随机投影、增量 PCA。
vaex-server：0.6.0 用 FastAPI 完全重构（#1300）；0.8.1 兼容 Python 3.6。
vaex-jupyter：0.5.1 提供 selection toggle list；0.7.0 提供 settings 编辑组件。
vaex-contrib：0.1.0 支持 Google BigQuery 导入导出（#1470），代码在 packages/vaex-contrib/vaex/contrib/io/gbq.py。

十、依赖、环境与构建事项

Python 版本：4.0.0 起 Arrow 为核心依赖；vaex-core 4.8.0 为避免 segfault 有意避开 frozendict 2.2.0（Python 3.6，#1856）；vaex-server 0.8.1 兼容 Python 3.6。
OSX Metal：vaex-core 4.6.0 支持 Metal 加速表达式 jit（#584）；4.11.0 提供 osx arm wheel（#2124）。
blake3：4.5.0 用于加速 blob 编码（#1575），4.8.0 修复 blake3 兼容问题（#1818）。
构建系统：4.8.0 起使用 cmake/scikit-build（#1847），参考 packages/vaex-core/CMakeLists.txt。
环境变量：VAEX_NUM_THREADS、VAEX_NUM_THREADS_IO控制计算/IO 线程（packages/vaex-core/vaex/settings.py）；$VAEX_HOME/main.yml可集中配置（packages/vaex-core/vaex/settings.py）；4.8.0 起锁文件位于$VAEX_HOME/lock（#1797）；注意 4.11.0 将$VAEX_PATH_HOME更正为$VAEX_PATH（#2101）。

十一、如何继续深入

核心 DataFrame API 与实现：packages/vaex-core/vaex/dataframe.py
聚合器定义：packages/vaex-core/vaex/agg.py
分组、连接、滚动窗口：packages/vaex-core/vaex/groupby.py、join.py、rolling.py
C++ 加速内核：packages/vaex-core/src/（hash、agg、binner、strings）
测试印证：CHANGELOG 中多数修复均有对应回归测试，如 tests/groupby_test.py、tests/join_test.py、tests/unique_test.py、tests/from_csv_test.py 等，可用于验证本文所述行为在当前版本中的实际表现。