多个 CSV 合并成一个：零依赖单文件工具 csvmerge

用微信扫一扫分享本页

打开微信「扫一扫」即可

关 闭

一、引言：数据整合的困境与解决方案

在当今数据驱动的商业环境中，来自不同系统、平台和流程的 CSV 文件已成为日常工作中不可或缺的数据载体。无论是电商平台导出的销售记录、财务系统生成的月度账单，还是不同部门提交的站点统计报表，这些 CSV 文件往往以分散、零散的方式存在。当需要对这些数据进行整合分析时，一个常见的痛点便是如何高效地将多个结构相似但表头略有差异的 CSV 文件合并成一个统一的数据集。手动处理这些文件不仅耗时费力，而且容易出错，如表头对齐错误、数据遗漏或重复等。

传统的解决方案通常依赖于功能强大的商业软件，如 Excel 或专业的数据处理工具。然而，这些工具往往需要安装复杂的依赖库，操作步骤繁琐，且可能产生额外的成本。对于需要快速、轻量级解决方案的场景，这些方法显得不够灵活和高效。此外，许多数据处理工具在处理大量数据时性能表现不佳，甚至可能崩溃。

为了解决上述问题，本文将介绍一个名为 csvmerge 的零依赖单文件工具。该工具利用 Python 3.8+ 标准库，提供了一种简单、高效、无需安装任何额外依赖库的方式，将多个 CSV/TSV 文件按表头自动对齐合并成一个单一的文件。csvmerge 不仅支持基本的行追加和列并集合并，还提供了去重、来源列标记和干跑预览等功能，使其成为处理 CSV 文件整合任务的理想选择。

二、工具概述：csvmerge 的核心功能与优势

csvmerge 是一个轻量级、零依赖的命令行工具，专门设计用于将目录下多个 CSV 或 TSV 文件按表头自动对齐合并成一个单一的文件。该工具的核心优势在于其简洁的设计和强大的功能，使其能够在无需安装任何第三方库的情况下，高效地完成数据整合任务。

2.1 核心功能

csvmerge 提供了以下核心功能：

1. 多表合并：能够将指定目录下所有 CSV/TSV 文件按表头并集对齐，合并为单个文件。
2. 两种合并模式：
   • 追加模式（append）：将所有文件的行追加到一起，表头不一致时自动求并集。
   • 并集模式（union）：按关键列求并集，保留所有文件中的唯一列。
3. 来源列标记：通过 --source-col 参数，可以为每行数据添加一个来源列，标记数据来自哪个文件，便于后续追溯和分析。
4. 去重功能：支持按整行去重，确保合并后的文件中没有重复数据。
5. 干跑预览：默认情况下，csvmerge 会进行干跑预览，显示合并后的表头和部分数据，但不会实际写入文件。只有在添加 --apply 参数时，才会真正生成合并后的文件。
6. 自定义列选择：通过 --cols 参数，可以选择只保留指定的列，忽略其他列。

2.2 优势与特点

csvmerge 的优势主要体现在以下几个方面：

• 零依赖：仅使用 Python 3.8+ 标准库，无需安装任何第三方库，安装和使用极为简单。
• 高效性：利用标准库中的高效数据处理功能，即使在处理大量数据时也能保持良好的性能。
• 灵活性：支持多种合并模式、去重和列选择功能，满足不同的数据整合需求。
• 易用性：命令行界面简洁直观，参数设置简单，易于上手。
• 安全性：默认不覆盖源文件，干跑预览机制确保操作的安全性，避免误操作导致数据丢失。
• 开源与授权：源码开放，使用 CC0 授权，用户可以自由使用、修改和分发。

2.3 与传统解决方案的对比

为了更直观地展示 csvmerge 的优势，以下表格对比了 csvmerge 与传统数据处理工具在处理多个 CSV 文件合并任务时的差异：

从上表可以看出，csvmerge 在易用性、灵活性、安全性和成本方面具有显著优势，特别适合需要快速、轻量级数据整合的场景。

三、功能详解：深入理解 csvmerge 的各项特性

csvmerge 提供了多种功能，满足不同的数据整合需求。以下将详细介绍这些功能的具体用法和适用场景。

3.1 多表合并与表头对齐

csvmerge 的核心功能是将多个 CSV/TSV 文件按表头对齐合并成一个单一的文件。这一功能特别适用于需要整合来自不同平台、但结构相似的 CSV 文件的情况。

3.1.1 合并原理

csvmerge 在合并文件时，会首先读取所有文件的表头，然后根据表头信息进行对齐。如果不同文件的表头存在差异，csvmerge 会自动求并集，确保合并后的文件包含所有文件中的所有列。

例如，假设有以下三个 CSV 文件：

• file1.csv：order_id,amount,ts
• file2.csv：order_id,amount,ts,coupon
• file3.csv：order_id,amount,ts,region

在合并时，csvmerge 会自动生成一个包含所有列的表头：order_id,amount,ts,coupon,region。

3.1.2 使用示例

假设有三个 CSV 文件 orders1.csv、orders2.csv 和 orders3.csv 存放在 /data/orders 目录下，表头分别为 order_id,amount,ts、order_id,amount,ts,coupon 和 order_id,amount,ts,region。以下是如何使用 csvmerge 将它们合并成一个文件 merged_orders.csv 的示例：

bash python3 csvmerge.py /data/orders –apply –out merged_orders.csv

执行上述命令后，csvmerge 会读取所有文件，生成一个包含所有列的表头，并将所有数据按行追加到 merged_orders.csv 中。

3.2 两种合并模式：追加与并集

csvmerge 提供了两种合并模式：追加模式和并集模式。这两种模式适用于不同的数据整合需求。

3.2.1 追加模式（append）

追加模式将所有文件的行追加到一起，表头不一致时自动求并集。这种模式适用于需要将多个数据集按时间顺序或逻辑顺序合并在一起的情况。

追加模式的工作原理：

1. 读取所有文件的表头，求并集生成新的表头。
2. 将所有文件的行按顺序追加到一起，生成合并后的数据。
3. 如果某些文件缺少某些列，会在相应位置填充空值（如 None 或空字符串）。

使用示例：

假设有三个 CSV 文件 sales1.csv、sales2.csv 和 sales3.csv，表头分别为 date,sales,product、date,sales,product,cost 和 date,sales,product。以下是如何使用 csvmerge 以追加模式合并这些文件的示例：

bash python3 csvmerge.py /data/sales –apply –out merged_sales.csv

执行上述命令后，csvmerge 会生成一个包含所有列的表头（date,sales,product,cost），并将所有数据按行追加到 merged_sales.csv 中。如果某些文件缺少 cost 列，cost 列的相应位置会被填充为 None。

3.2.2 并集模式（union）

并集模式按关键列求并集，保留所有文件中的唯一列。这种模式适用于需要合并多个数据集，但每个数据集的列不完全相同的情况。

并集模式的工作原理：

1. 读取所有文件的表头，求并集生成新的表头。
2. 将所有文件的数据按行合并，保留所有唯一行。
3. 如果某些行在多个文件中存在，会保留其中一个，其余重复行会被丢弃。

使用示例：

假设有三个 CSV 文件 products1.csv、products2.csv 和 products3.csv，表头分别为 product_id,name,price、product_id,name,price,category 和 product_id,name,price,weight。以下是如何使用 csvmerge 以并集模式合并这些文件的示例：

bash python3 csvmerge.py /data/products –apply –out merged_products.csv

执行上述命令后，csvmerge 会生成一个包含所有列的表头（product_id,name,price,category,weight），并将所有数据按行合并，保留所有唯一行。如果某些行在多个文件中存在，会保留其中一个，其余重复行会被丢弃。

3.3 来源列标记：追踪数据来源

在某些数据整合场景中，了解每行数据来自哪个文件非常重要。csvmerge 提供了 --source-col 参数，可以为每行数据添加一个来源列，标记数据来自哪个文件。

3.3.1 功能原理

通过 --source-col 参数，csvmerge 会在合并后的数据中添加一个新列，该列的名称由用户指定（默认为 source）。每行数据的来源列会显示该行数据来自哪个文件。

工作原理：

1. 读取所有文件的表头。
2. 在表头中添加指定的来源列。
3. 在每行数据中添加一个来源列，其值对应该行数据来源的文件名。

3.3.2 使用示例

假设有三个 CSV 文件 sales1.csv、sales2.csv 和 sales3.csv，表头分别为 date,sales,product、date,sales,product,cost 和 date,sales,product。以下是如何使用 csvmerge 添加来源列并合并这些文件的示例：

bash python3 csvmerge.py /data/sales –apply –out merged_sales.csv –source-col source

执行上述命令后，csvmerge 会生成一个包含所有列和一个 source 列的表头，并在每行数据中添加一个 source 列，其值对应该行数据来源的文件名。例如：

3.4 去重功能：确保数据唯一性

在数据整合过程中，经常会出现重复数据。csvmerge 提供了去重功能，可以确保合并后的文件中没有重复数据。

3.4.1 去重原理

去重功能会根据用户指定的去重规则，删除合并后的数据中的重复行。去重规则可以是整行去重或按指定列去重。

整行去重：删除所有完全相同的行。

按指定列去重：删除在指定列中值相同的行。

3.4.2 使用示例

假设有三个 CSV 文件 users1.csv、users2.csv 和 users3.csv，表头分别为 user_id,name,age、user_id,name,age,city 和 user_id,name,age。以下是如何使用 csvmerge 进行整行去重并合并这些文件的示例：

bash python3 csvmerge.py /data/users –apply –dedup –out merged_users.csv

执行上述命令后，csvmerge 会删除所有完全相同的行，并将结果保存到 merged_users.csv 中。

如果需要按指定列去重，可以使用 --cols 参数指定去重列：

bash python3 csvmerge.py /data/users –apply –dedup –cols user_id –out merged_users.csv

执行上述命令后，csvmerge 会删除 user_id 列中值相同的行，并将结果保存到 merged_users.csv 中。

3.5 干跑预览：安全高效的合并过程

csvmerge 默认进行干跑预览，显示合并后的表头和部分数据，但不会实际写入文件。只有在添加 --apply 参数时，才会真正生成合并后的文件。这一功能特别适用于需要验证合并结果是否符合预期的情况。

3.5.1 干跑预览的工作原理

干跑预览的工作原理如下：

1. 读取所有文件的表头，求并集生成新的表头。
2. 根据合并模式（追加或并集）生成合并后的数据。
3. 如果启用了去重功能，会先进行去重处理。
4. 如果启用了来源列标记，会添加来源列。
5. 显示合并后的表头和部分数据（默认显示前 10 行）。

3.5.2 使用示例

假设有三个 CSV 文件 products1.csv、products2.csv 和 products3.csv，表头分别为 product_id,name,price、product_id,name,price,category 和 product_id,name,price,weight。以下是如何使用 csvmerge 进行干跑预览的示例：

bash python3 csvmerge.py /data/products

执行上述命令后，csvmerge 会生成一个包含所有列的表头，并显示合并后的部分数据（默认显示前 10 行）。例如：

表头: product_id,name,price,category,weight 数据: product_id,name,price,category,weight 1,product_A,100.0,,None 2,product_B,150.0,electronics,1.5 3,product_C,200.0,home_goods,2.0 …

如果需要自定义显示的数据行数，可以使用 --preview-rows 参数：

bash python3 csvmerge.py /data/products –preview-rows 20

执行上述命令后，csvmerge 会显示前 20 行合并后的数据。

3.6 自定义列选择：灵活控制合并结果

csvmerge 提供了 --cols 参数，允许用户选择只保留指定的列，忽略其他列。这一功能特别适用于需要合并多个数据集，但只关注部分列的情况。

3.6.1 自定义列选择的工作原理

自定义列选择的工作原理如下：

1. 读取所有文件的表头。
2. 根据用户指定的列列表，筛选出需要保留的列。
3. 将所有文件的数据按筛选出的列进行合并。

3.6.2 使用示例

假设有三个 CSV 文件 sales1.csv、sales2.csv 和 sales3.csv，表头分别为 date,sales,product、date,sales,product,cost 和 date,sales,product。以下是如何使用 csvmerge 自定义列选择并合并这些文件的示例：

bash python3 csvmerge.py /data/sales –apply –out merged_sales.csv –cols date,sales

执行上述命令后，csvmerge 会只保留 date 和 sales 列，并将所有数据按这两列合并，生成 merged_sales.csv 文件。

四、使用方法：详细步骤与实例

csvmerge 是一个简单易用的命令行工具，以下将详细介绍其使用方法，并通过实例展示如何在实际场景中应用。

4.1 基本使用方法

csvmerge 的基本使用方法如下：

bash python3 csvmerge.py <目录> [选项]

其中：

• <目录>：存放 CSV/TSV 文件的目录。
• [选项]：可选参数，包括：
  • --apply：真正写出合并后的文件（默认不写）。
  • --out <文件名>：输出文件名（默认 merged.csv）。
  • --source-col <列名>：添加来源列，标记每行数据来自哪个文件。
  • --dedup：按整行去重。
  • --cols <列列表>：只保留指定的列（逗号分隔）。

4.1.1 干跑预览示例

假设有三个 CSV 文件 orders1.csv、orders2.csv 和 orders3.csv 存放在 /data/orders 目录下。以下是如何使用 csvmerge 进行干跑预览的示例：

bash python3 csvmerge.py /data/orders

执行上述命令后，csvmerge 会读取所有文件，生成一个包含所有列的表头，并显示合并后的部分数据（默认显示前 10 行）。例如：

表头: order_id,amount,ts,coupon,region 数据: order_id,amount,ts,coupon,region 1001,100.0,2023-01-01 10:00:00,,site_A 1002,150.0,2023-01-01 11:00:00,coupon_A,site_B 1003,200.0,2023-01-01 12:00:00,,site_C …

4.2

豆学长 · 站长

豆学长博客：专注AI工具实战、学习方法与效率提升的原创内容博客，每日更新干货教程与深度评测

📡 RSS 订阅 了解作者 全部文章