Anens0 / heimdall

Heimdall is a tool to perform import, export, direct SQL query and format conversion on excel files. Currently supports json, yaml, markdown, csv, xlsx, html, sql ...

Heimdall

English Version

Heimdall 是一款对 Excel 文件执行导入、导出、直接 SQL 查询和格式转换的工具。当前支持直接写 SQL 对 Excel 文件进行查询和导出，将 MySQL 数据库中的数据导出为 json、yaml、markdown、csv、xlsx、html、sql 等多种格式的文件，导入 xlsx 或者 csv 文件到 MySQL 数据库以及 xlsx、csv 文件的格式转换，文件拆分等功能。

命令行选项

heimdall 支持下列命令

• fly (或者 query-file) 使用 SQL 直接对 xlsx、csv 文件进行查询并导出为 json、yaml、markdown、csv、xlsx、html、sql 等多种格式的文件
• import (或者 load) 将 xlsx、csv 文件中的数据导入到 MySQL 数据库
• export (或者 query) 将 MySQL 中的数据，按照 SQL 的查询结果导出 json、yaml、markdown、csv、xlsx、html、sql 等多种格式的文件
• convert 将 xlsx、csv 文件转换为其它格式如 json、yaml、markdown、csv、xlsx、html、sql 等
• split 将一个比较大的 xlsx 文件拆分为多个文件，当前支持按照行数、按照某一列的值、按照 Sheet 进行拆分

fly/query-file

使用 fly/query-file 命令，可以直接对输入的 xlsx、csv 文件写 SQL 进行查询和过滤处理，并且导出为 json、yaml、markdown、csv、xlsx、html、sql 等多种格式的文件。

每一个输入（--file）的文件都会作为一个数据库表，表名命名格式为 table_序号，序号从第一个文件开始，按照 table_0，table_1，table_2 以此类推。

heimdall fly --file data.csv --file data2.csv \
    --sql "SELECT table_0.id 'ID', table_0.name '名称', table_0.created_at '创建时间', count(*) as '字段数量' FROM table_0 LEFT JOIN table_1 ON table_0.id = table_1.ref_id WHERE table_1.deleted_at = '' GROUP BY table_0.id ORDER BY count(*) DESC LIMIT 10" \
    -f table

支持下面这些命令行选项：

• --sql value, -s value, --query value SQL 语句 (如果没有指定，则会从标准输入 STDIN 中读取，直到遇到';'结束)
• --file value, -i value, --input value [ --file value, -i value, --input value ] 要查询的 xlsx 或者 csv 文件路径，可以使用 TABLE:FILE 的形式来为文件指定表名，该选项可以指定多次，用于一次对多个文件进行连表查询
• --csv-sepertor value csv 文件分隔符 (默认值: ",")
• --format value, -f value 输出格式，支持 csv, json, yaml, xml, table, html, markdown, xlsx, plain, sql (默认值: "table")
• --output value, -o value 输出路径，默认直接输出到标准输出 STDOUT
• --no-header, -n 不要输出表头
• --query-timeout value, -t value 查询超时时间，当指定 stream 选项时，该选项无效 (默认值: 2m0s)
• --xlsx-max-row value 输出格式为 xlsx 时，指定每个 Sheet 中最大的行数（包含表头），超过该值时会自动拆分到多个 Sheet (默认值: 1048576)
• --table value 输出格式为 sql 时，指定 sql 语句中的表名
• --use-column-num 使用列编号作为列名，从 1 开始，如 col_1, col_2...
• --show-tables 查看当前文件对应的所有表和字段
• --temp-ds value 临时数据库的 URI，默认使用内存数据库，可以指定文件来为多次查询加速，例如 file:data.db?cache=shared, 更多选项查看: https://www.sqlite.org/c3ref/open.html (默认值: ":memory:")
• --slient 不要输出警告日志
• --debug, -D 启用调试模式
• --beta 允许 beta 特性，当指定该选项时，大型 xlsx 文件的加载速度会有大幅度提升，目前该功能可能会存在不稳定的因素，请谨慎使用

import/load

使用 import/load 命令，可以将 xlsx、csv 文件导入到 MySQL 表中。

heimdall import --tx --database example --table users \
    --file users.csv --file users.xlsx \
    --field 姓名:name \
    --field 年龄:age

支持下面这些命令行选项：

• --host value, -H value MySQL 主机地址 (default: "127.0.0.1")
• --port value, -P value MySQL 端口 (default: 3306)
• --user value, -u value MySQL 用户名 (default: "root")
• --password value, -p value MySQL 密码
• --database value, -d value MySQL 数据库
• --connect-timeout value 数据库连接超时时间 (default: 3s)
• --debug, -D 启用调试模式 (default: false)
• --file value, -i value, --input value [ --file value, -i value, --input value ] 输入文件路径，支持 xlsx、csv，该选项可以指定多次，用于同时导入多个文件
• --table value, -t value 要导入的表名称
• --field value, -f value [ --field value, -f value ] 字段关系，如: excel_field:db_field, 该选项可以指定多次
• --include value, -I value [ --include value, -I value ] 包含字段白名单，如果指定，则只有白名单中的字段将会被导入，该选项可以指定多次
• --exclude value, -E value [ --exclude value, -E value ] 排除字段，如果指定，这里的字段将会被忽略，该选项可以指定多次
• --csv-sepertor value csv 文件分隔符 (默认值: ",")
• --tx, -T 启用事务支持，所有文件的导入全部成功或者全部失败，只有支持事务的数据存储引擎支持，如 InnoDB 等
• --dry-run 执行导入测试以验证，只有支持事务的存储引擎支持
• --create-table 自动创建表结构
• --use-column-num 使用列编号作为列名，从 1 开始，如 col_1, col_2...
• --with-ts 在创建表结构时，自动添加 created_at 字段，用于标识导入的时间
• --table-structure-format value 指定该选项时，会在导入完成后输出表结构信息，支持 table，json，yaml, markdown, html, csv, xml

export/query

使用 export/query 命令，可以写一个 SQL 来查询 MySQL 数据库中的数据，将查询结果导出到 json、yaml、markdown、csv、xlsx、html、sql 等多种格式的文件。

heimdall export --database example --format json --sql 'select * from users'

支持下面这些命令行选项：

• --host value, -H value MySQL 主机地址 (默认值: "127.0.0.1")
• --port value, -P value MySQL 端口 (默认值: 3306)
• --user value, -u value MySQL 用户 (默认值: "root")
• --password value, -p value MySQL 密码
• --database value, -d value MySQL 数据库
• --connect-timeout value 数据库连接超时时间 (默认值: 3s)
• --debug, -D 启用调试模式
• --sql value, -s value SQL 查询语句
• --format value, -f value 输出格式，支持 csv, json, yaml, xml, table, html, markdown, xlsx, plain, sql (默认值: "csv")
• --output value, -o value 输出路径，默认直接输出到标准输出 STDOUT
• --streaming, -S 是否使用流式输出，如果使用该选项，数据将会在查询过程中一行一行的写入到输出文件，使用该选项可以显著降低内存占用和数据库的查询负担。使用该选项时，输出格式只支持 csv、xlsx、json、plain、sql
• --no-header, -n 不要输出表头
• --query-timeout value, -t value 查询超时时间，当指定 stream 选项时，该选项无效 (默认值: 2m0s)
• --xlsx-max-row value 输出格式为 xlsx 时，指定每个 Sheet 中最大的行数（包含表头），超过该值时会自动拆分到多个 Sheet (默认值: 1048576)
• --table value 输出格式为 sql 时，指定 sql 语句中的表名

convert

使用 convert 命令，可以将 xlsx、csv 文件转换为 json、yaml、markdown、csv、xlsx、html、sql 等格式。

heimdall convert --file data.csv --format json --include id --include name --include updated_at

支持下面这些命令行选项：

• --file value, -i value, --input value 要转换格式的 xlsx 或者 csv 文件路径
• --csv-sepertor value csv 文件分隔符 (默认值: ",")
• --format value, -f value 输出格式，支持 csv, json, yaml, xml, table, html, markdown, xlsx, plain, sql (默认值: "table")
• --output value, -o value 输出路径，默认直接输出到标准输出 STDOUT
• --no-header, -n 不要输出表头
• --xlsx-max-row value 输出格式为 xlsx 时，指定每个 Sheet 中最大的行数（包含表头），超过该值时会自动拆分到多个 Sheet (默认值: 1048576)
• --table value 输出格式为 sql 时，指定 sql 语句中的表名
• --slient 不要输出警告日志
• --debug, -D 启用调试模式
• --include value, -I value [ --include value, -I value ] 包含字段白名单，如果指定，则只有白名单中的字段将会输出，该选项可以指定多次
• --exclude value, -E value [ --exclude value, -E value ] 排除字段，如果指定，这里的字段将会被忽略，该选项可以指定多次

split

使用 split 命令，可以将一个比较大的 xlsx 文件拆分为多个小文件，支持按照行数、指定的列值以及 Sheet 进行拆分。

heimdall split --file data.xlsx --perfile-limit 1000 --header-row-num 2

支持下面这些命令行选项：

• --file value, -i value, --input value 要拆分的 xlsx 文件路径，只支持 xlsx 文件
• --slient 不要输出警告信息
• --debug, -D 启用调试模式
• --perfile-limit value, -p value 每个文件中包含的最大行数，当 mode 为 row 时有效 (默认值: 1000)
• --header-row-num value, -r value 表格中表头行数，只有 mode 为 row 和 column 时有效 (默认值: 1)
• --mode value, -m value 文件拆分方式: row, column, sheet (默认值: "row")
• --column-index value, -c value 指定要按照哪一列的值进行拆分，如 'A', 'AA', 只在 mode 为 column 时有效

示例

将一个 xlsx 文件导入到数据库 example 的 people 表中。

heimdall import --host 127.0.0.1 --port 3306 --database example --user root --password root \
    --table people \
    --field 区域:area \ 
    --field 姓名:name \
    --field 身份证号码:idcard \
    --file ~/Downloads/data.xlsx

对数据库 example 执行 SQL，查询出创建时间为 30 天内的企业客户列表，按照 id 倒序排列，导出为 xlsx 文件。

heimdall export --database example --host 127.0.0.1 --user root --password root \
      --sql "SELECT id, name AS '企业名称', address AS '企业地址', city_name AS '城市', district_name AS '区县', DATE_FORMAT(created_at, '%Y-%m-%d %H:%i:%s') AS '创建时间' FROM enterprise WHERE created_at > DATE_SUB(NOW(), INTERVAL 30 DAY) ORDER BY id DESC" \
      --streaming \
      --format xlsx \
      --output 最近30天新增企业列表.xlsx

比较两个包含人员信息的文件，遍历文件 file-0.csv，对于其中的每一行数据，取其中的 身份证号码 字段，在 file-1.xlsx 文件中查找是否存在，如果存在则将该条数据输出到一个新的 xlsx 文件。

heimdall fly --beta \
    -i ./file-0.csv \
    -i ./file-1.xlsx  \
    --sql "select xingming as '姓名', shenfenzhenghaoma as '身份证号码', shengri as '生日', xingbie as '性别', dizhi as '地址', lianxidianhua as '联系电话' from table_0 where table_0.shenfenzhenghaoma NOT IN (select IDCARDNO from table_1)" \
    --format xlsx \
    --output result.xlsx

将 xlsx 文件中的数据，按照身份证号码这一列进行去重，只保留其中一条数据，导出为新的 xlsx 文件。

heimdall fly --beta \
    -i ./data.xlsx \
    --sql "select xingming as '姓名', shenfenzhenghaoma as '身份证号码', shengri as '生日', xingbie as '性别', dizhi as '地址', lianxidianhua as '联系电话' from table_0 where __rowid IN (SELECT max(__rowid) FROM table_0 GROUP BY shenfenzhenghaoma)" \
    --format xlsx \
    --output result.xlsx

将一个 xlsx 文件以列 A 的值进行拆分

heimdall split -i ./data.xlsx -m column -c A

将一个 xlsx 文件拆分为每个文件 1000 条数据的多个文件

heimdall split -m row --file data.xlsx --perfile-limit 1000 --header-row-num 2