sumeshi/qsv-rs

# Quilter-CSV [](LICENSE) [](https://github.com/sumeshi/qsv-rs/actions/workflows/release.yml)  一款用 Rust 编写的快速、灵活、内存高效的命令行工具，用于处理大型 CSV 文件。灵感来自 [xsv](https://github.com/BurntSushi/xsv)，基于 [Polars](https://www.pola.rs/) 构建，专为在日志分析和数字取证等工作流中高效处理数十或数百 GB 的 CSV 数据而设计。 ## 功能特性 - **流水线式命令链**：在一行中链接多个命令，实现快速高效的数据处理 - **灵活的过滤和转换**：执行选择、过滤、排序、去重和时区转换等操作 - **基于 YAML 的批量处理 (Quilt)**：使用 YAML 配置文件自动化复杂工作流 ## 使用方法  ### 获取帮助 要查看可用的命令和选项，请不带任何参数运行 `qsv`： ``` $ qsv -h ``` ### 示例 以下是一个读取 CSV 文件、提取 'Event ID' 列包含 4624 的行，并按 'Date and Time' 列排序显示前 3 行的示例： ``` $ qsv load Security.csv - isin 'Event ID' 4624 - sort 'Date and Time' - head 3 - showtable ``` 此命令： 1. 加载 `Security.csv` 2. 过滤 `Event ID` 为 4624 的行 3. 按 `Date and Time` 排序 4. 以表格形式显示前 3 行 ### 命令结构 qsv 命令由三种类型的步骤组成： - **初始化器 (Initializer)**：加载数据（例如 `load`） - **可链函数 (Chainable)**：转换或过滤数据（例如 `select`、`grep`、`sort` 等） - **终止器 (Finalizer)**：输出或汇总数据（例如 `show`、`showtable`、`headers` 等） 每个步骤用连字符 (`-`) 分隔： ``` $ qsv - - ``` **注意：** 如果未明确指定终止器，默认构建会自动使用 `showtable`，便于快速查看结果： ``` $ qsv load data.csv - select col1,col2 - head 5 # 等效于： $ qsv load data.csv - select col1,col2 - head 5 - showtable ``` 未启用可选 `table` 功能的构建会回退到 `show`，而 `showtable` 命令会打印重建提示。 ## 命令参考 ### 初始化器 #### `load` 加载一个或多个 CSV 或 Parquet 文件。 **支持的格式：** - CSV 文件 (.csv, .tsv, .txt) - Gzip 压缩的 CSV 文件 (.csv.gz) - Parquet 文件 (.parquet) - 高性能，保留数据类型 | 参数 | 类型 | 默认值 | 说明 | |-----------------|--------------|----------|----------------------------------------------------------------------| | path | list[str] | | 一个或多个 CSV 或 Parquet 文件的路径。支持带引号的通配符模式，如 `"logs/*.tsv"`。不能在同一命令中混合使用 CSV 和 Parquet 文件。 | | -s, --separator | str | `,` | 字段分隔符字符（仅限 CSV 文件）。 | | --low-memory | flag | `false` | 为非常大的文件启用低内存模式（仅限 CSV 文件）。 | | --no-headers | flag | `false` | 将第一行视为数据而非表头（仅限 CSV 文件）。启用时，列将自动命名（`column_1`、`column_2` 等）。 | | --chunk-size | int | (自动) | 每次读取的行数（仅限 CSV 文件）。控制文件处理期间的内存使用。 | **环境变量：** - `QSV_CHUNK_SIZE`：CSV 处理的默认块大小（覆盖自动检测，可被 --chunk-size 覆盖） - `QSV_MEMORY_LIMIT_MB`：gzip 解压和流式操作的内存限制（默认值：1024MB，范围：512-4096MB） 示例： ``` $ qsv load data.csv $ qsv load data.csv.gz $ qsv load data1.csv data2.csv data3.csv $ qsv load "logs/*.tsv" -s $'\t' $ qsv load "logs/*.tsv" --separator=$'\t' $ qsv load data.csv --low-memory $ qsv load data.csv --no-headers $ qsv load data.csv --chunk-size 50000 $ qsv load cache.parquet # Load from parquet cache $ qsv load cache1.parquet cache2.parquet # Load multiple parquet files ``` ### 可链函数 #### `select` 按名称、数字索引或范围表示法选择列。 | 参数 | 类型 | 默认值 | 说明 | |------------|-------------------|----------|---------------------------------------------------------------------------------------------------| | colnames | str/list/range | | 列名或索引。支持多种格式（见下文示例）。这是必需参数。 | **列选择格式：** - **单独列**：`col1,col3` - 按名称选择特定列 - **数字索引**：`1,3` - 按位置选择列（1-based 索引） - **范围表示法（连字符）**：`col1-col3` - 使用连字符选择范围 - **范围表示法（冒号）**：`col1:col3` - 使用冒号选择范围 - **数字范围**：`2:4` - 选择第 2 到第 4 列（例如 col1、col2、col3） - **带引号的冒号表示法**：`"col:1":"col:3"` - 用于包含冒号的列名 - **混合格式**：`1,col2,4:6` - 结合不同的选择方法 ``` $ qsv load data.csv - select datetime # Select single column by name $ qsv load data.csv - select col1,col3 # Select specific columns by name $ qsv load data.csv - select col1-col3 # Select range using hyphen $ qsv load data.csv - select col1:col3 # Select range using colon $ qsv load data.csv - select 1 # Select 1st column (datetime) $ qsv load data.csv - select 2:4 # Select 2nd-4th columns (col1, col2, col3) $ qsv load data.csv - select 2,4 # Select 2nd and 4th columns (col1, col3) $ qsv load data.csv - select "col:1":"col:3" # For columns with colons in names $ qsv load data.csv - select 1,datetime,3:5 # Mixed selection methods ``` #### `isin` 过滤列值匹配任意给定值的行。 | 参数 | 类型 | 默认值 | 说明 | |----------|--------|----------|-----------------------------------------------------------------------------------| | colname | str | | 要过滤的列名。必需。 | | values | list | | 逗号分隔的值。过滤列匹配任意这些值的行（OR 条件）。必需。 | ``` $ qsv load data.csv - isin col1 1 $ qsv load data.csv - isin col1 1,4 ``` #### `contains` 过滤列包含特定字面字符串的行。 | 参数 | 类型 | 默认值 | 说明 | |--------------------|--------|----------|------------------------------------| | colname | str | | 要搜索的列名。必需。 | | substring | str | | 要搜索的字面字符串。必需。 | | -i, --ignorecase | flag | `false` | 执行不区分大小写的匹配。 | ``` $ qsv load data.csv - contains str ba $ qsv load data.csv - contains str BA -i $ qsv load data.csv - contains str BA --ignorecase ``` #### `sed` 使用正则表达式模式替换列中的值。 | 参数 | 类型 | 默认值 | 说明 | |--------------------|--------|----------|--------------------------------------------------------------| | pattern | str | | 要搜索的正则表达式模式。必需。 | | replacement | str | | 替换字符串。必需。 | | --column | str | (全部) | 仅对特定列应用替换。如果未指定，则应用于所有列。 | | -i, --ignorecase | flag | `false` | 执行不区分大小写的匹配。 | ``` $ qsv load data.csv - sed foo foooooo # Replace 'foo' with 'foooooo' in all columns $ qsv load data.csv - sed foo foooooo --column str # Replace 'foo' with 'foooooo' in 'str' column only $ qsv load data.csv - sed FOO foooooo -i # Case-insensitive replacement in all columns $ qsv load data.csv - sed ".*o.*" foooooo --column str # Regex replacement in specific column ``` #### `grep` 过滤任意列匹配正则表达式模式的行。 | 参数 | 类型 | 默认值 | 说明 | |---------------------|--------|----------|-----------------------------------------| | pattern | str | | 在任意列中搜索的正则表达式模式。必需。 | | -i, --ignore-case | flag | `false` | 执行不区分大小写的匹配。 | | -v, --invert-match | flag | `false` | 反转匹配含义，选择不匹配的行。 | 示例： ``` $ qsv load data.csv - grep foo $ qsv load data.csv - grep "^FOO" -i # Case-insensitive search $ qsv load data.csv - grep "^FOO" --ignore-case # Long form case-insensitive $ qsv load data.csv - grep "^FOO" -i -v # Case-insensitive inverted match $ qsv load data.csv - grep "^FOO" --ignore-case --invert-match # Long form inverted match ``` #### `head` 显示数据集的前 N 行。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|---------------------------------------------------| | number | int | 5 | 要显示的行数。可以作为位置参数或使用 -n/--number 选项指定。 | | -n, --number | int | | 指定行数的替代方式。 | ``` $ qsv load data.csv - head 3 $ qsv load data.csv - head 10 $ qsv load data.csv - head -n 3 $ qsv load data.csv - head --number 10 ``` #### `tail` 显示数据集的最后 N 行。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|---------------------------------------------------| | number | int | 5 | 要显示的行数。可以作为位置参数或使用 -n/--number 选项指定。 | | -n, --number | int | | 指定行数的替代方式。 | #### `sort` 根据指定的列对数据集进行排序。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|-------------|----------|--------------------------------------------------------------| | colnames | str/list | | 要排序的列名。多个列用逗号分隔（例如 `col1,col3`）或单个列名。必需。 | | -d, --desc | flag | `false` | 按降序排序。适用于所有指定的列。 | ``` $ qsv load data.csv - sort str $ qsv load data.csv - sort str -d $ qsv load data.csv - sort str --desc $ qsv load data.csv - sort col1,col2,col3 --desc ``` #### `count` 统计重复行，按所有列分组。结果自动按计数降序排序。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|---------------------------------------------------------| | (无) | | | 不带参数。自动按计数列降序排序输出。 | ``` $ qsv load data.csv - count $ qsv load data.csv - count - sort col1 # Count and then sort by col1 instead ``` #### `uniq` 过滤唯一行，基于所有列去除重复项。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|------------------------------------------------| | (无) | | | 不带参数。基于所有列去除重复行。 | ``` $ qsv load data.csv - uniq ``` #### `changetz` 更改 datetime 列的时区。 | 参数 | 类型 | 默认值 | 说明 | |--------------------|--------|----------|---------------------------------------------------------------------------------------------------------| | colname | str | | datetime 列的名称。必需。 | | --from-tz | str | | 源时区（例如 `UTC`、`America/New_York`、`local`）。必需。 | | --to-tz | str | | 目标时区（例如 `Asia/Tokyo`）。必需。 | | --input-format | str | `auto` | 输入 datetime 格式字符串（例如 `%Y-%m-%d %H:%M:%S%.f`）。`auto` 使用类似 Python dateutil.parser 的智能解析，支持模糊解析和自动格式检测。 | | --output-format | str | `auto` | 输出 datetime 格式字符串（例如 `%Y/%m/%d %H:%M:%S`）。`auto` 使用 ISO8601 格式 `%Y-%m-%dT%H:%M:%S%.6f%:z`（微秒精度）。 | | --ambiguous | str | `earliest` | DST 转换期间处理歧义时间的策略：`earliest`（首次出现）或 `latest`（第二次出现）。 | **理解 `--ambiguous` 选项：** 在秋季夏令时 (DST) 转换期间，时钟会"回拨"，造成重复的小时。例如，凌晨 2:30 会发生两次： - 第一次：凌晨 2:30 DST（转换前） - 第二次：凌晨 2:30 标准时间（转换后） 遇到这种歧义时间时： - `earliest`：使用第一次出现（夏令时时间） - `latest`：使用第二次出现（标准时间） 示例： ``` $ qsv load data.csv - changetz datetime --from-tz UTC --to-tz Asia/Tokyo # 输出：2023-01-01T09:00:00.123456+09:00 (ISO8601 with microsecond precision) $ qsv load data.csv - changetz datetime --from-tz UTC --to-tz America/New_York --input-format "%Y/%m/%d %H:%M" --output-format "%Y-%m-%d %H:%M:%S" # 自定义输出格式 $ qsv load data.csv - changetz datetime --from-tz America/New_York --to-tz UTC --ambiguous latest # 处理夏令时模糊时间 # 自动格式检测（类似于 Python dateutil.parser）： $ qsv load logs.csv - changetz timestamp --from-tz local --to-tz UTC # 处理："Jan 15, 2023 2:30 PM"、"2023/01/15 14:30"、"15-Jan-2023 14:30:00" 等 # 模糊解析嵌入文本： $ qsv load events.csv - changetz event_time --from-tz EST --to-tz UTC # 处理："Meeting on January 15th, 2023 at 2:30 PM"、"Call scheduled for Jan 15 2023" ``` **TODO：** 当 chrono-tz 库支持时，升级到 7 位亚秒精度（100 纳秒精度，用于 Windows FILETIME 兼容性）。当前 `auto` 输出使用微秒精度。 #### `renamecol` 重命名特定列。 | 参数 | 类型 | 默认值 | 说明 | |--------------------|--------|----------|------------------------| | old_name | str | | 当前的列名。必需。 | | new_name | str | | 新的列名。必需。 | ``` $ qsv load data.csv - renamecol current_name new_name ``` #### `convert` 在 JSON、YAML 和 XML 之间转换数据格式。也支持同一格式的格式化/美化。 | 参数 | 类型 | 默认值 | 说明 | |----------|--------|----------|--------------------------------------------| | colname | str | | 包含要转换数据的列名。必需。 | | --from | str | | 源格式：`json`、`yaml` 或 `xml`。必需。 | | --to | str | | 目标格式：`json`、`yaml` 或 `xml`。必需。 | **支持的转换：** - 跨格式：`json ↔ yaml`、`json ↔ xml`、`yaml ↔ xml` - 同格式（格式化）：`json → json`、`yaml → yaml`、`xml → xml` **功能特性：** - 自动处理格式错误的 JSON（带多余引号） - 美化并格式化数据以提高可读性 - 转换过程中保留数据结构 示例： ``` $ qsv load data.csv - convert json_col --from json --to yaml $ qsv load data.csv - convert config --from yaml --to json $ qsv load data.csv - convert data --from json --to xml $ qsv load data.csv - convert messy_json --from json --to json # Format/prettify JSON $ qsv load data.csv - convert compact_yaml --from yaml --to yaml # Format YAML ``` #### `timeline` 按时间间隔聚合数据，创建基于时间的摘要。 | 参数 | 类型 | 默认值 | 说明 | |----------------|--------|----------|--------------------------------------------------| | time_column | str | | 用于时间分桶的 datetime 列名。必需。 | | --interval | str | | 聚合的时间间隔（例如 `1h`、`30m`、`5s`、`1d`）。必需。 | | --sum | str | | 在每个时间桶中求和的列名。可选。 | | --avg | str | | 在每个时间桶中求平均的列名。可选。 | | --min | str | | 在每个时间桶中找最小值的列名。可选。 | | --max | str | | 在每个时间桶中找最大值的列名。可选。 | | --std | str | | 在每个时间桶中计算标准差的列名。可选。 | **功能特性：** - 创建一个名为 `timeline_{interval}` 的时间桶列（例如 `timeline_1h`、`timeline_30m`） - 如果未指定聚合列，则仅为每个时间桶提供行计数 - 支持各种时间间隔格式：小时 (`1h`)、分钟 (`30m`)、秒 (`5s`)、天 (`1d`) 示例： ``` $ qsv load access.log - timeline timestamp --interval 1h # 创建列：timeline_1h $ qsv load metrics.csv - timeline time --interval 5m --avg cpu_usage # 创建列：timeline_5m、count、avg_cpu_usage $ qsv load sales.csv - timeline date --interval 1d --sum amount # 创建列：timeline_1d、count、sum_amount $ qsv load server.log - timeline timestamp --interval 30s --max response_time # 创建列：timeline_30s、count、max_response_time ``` #### `timeslice` 基于时间范围过滤数据，提取指定时间边界内的记录。 | 参数 | 类型 | 默认值 | 说明 | |----------------|--------|----------|------------------------------------| | time_column | str | | 要过滤的 datetime 列名。必需。 | | --start | str | | 开始时间（含）。可选。 | | --end | str | | 结束时间（含）。可选。 | 必须指定 `--start` 或 `--end` 中的至少一个。支持各种 datetime 格式，包括 ISO8601、时间戳和常见日志格式。 示例： ``` $ qsv load data.csv - timeslice timestamp --start "2023-01-01 00:00:00" $ qsv load data.csv - timeslice timestamp --end "2023-12-31 23:59:59" $ qsv load data.csv - timeslice timestamp --start "2023-06-01" --end "2023-06-30" $ qsv load access.log - timeslice timestamp --start "2023-01-01T10:00:00" ``` #### `pivot` 基于行键和列键创建分组聚合。 | 参数 | 类型 | 默认值 | 说明 | |--------------|--------|----------|------------------------------------------------------------------------------------------| | --rows | str | | 用于行分组的逗号分隔列列表。可选。 | | --cols | str | | 用于列分组的逗号分隔列列表。可选。 | | --values | str | | 要聚合值的列。必需。 | | --agg | str | | 聚合函数：`sum`、`mean`、`count`、`min`、`max`、`median`、`std`。可选（默认：`sum`）。 | 必须指定 `--rows` 或 `--cols` 中的至少一个。当前返回请求的行和列键的长格式分组聚合，而非宽格式 Excel 风格的交叉表。 示例： ``` $ qsv load sales.csv - pivot --rows region --cols product --values sales_amount --agg sum $ qsv load data.csv - pivot --rows category --cols year --values revenue --agg mean $ qsv load logs.csv - pivot --rows date --cols error_type --values count --agg count $ qsv load metrics.csv - pivot --rows department --values performance --agg median ``` #### `timeround` 将 datetime 值四舍五入到指定的时间单位，创建新的四舍五入列同时保留原始列。 | 参数 | 类型 | 默认值 | 说明 | |------------|--------|--------------------|----------------------------------------------------------------------| | colname | str | | 要四舍五入的 datetime 列名。必需。 | | --unit | str | | 四舍五入的时间单位：`y`/`year`、`M`/`month`、`d`/`day`、`h`/`hour`、`m`/`minute`、`s`/`second`。必需。 | | --output | str | (替换原始列) | 输出列的名称。如果未指定，则替换原始列。 | **功能特性：** - 将 datetime 值向下四舍五入到最近的时间单位边界 - 用于基于时间的分组和分析 - 支持短 (`h`、`d`) 和长 (`hour`、`day`) 单位名称 - 输出格式自动调整为指定单位（简洁、最小化格式） **按单位的输出格式：** - **年 (y)**2023` - **月 (M)**：`2023-01` - **天 (d)**：`2023-01-01` - **小时 (h)**：`2023-01-01 12` - **分钟 (m)**：`2023-01-01 12:34` - **秒 (s)**：`2023-01-01 12:34:56` 示例： ``` $ qsv load data.csv - timeround timestamp --unit d --output date_only # 输入：2023-01-01 12:34:56 # 输出：2023-01-01 $ qsv load data.csv - timeround timestamp --unit h --output hour_rounded # 输入：2023-01-01 12:34:56 # 输出：2023-01-01 12 $ qsv load logs.csv - timeround timestamp --unit m # 四舍五入到分钟边界，替换原列 $ qsv load metrics.csv - timeround created_at --unit year --output created_year # 输入：2023-01-01 12:34:56 # 输出：2023 ``` ### 终止器 终止器用于输出或汇总处理后的数据。它们通常是链中的最后一个命令。 #### `partition` 根据指定列中的唯一值将数据拆分为单独的 CSV 文件。每个唯一值创建自己的文件。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------------|----------------------------------------------------------------------------------------------| | colname | str | | 用于分区的列名。必需。 | | output_directory | str | `./partitions/` | 保存分区文件的目录。可选 - 如果未指定，则创建 `./partitions/` 目录。 | 如果输出目录不存在，将自动创建。每个文件以分区列中的唯一值命名（无效的文件名字符会被替换为下划线）。 示例： ``` $ qsv load data.csv - partition category # Uses default ./partitions/ directory $ qsv load data.csv - partition category ./partitions/ # Explicit directory $ qsv load sales.csv - partition region ./by_region/ $ qsv load logs.csv - partition date ./daily_logs/ $ qsv load data.csv - select col1,col2 - partition col1 ./numeric_partitions/ ``` #### `headers` 显示当前数据集的列标题。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|------------------------------------------------| | -p, --plain | flag | `false` | 将标题显示为纯文本，每行一个，而非格式化表格。 | 示例： ``` $ qsv load data.csv - headers $ qsv load data.csv - headers -p $ qsv load data.csv - headers --plain ``` #### `stats` 显示数据集中每列的汇总统计信息（例如 count、null_count、mean、std、min、max）。 此命令不带任何参数或选项。 示例： ``` $ qsv load data.csv - stats ``` #### `showquery` 显示 Polars LazyFrame 查询计划。这对于调试和理解正在执行的操作很有用。 此命令不带任何参数或选项。 示例： ``` $ qsv load data.csv - select col1 - showquery ``` #### `show` 将结果数据以 CSV 格式显示到标准输出。默认包含标题。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|----------|--------------------------------------------------------| | --batch-size | str | `1GB` | 流式处理大型数据集的内存批大小（例如 `512MB`、`2GB`）。范围：1MB-10GB。 | 示例： ``` $ qsv load data.csv - head 5 - show $ qsv load huge.csv - show --batch-size 2GB # Streaming mode for large files $ qsv load data.csv - select col1,col2 - show --batch-size 512MB ``` #### `showtable` 将结果数据以格式化表格显示到标准输出。显示表格尺寸并智能截断大型数据集。 **功能特性：** - 显示表格尺寸信息（行 × 列），类似于 Python Polars - 对于 9 行以上的数据集：显示前 8 行和截断指示符 (`⋮`) - 对于 8 行或更少的数据集：显示所有行而不截断 - 当未指定显式终止器时，自动用作默认终止器 此命令不带任何参数或选项。 此命令由可选的 cargo 特性 `table` 控制，默认构建中已启用。 示例： ``` $ qsv load data.csv - select col1,col2 - head 3 - showtable # 输出包括：shape: (3, 2) 后跟格式化表格 $ qsv load large_data.csv - select col1,col2 # 如未指定最终格式化器，自动调用 showtable ``` 要构建不带表格渲染支持的较小二进制文件： ``` $ cargo build --release --no-default-features ``` 在该构建中，`showtable` 会退出并显示清晰的重建消息，隐式终止会回退到 `show`。 #### `dump` 将处理结果输出到 CSV 文件。 | 参数 | 类型 | 默认值 | 说明 | |-------------------|--------|--------------------|--------------------------------------------------------------| | -o, --output | str | `dump_.csv` | 保存 CSV 数据的文件路径。可选 - 如果未指定，则自动生成带时间戳的默认文件名。 | | -s, --separator | char | `,` | 输出 CSV 文件的字段分隔符字符。 | | --batch-size | str | `1GB` | 流式处理大型数据集的内存批大小（例如 `512MB`、`2GB`）。范围：1MB-10GB。 | 示例： ``` $ qsv load data.csv - dump # Saves to dump_.csv $ qsv load data.csv - head 100 - dump -o results.csv $ qsv load data.csv - head 100 - dump --output results.csv $ qsv load data.csv - head 100 - dump -o results.csv -s ';' $ qsv load huge.csv - dump -o output.csv --batch-size 2GB # Streaming mode for large files ``` #### `dumpcache` 将处理结果保存为 Parquet 缓存文件，以便快速重新加载。 **功能特性：** - 将 DataFrame 保存为压缩 Parquet 格式 - 保留数据类型（与 CSV 不同） - 对大型数据集高性能 - 可以使用 `load` 命令重新加载 | 参数 | 类型 | 默认值 | 说明 | |-------------------|-------------------------------|----------------------|----------------------------------------------| | -o, --output | str | `cache_.parquet` | 输出文件路径（可选）。如果未指定，扩展名将更改为 .parquet。 | 示例： ``` $ qsv load data.csv - head 100 - dumpcache # Auto-named cache file $ qsv load data.csv - select col1,col2 - dumpcache -o cache.parquet $ qsv load data.csv - sort col1 - dumpcache --output processed_data # 从缓存加载以快速访问 $ qsv load cache.parquet - show ``` ### Quilt (YAML 工作流) Quilt 允许您在 YAML 配置文件中定义复杂的数据处理工作流。这对于自动化重复任务或创建可重用的数据处理流水线非常有用。 #### 使用方法 `quilt` 命令本身接受 YAML 配置文件的路径。输入数据源和其他参数通常在 YAML 文件中定义。 ``` $ qsv quilt [options] ``` | 参数 | 类型 | 说明 | |--------------------------|--------|----------------------------------------------------| | config_file_path.yaml | str | 定义流水线阶段的 YAML 配置文件路径。必需。 | | -o, --output | str | 覆盖 YAML 配置中定义的最终 dump 操作的输出路径（如果有）。 | #### 示例：运行 Quilt 文件 ``` $ qsv quilt rules/my_workflow.yaml $ qsv quilt rules/my_analysis.yaml -o custom_output.csv ``` YAML 配置文件（例如 `rules/my_workflow.yaml`）定义各阶段和步骤。例如，下面的 `Sample YAML (rules/test.yaml)` 定义了一个流水线，它： 1. 加载数据（隐式或通过 `process` 阶段中的 `load` 步骤显式）。 2. 在不同阶段执行选择和连接操作。 3. 将最终结果显示为表格。 #### YAML 中的流水线操作 在 Quilt YAML 文件中，阶段可以是不同类型来编排流程。 | 操作类型 | 说明 | 关键参数 | |----------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `process` | 在数据集上执行一系列 qsv 操作。 | `steps`：操作字典（例如 `load`、`select`、`head`、`showtable`）。每个键是一个 qsv 命令，其值包含参数/选项。
`source`（可选）：指定前一阶段的输出作为输入。 | | `concat` | 连接多个数据集（阶段）。 | `sources`：要连接的阶段名称列表。
`params.how`（可选）：连接方法，`vertical`（默认）。注意：`horizontal` 连接尚未实现。 | | `join` | 基于键连接多个阶段的数据集。 | `sources`：要连接的两个阶段名称列表。
`params.left_on`/`params.right_on` 或 `params.on`：连接的列。
`params.how`（可选）：连接类型（`inner`、`left`、`outer`、`cross`）。 | Quilt 中的 timeline 步骤使用显式聚合键： ``` stages: hourly_metrics: type: process steps: load: path: metrics.csv timeline: time_column: timestamp interval: 1h agg_type: avg agg_column: cpu_usage show: ``` ## 大文件处理 qsv-rs 支持流式处理超大文件，无需将它们完全加载到内存中。 ### 使用示例 ``` # 流式显示大文件（默认 1GB 批次） $ qsv load huge.csv - show # 自定义内存使用 - 512MB 批次 $ qsv load huge.csv - show --batch-size 512MB # 高内存服务器 - 2GB 批次以获得最佳性能 $ qsv load huge.csv - show --batch-size 2GB # 流式保存大结果到文件，自定义批次大小 $ qsv load huge.csv - select important,columns - dump -o output.csv --batch-size 2GB ``` ### 内存配置 ``` # 为您的系统配置批次大小 --batch-size 512MB # Low memory systems --batch-size 1GB # Default (balanced) --batch-size 2GB # High memory systems (2GB+) # 配置 gzip 解压内存（环境变量） export QSV_MEMORY_LIMIT_MB=512 # Low memory systems export QSV_MEMORY_LIMIT_MB=1024 # Default (1GB) export QSV_MEMORY_LIMIT_MB=2048 # High memory systems (2GB+) ``` ### Gzip 文件处理 ``` # 使用不同内存设置处理大型 gzip 文件 $ QSV_MEMORY_LIMIT_MB=2048 qsv load huge.csv.gz - show $ QSV_MEMORY_LIMIT_MB=512 qsv load huge.csv.gz - head 1000 - show # Low memory ``` ### Parquet 缓存以提升性能 对于重复处理大型 CSV 文件，转换为 Parquet 格式可以显著加快加载速度。 **性能优势：** - 相比 CSV 格式加载更快 - 更好的压缩（更小的文件大小） - 保留数据类型（无需重新解析） ``` # 一次性转换：CSV 到 Parquet 缓存 $ qsv load huge.csv - dumpcache -o huge.parquet # 后续处理：从 Parquet 加载（更快） $ qsv load huge.parquet - select col1,col2 - show $ qsv load huge.parquet - isin category "important" - dump -o result.csv ``` ## 安装 ### 预构建二进制文件 从 [GitHub Releases](https://github.com/sumeshi/qsv-rs/releases) 下载最新版本。 ### 从源码构建 ``` $ git clone https://github.com/sumeshi/qsv-rs.git $ cd qsv-rs $ cargo build --release ``` ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 许可证 本项目基于 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。 灵感来自 [xsv](https://github.com/BurntSushi/xsv)。

标签：CSV, ETL, JavaCC, Polars, Rust, YAML, 二进制发布, 内存高效, 可视化界面, 大数据, 安全库, 开源工具, 批量处理, 数字取证, 数据清洗, 数据转换, 文件处理, 目录扫描, 管道, 网络流量审计, 自动化脚本, 通知系统