Skip to content

FILTER_GUIDE.md

Latest commit

 

History

History
355 lines (250 loc) · 8.13 KB

FILTER_GUIDE.md

File metadata and controls

355 lines (250 loc) · 8.13 KB

数据过滤和列选择指南

本指南介绍如何使用 excel-cli 的数据过滤和列选择功能，让您在导出前精确控制需要的数据。

目录

功能概述

数据过滤功能让您可以：

  1. 选择特定列 - 只导出需要的列
  2. 排除敏感列 - 移除不需要或敏感的列
  3. 过滤数据行 - 根据条件筛选符合要求的数据
  4. 组合使用 - 同时应用多个过滤条件

所有过滤操作都在内存中完成，不会修改原始 Excel 文件。

列选择

使用 --select 参数选择需要的列。

语法

excel-cli convert -i <输入文件> -o <输出文件> --select "<列名1>,<列名2>,<列名3>"

示例

假设有如下 Excel 数据：

ID Name Age City Salary Password
1 张三 28 北京 15000 secret1
2 李四 35 上海 22000 secret2

只导出 Name, Age, City 三列：

excel-cli convert -i users.xlsx -o users.json --select "Name,Age,City"

输出：

[
  {
    "Name": "张三",
    "Age": 28,
    "City": "北京"
  },
  {
    "Name": "李四",
    "Age": 35,
    "City": "上海"
  }
]

注意事项

  • 列名区分大小写，必须与 Excel 中的列名完全一致
  • 多个列名用逗号分隔
  • 列名顺序会影响输出顺序
  • 如果指定的列名不存在，会报错

列排除

使用 --exclude 参数排除不需要的列。

语法

excel-cli convert -i <输入文件> -o <输出文件> --exclude "<列名1>,<列名2>"

示例

排除 Password 和 Salary 列：

excel-cli convert -i users.xlsx -o users.json --exclude "Password,Salary"

输出：

[
  {
    "ID": 1,
    "Name": "张三",
    "Age": 28,
    "City": "北京"
  },
  {
    "ID": 2,
    "Name": "李四",
    "Age": 35,
    "City": "上海"
  }
]

使用场景

  • 移除敏感信息（如密码、身份证号）
  • 排除内部使用的列
  • 减少输出文件大小

行过滤

使用 --filter 参数根据条件筛选数据行。

语法

excel-cli convert -i <输入文件> -o <输出文件> --filter "<条件>"

支持的操作符

操作符 说明 示例
== 等于 City == 北京
!= 不等于 Status != 已删除
> 大于 Age > 30
< 小于 Price < 100
>= 大于等于 Score >= 60
<= 小于等于 Quantity <= 10
contains 包含（字符串） Name contains 张
not_contains 不包含（字符串） Email not_contains test
is_empty 为空 Phone is_empty
is_not_empty 不为空 Address is_not_empty

示例

1. 简单数值比较

筛选年龄大于 30 的用户：

excel-cli convert -i users.xlsx -o adults.json --filter "Age > 30"

2. 字符串相等

筛选北京的用户：

excel-cli convert -i users.xlsx -o beijing_users.json --filter "City == 北京"

3. 字符串包含

筛选名字中包含"张"的用户：

excel-cli convert -i users.xlsx -o zhang_users.json --filter "Name contains 张"

4. 多个条件（AND 关系）

筛选年龄大于 30 且工资高于 20000 的用户：

excel-cli convert -i users.xlsx -o senior_high_paid.json \
  --filter "Age > 30" \
  --filter "Salary > 20000"

5. 检查空值

筛选有手机号的用户：

excel-cli convert -i users.xlsx -o with_phone.json --filter "Phone is_not_empty"

条件格式

  • 格式：<列名> <操作符> <值>
  • 空格是必须的
  • 值可以是数字、字符串或布尔值
  • 字符串值不需要引号（除非包含空格）
  • 多个条件之间是 AND 关系（所有条件都必须满足）

组合使用

您可以同时使用列选择、列排除和行过滤。

示例 1：选择列 + 过滤行

只导出 Name, Age, Salary，且只包含工资高于 15000 的员工：

excel-cli convert -i employees.xlsx -o high_paid.json \
  --select "Name,Age,Salary" \
  --filter "Salary > 15000"

示例 2：排除列 + 过滤行

排除敏感列，只保留活跃用户：

excel-cli convert -i users.xlsx -o active_users.json \
  --exclude "Password,InternalId,CreatedBy" \
  --filter "Active == true"

示例 3：复杂组合

选择特定列，应用多个过滤条件：

excel-cli convert -i sales.xlsx -o q4_high_value.csv -f csv \
  --select "Date,Customer,Amount,Region" \
  --filter "Date >= 2023-10-01" \
  --filter "Amount > 10000" \
  --filter "Region == 华东"

示例 4：导出 SQL 时使用过滤

excel-cli convert -i users.xlsx -o active_users.sql -f sql \
  --sql-dialect postgresql \
  --sql-table active_users \
  --select "Name,Email,Age,City" \
  --filter "Active == true" \
  --filter "Age >= 18"

输出：

-- Generated by excel-cli
-- Dialect: PostgreSQL
-- Table: active_users
-- Rows: 5

INSERT INTO "active_users" ("Name", "Email", "Age", "City") VALUES
('张三', 'zhang@example.com', 28, '北京'),
('李四', 'li@example.com', 35, '上海'),
...

实际应用场景

场景 1：数据脱敏

从用户数据中移除敏感信息：

excel-cli convert -i users_full.xlsx -o users_public.json \
  --exclude "Password,BankAccount,IDNumber,Phone"

场景 2：市场分析

筛选特定地区的高价值客户：

excel-cli convert -i customers.xlsx -o high_value_customers.csv -f csv \
  --select "Name,Company,Revenue,Industry,Region" \
  --filter "Revenue > 1000000" \
  --filter "Region contains 华东"

场景 3：数据验证

找出数据不完整的记录：

excel-cli convert -i contacts.xlsx -o incomplete.json \
  --filter "Email is_empty"

场景 4：报表生成

生成特定时期的销售报表：

excel-cli convert -i sales_2023.xlsx -o q4_report.csv -f csv \
  --select "Date,Product,Quantity,Amount,Salesperson" \
  --filter "Date >= 2023-10-01" \
  --filter "Amount > 0"

场景 5：测试数据生成

从生产数据中生成测试数据（移除真实信息）：

excel-cli convert -i prod_orders.xlsx -o test_orders.sql -f sql \
  --sql-dialect mysql \
  --sql-table test_orders \
  --exclude "CustomerPhone,CustomerAddress,PaymentInfo" \
  --filter "Status == 已完成" \
  --filter "Amount < 1000"

性能建议

  1. 先过滤行，后选择列 - 系统会自动优化，但建议在命令行中按此顺序
  2. 使用列选择代替排除 - 当需要的列较少时，--select 比 --exclude 更高效
  3. 组合多个条件 - 多个 --filter 参数会依次应用，尽早排除不需要的数据
  4. 大文件处理 - 对于超大 Excel 文件，考虑先用 Excel 自带的筛选功能预处理

常见问题

Q: 可以使用 OR 条件吗？

A: 当前版本只支持 AND 条件。如需 OR 逻辑，请分多次运行命令，然后合并结果。

Q: 过滤条件中如何处理包含空格的值？

A: 在命令行中用引号括起整个条件：

--filter "City == San Francisco"

Q: 可以使用正则表达式吗？

A: 当前版本不支持正则表达式，但支持 contains 操作符进行简单的子串匹配。

Q: 过滤后没有数据怎么办？

A: 工具会显示警告但仍会创建输出文件（空数组或无数据行）。检查：

  1. 列名是否正确（区分大小写）
  2. 条件值是否正确
  3. 操作符是否合适

Q: 可以同时使用 --select 和 --exclude 吗？

A: 可以，但不推荐。如果同时使用，会先应用 --select，再应用 --exclude。

小结

数据过滤功能让 excel-cli 不仅仅是一个格式转换工具，更是一个强大的数据预处理工具。通过灵活组合列选择、列排除和行过滤，您可以：

  • 🔒 保护敏感数据
  • 📊 快速生成报表
  • 🎯 精确提取所需数据
  • ⚡ 提高后续处理效率

结合 SQL 导出和 Schema 生成功能，excel-cli 可以成为您数据处理工作流中的得力助手。