Great Expectations 数据验证第一课：从接入一份 CSV 到产出完整校验报告

Great Expectations 数据验证第一课：从接入一份 CSV 到产出完整校验报告

【免费下载链接】great_expectationsAlways know what to expect from your data.项目地址: https://gitcode.com/GitHub_Trending/gr/great_expectations

数据进了仓库、报表跑出来了，一核对才发现一批负数运正费进了 BI 看板——数据质量事故几乎总比发现得早。Great Expectations 是一个开源数据验证框架：把业务规则写成一条条"期望"（Expectation），由它逐条核对数据，产出通过率、失败行采样和可直接打开的报告。本文用仓库里自带的一份 CSV，带你把"安装 → 接入数据 → 定义期望 → 跑验证 → 看报告"这条完整链路走一遍。

跑通之后你能拿到什么

先说结果，再谈概念。跑完本文流程，你手里会有三样东西：

1. 一份结构化的验证结果：每条期望是否通过、失败了几条、占比多少，失败行还能直接采样出来；
2. 一个 Checkpoint 的运行记录，可以作为流水线里的"红绿灯"，失败即阻断下游；
3. 一个本地 Data Docs 静态站点，把规则与历次验证结果沉淀成网页，团队任何人随时可查。

管理这一切的是 Data Context：连接、规则、验证结果都挂在它下面，整个项目只需要维护这一个入口对象。官方概览脚本 docs/docusaurus/docs/core/introduction/try_gx.md 展示了这条链路，仓库里也配有可直接运行的端到端示例 docs/docusaurus/docs/core/introduction/try_gx_end_to_end.py。

安装 Great Expectations 并确认环境可用

为什么：GX 是纯 Python 库，装错位置或装完不验证，问题会推迟到连数据库时才暴露，排查成本高。

怎么做：推荐在虚拟环境里安装基础包，随后打印版本号确认。

python -m venv gx_env source gx_env/bin/activate pip install great-expectations

下面这行代码用来确认安装成功，能打印出版本号即可：

import great_expectations as gx print(gx.__version__)

做出什么：一个可用的 Python 环境。

⚠️ 两个常见的坑：一是别往系统 Python 全局装，后面升级依赖会互相牵连；二是如果你接下来要连数据库而不是文件，需要按目标库追加对应 extra，比如pip install "great-expectations[postgresql]"、great-expectations[mysql]"、great-expectations[bigquery]"，驱动会一并装好，省得手查依赖。

接入第一份数据：把 CSV 变成可校验的数据批次

为什么：验证的前提是 GX 知道"要验哪份数据"。Fluent API 把这件事拆成四层：数据源（Data Source）→ 数据资产（Data Asset）→ 批次定义（Batch Definition）→ 批次（Batch）。前三个是"合同"，可反复引用；Batch 才是某一次具体加载出来的数据。

怎么做：以仓库自带的泰坦尼克号样例数据 tests/test_sets/Titanic.csv 为例，下面这段代码创建上下文、加载 CSV，并把数据接入 GX：

import pandas as pd context = gx.get_context() df = pd.read_csv("tests/test_sets/Titanic.csv") data_source = context.data_sources.add_pandas("titanic") data_asset = data_source.add_dataframe_asset(name="titanic_df") batch_definition = data_asset.add_batch_definition_whole_dataframe("whole_df") batch = batch_definition.get_batch(batch_parameters={"dataframe": df})

做出什么：context在当前目录自动生成了.gx项目目录，数据源、资产、批次定义都注册其中；batch指向内存里的 891 行数据，可以直接发起验证。

📌 注意区分batch_definition和batch：定义描述"验哪份数据"，批次是"这一次"的数据。后续写 Checkpoint 时挂的是定义而不是批次，这也是数据更新后不用改代码的原因。另一个容易踩的坑是数据源命名——同一上下文里名字唯一即可，起得含糊（比如都叫default）后期排查会很痛苦。

定义第一条期望并跑通数据验证

为什么：期望是 GX 的基本单位——一句话描述"数据应该长什么样"，比如"乘客年龄应该在 0 到 100 之间"。写期望之前，先确认列名，别凭印象敲。

怎么做：先用df.columns看一眼真实列名，然后构造期望对象并直接验证。

print(df.columns.tolist()) expectation = gx.expectations.ExpectColumnValuesToBeBetween( column="Age", min_value=0, max_value=100 ) validation_result = batch.validate(expectation) print(validation_result["success"], validation_result["result"]["unexpected_count"])

做出什么：一段结构化的验证结果——success表示该条期望是否通过，result里给出检查总数、失败条数与占比，失败行还能采样出来。内置期望有上百种（非空、取值范围、枚举、列对关系等），完整清单见源码目录 great_expectations/expectations/core/，IDE 里输入gx.expectations.就能自动补全。

⚠️ 泰坦尼克数据里Age列有 177 个空值，所以这条验证会失败，unexpected_count大于 0——这是正常的，说明验证器真的在干活。业务上若允许少量越界值，可以加mostly=0.95表示"95% 满足即可"；也可以给期望加severity="warning"，让它失败时不直接阻断流水线。

沉淀为可复跑的验证流：套件、验证定义与 Checkpoint

为什么：单条验证适合探索，要交给流水线，需要把"哪些规则"和"验哪份数据"绑定成定义，再交给 Checkpoint 统一触发。

怎么做：下面这段代码把两条期望打包成套件，与批次定义绑定成验证定义，最后创建 Checkpoint 并运行：

suite = context.suites.add( gx.core.expectation_suite.ExpectationSuite(name="titanic_check") ) suite.add_expectation( gx.expectations.ExpectColumnValuesToBeBetween( column="Age", min_value=0, max_value=100, mostly=0.95 ) ) suite.add_expectation( gx.expectations.ExpectColumnValuesToNotBeNull(column="Pclass") ) validation_definition = context.validation_definitions.add( gx.core.validation_definition.ValidationDefinition( name="titanic_check", data=batch_definition, suite=suite ) ) checkpoint = context.checkpoints.add( gx.checkpoint.checkpoint.Checkpoint( name="titanic_cp", validation_definitions=[validation_definition] ) ) checkpoint_result = checkpoint.run() print(checkpoint_result.describe())

做出什么：checkpoint_result.describe()会打印整体通过率与每条期望的状态。Checkpoint 的实现见 great_expectations/checkpoint/。🔍 排查时重点看severity：critical级别的失败会让 Checkpoint 整体失败，warning级别只记录不阻断——把它当成"必须拦截"和"仅提示"两档开关来用。

读懂第一份验证报告：生成 Data Docs 站点

为什么：验证结果散在终端里没人看，沉淀成网页才有长期价值。Data Docs 就是 GX 的官方报告形态：期望列表、每次运行的通过率、失败行的具体取值，一页看全。

怎么做：构建本地站点只需一行：

context.build_data_docs()

生成的静态站点默认落在.gx目录下，用浏览器打开入口 HTML 即可。效果大致如下：

做出什么：一个可分享给团队的本地报告站。对失败行较多的期望，报告里还会给出具体采样的异常值，方便定位是哪批数据出了问题：

⚠️ 注意 Data Docs 只是"展示层"，它不产生验证——验证发生在 Checkpoint 运行那一刻。生产上通常把站点输出到对象存储或内部服务器，让报告跟随数据发布节奏自动更新。

接下来往哪走

三个由浅入深的方向，建议按顺序推进：

1. 把探索变成日常：用交互式 Notebook 边看数据边写期望，官方入口在 docs/docusaurus/docs/core/introduction/，里面同时提供了探索式与端到端两种脚本；
2. 接入真实数据源：把 CSV 换成 Postgres、MySQL 或 Snowflake 表，模式不变，只是add_pandas换成add_postgres等对应方法，安装命令见前文的 extras 表；
3. 让规则自动起草：用内置的规则式 Profiler 对列做统计分析并自动草拟期望，再人工审核，适合接手一份完全陌生的表。

完整文档都放在仓库的 docs/ 目录下，reference/learn一层的概念指南配合guides的操作手册，基本覆盖了从入门到生产的全部环节。数据的事，让数据自己先说一次。

【免费下载链接】great_expectationsAlways know what to expect from your data.项目地址: https://gitcode.com/GitHub_Trending/gr/great_expectations