csvq 1.18.1 配置参数详解

csvq v1.18.1 三层配置体系（命令行 flag、csvqrc 预载语句、csvq_env.json）实测详解：SHOW FLAGS 全 30 参数逐项释义、csvqrc 覆盖语义与 @@FORMAT 动态默认陷阱、RELOAD CONFIG 热加载、交互壳提示符/历史/配色配置与生产模板

csvqcsvqSQLCLI工具Go命令行2026/11/03

csvq 1.18.1 配置参数详解

目标：把 csvq 的全部可调参数（30 个 flag、csvq_env.json 配置节、csvqrc 预载语句）逐项讲清并给出实测生效证据，含 csvqrc 覆盖语义、@@FORMAT 动态默认陷阱、RELOAD CONFIG 热加载等易踩坑行为。以下参数与回显均在 Ubuntu 22.04 + csvq v1.18.1 实测（数据目录 /root/csvdemo，账号 root）。安装步骤见 《Ubuntu 22.04 安装 csvq 1.18.1 指南》。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（jammy），x86_64
  • csvq 版本：v1.18.1（csvq --version → csvq version 1.18.1）
  • 配置相关路径（实测生效位置）：
    • 用户级：/root/.config/csvq/csvq_env.json（配置）、/root/.config/csvq/csvqrc（预载语句）
    • 目录级：当前目录/csvq_env.json、当前目录/csvqrc
  • 测试数据：users.csv（6 列）、scores.tsv、products.json、access.ltsv、fixdata.txt（定长）、uneven.csv（坏行）、sjis.csv（Shift-JIS）、pipe.csv（竖线分隔）

二、前置条件

  • csvq 已安装（三种途径任选，见安装篇）。
  • 本文所有 SET @@...、SHOW FLAGS 语句可直接复制执行；涉及文件配置的示例给出完整文件内容。

三、参数查看与修改方式

csvq 的配置由三层叠加，优先级：命令行显式参数 > csvqrc 预载语句 / csvq_env.json > 内置默认值（官方手册原文："Overwrite Flags with Command Options"）。

3.1 查看当前生效参数：SHOW FLAGS

$ csvq "SHOW FLAGS;"

输出 30 行全表见第四章（实测原样照抄）。

3.2 命令行 flag（单次覆盖）

csvq --help 列出全部 flag（节选实测）：

   --delimiter value, -d value                  field delimiter for CSV (default: ",")
   --import-format value, -i value              default format to load files (default: "CSV")
   --format value, -f value                     format of query results. (default: "CSV" for output to pipe, "TEXT" otherwise)
   --encoding value, -e value                   file encoding (default: "AUTO")
   --out FILE, -o FILE                          export result sets of select queries to FILE

⚠️ 注意：查询语句参数必须放在所有 flag 之后。实测 csvq "SELECT ..." -o file 报 incorrect usage: csvq command takes exactly 1 argument（rc=2），正确写法是 csvq -o file "SELECT ..."。

3.3 csvqrc 预载语句（持久 SET）

csvqrc 是"语句文件"，csvq 启动时（交互壳与非交互单次查询都加载）按序读取以下位置：

$XDG_CONFIG_HOME/csvq/csvqrc 或 $HOME/.config/csvq/csvqrc
$HOME/.csvqrc
$HOME/.csvq/csvqrc
当前目录/csvqrc

文件内容就是普通 SQL 语句，每行一条 SET @@<flag> TO <值>;。实测把 SET @@DELIMITER TO '|'; 写入 /root/csvdemo/csvqrc 后，非交互查询也能正确解析竖线分隔文件：

$ cat /root/csvdemo/csvqrc
SET @@DELIMITER TO '|';
$ csvq "SELECT * FROM \`pipe.csv\`"
a,b
1,2
$ rm -f /root/csvdemo/csvqrc
$ csvq "SELECT * FROM \`pipe.csv\`"
a|b
1|2

对照回显：有 csvqrc 时 a|b 被切成两列（输出 a,b 两行两列）；删掉 csvqrc 后整行退化为单列。

⚠️ 注意：csvqrc 里写了非法参数会在启动时直接报错并中止执行（rc=1），即使本次查询本身没问题：

$ printf "SET @@ROW_LIMIT TO 3;\n" > /root/csvdemo/csvqrc
$ csvq "SELECT 1 + 1 AS r"
/root/csvdemo/csvqrc [L:1 C:5] @@ROW_LIMIT is an unknown flag
$ echo $?
1

（@@ROW_LIMIT 不是 csvq 的合法 flag，限流请写 SQL LIMIT；见 7.1。）

3.4 csvq_env.json（JSON 配置文件）

官方样例（https://raw.githubusercontent.com/mithrandie/csvq/master/csvq_env.json ）的顶层结构：

{
  "datetime_format": [],
  "timezone": "Local",
  "ansi_quotes": false,
  "interactive_shell": {
    "history_file": ".csvq_history",
    "history_limit": 500,
    "prompt": "\u001b[34;1m@#WORKING_DIRECTORY ... \u001b[0m ",
    "continuous_prompt": " > ",
    "completion": true,
    "kill_whole_line": false,
    "vi_mode": false
  },
  "environment_variables": {},
  "palette": { "effectors": { "label": {...}, "number": {...}, "string": {...} } }
}

加载顺序与 csvqrc 相同（用户级 → ~/.csvq_env.json → ~/.csvq/csvq_env.json → 当前目录），多路径同时存在时全部加载、后者覆盖前者。实测用户级配置 /root/.config/csvq/csvq_env.json 中的 environment_variables 注入生效：

$ csvq
csvq interactive shell
Press Ctrl+D or execute "EXIT;" to terminate this shell.

/root/csvdemo csvq> ECHO @%MYENV;
from-csvq-env-config

（配置节 "environment_variables": {"MYENV": "from-csvq-env-config"} 的值以 @% 前缀环境变量形式在会话内可读。）

3.5 会话内热加载：RELOAD CONFIG

改完 csvq_env.json 不必退出重进。实测交互壳内先用 $ 外部命令改配置，再 RELOAD CONFIG; 立即生效（提示符从 csvq2# 实时变为 csvq3#）：

csvq2# $ sed -i 's/csvq2#/csvq3#/' /root/.config/csvq/csvq_env.json
csvq2# ECHO 'prompt still old';
prompt still old
csvq2# RELOAD CONFIG;
csvq3# ECHO 'prompt now changed';
prompt now changed

3.6 运行时信息常量（@#）与提示符模板

@# 开头的运行时常量可在 prompt 模板与语句中引用（官方样例的 prompt 即用了 @#WORKING_DIRECTORY 与 @#UNCOMMITTED）。实测交互壳 SHOW RUNINFO; 全量回显：

/root/csvdemo > SHOW RUNINFO;
        Runtime Information
------------------------------------
       @#UNCOMMITTED: false
           @#CREATED: 0
           @#UPDATED: 0
     @#UPDATED_VIEWS: 0
     @#LOADED_TABLES: 1
 @#WORKING_DIRECTORY: /root/csvdemo
           @#VERSION: 1.18.1

单值可读（实测 ECHO @#VERSION; → 1.18.1）。事务状态常量 @#UNCOMMITTED 在交互壳有未提交修改时变为 true，默认提示符同步追加 (Uncommitted:1)（实测，详见命令详解篇事务章节）。

四、参数总览（SHOW FLAGS 实测全表）

csvq "SHOW FLAGS;" 实测原样回显（30 项，括注为默认值/初始态）：

                           Flags
-----------------------------------------------------------
                @@REPOSITORY: (current dir: /root/csvdemo)
                  @@TIMEZONE: Local
           @@DATETIME_FORMAT: (not set)
               @@ANSI_QUOTES: false
              @@STRICT_EQUAL: false
              @@WAIT_TIMEOUT: 10
             @@IMPORT_FORMAT: CSV
                 @@DELIMITER: ','
       @@ALLOW_UNEVEN_FIELDS: false
       @@DELIMITER_POSITIONS: SPACES
                @@JSON_QUERY: (empty)
                  @@ENCODING: AUTO
                 @@NO_HEADER: false
              @@WITHOUT_NULL: false
   @@STRIP_ENDING_LINE_BREAK: false
                    @@FORMAT: TEXT
            @@WRITE_ENCODING: UTF8
           @@WRITE_DELIMITER: (ignored) ','
 @@WRITE_DELIMITER_POSITIONS: (ignored) SPACES
            @@WITHOUT_HEADER: (ignored) false
                @@LINE_BREAK: LF
               @@ENCLOSE_ALL: (ignored) false
               @@JSON_ESCAPE: (ignored) BACKSLASH
              @@PRETTY_PRINT: (ignored) false
       @@SCIENTIFIC_NOTATION: false
       @@EAST_ASIAN_ENCODING: false
    @@COUNT_DIACRITICAL_SIGN: false
         @@COUNT_FORMAT_CODE: false
                     @@COLOR: false
                     @@QUIET: false
           @@LIMIT_RECURSION: 1000
                       @@CPU: 3
                     @@STATS: false

按用途分五组，逐组详解见第五章：数据读取组（IMPORT_FORMAT/DELIMITER/DELIMITER_POSITIONS/ALLOW_UNEVEN_FIELDS/NO_HEADER/ENCODING/JSON_QUERY/WITHOUT_NULL/STRIP_ENDING_LINE_BREAK/REPOSITORY）、结果输出组（FORMAT/WRITE_*/LINE_BREAK/ENCLOSE_ALL/JSON_ESCAPE/PRETTY_PRINT/SCIENTIFIC_NOTATION）、SQL 行为组（TIMEZONE/DATETIME_FORMAT/ANSI_QUOTES/STRICT_EQUAL）、字符宽度组（EAST_ASIAN_ENCODING/COUNT_DIACRITICAL_SIGN/COUNT_FORMAT_CODE）、执行控制组（COLOR/QUIET/LIMIT_RECURSION/CPU/STATS/WAIT_TIMEOUT）。

💡 说明：(ignored) 前缀表示该 flag 只在对应输出格式下起作用，当前 @@FORMAT=TEXT 时被忽略——这是 csvq 用一张表管"读配置+写配置"的设计，改输出参数前先看它是否处于 ignored 态。

五、核心参数分类详解

5.1 数据读取组

  • @@IMPORT_FORMAT（-i，默认 CSV）：文件加载格式，取值 CSV | TSV | FIXED | JSON | JSONL | LTSV。带标准扩展名的文件自动识别（实测 scores.tsv 自动按 TSV、orders.jsonl 自动按 JSONL 解析），无扩展名/定长文件必须显式指定。
  • @@DELIMITER（-d，默认 ,）：CSV 字段分隔符。实测 -D '|' 只影响输出，输入侧用 -d。
  • @@DELIMITER_POSITIONS（-m）：FIXED 定长切割位，取值是"累积偏移量"而不是列宽——三列宽 10/8/7 的写法是 [10,18,25]：
$ csvq -i FIXED -m '[10,18,25]' "SELECT * FROM \`fixdata.txt\`"
name,city,salary
Louis,Tokyo,5200000
Sean,Osaka,4100000
Mildred,Nagoya,6300000

写列宽会直接报错：csvq -i FIXED -m '[10,8,7]' ... → [L:1 C:15] data parse error in /root/csvdemo/fixdata.txt: invalid delimiter position: [10, 8, 7]。

  • @@ALLOW_UNEVEN_FIELDS（--allow-uneven-fields）：容忍列数不齐的坏行。默认关闭时整个文件报错：
$ csvq "SELECT * FROM \`uneven.csv\`"
[L:1 C:15] data parse error in /root/csvdemo/uneven.csv: line 3, column 0: wrong number of fields in line
$ csvq --allow-uneven-fields "SELECT * FROM \`uneven.csv\`"
id,name,age,__@4__
1,Louis,35,
2,Sean,,
3,Mildred,42,extra

实测行为：缺列补空、多出列以 __@4__ 自动命名。

  • @@NO_HEADER（-n/--no-header）：首行按数据处理，字段自动命名 c1,c2,c3：
$ csvq -n "SELECT * FROM \`nohdr.csv\`"
c1,c2,c3
a,b,c
1,2,3
  • @@ENCODING（-e，默认 AUTO）：输入编码，支持 AUTO | UTF8 | UTF8M | UTF16* | SJIS。实测 AUTO 能自动识别 Shift-JIS 文件，显式 -e SJIS 结果一致：
$ csvq -e SJIS "SELECT * FROM \`sjis.csv\`"
名前,太郎,東京
花子,二郎,大阪
  • @@JSON_QUERY（-j）：从嵌套 JSON 中取对象数组作为行集。实测 nested.json（{"users":[{...},{...}]}）默认直接查报错 json loading error: json value does not exists for ""，加 -j 'users'（或等价的 -j 'users{}'）后：
$ csvq -j 'users' "SELECT * FROM \`nested.json\`"
name,tags
Tom,"[""x"",""y""]"
Amy,"[""z""]"

嵌套数组值以 JSON 字符串保留。

  • @@REPOSITORY（-r）：表文件搜索根目录，默认当前目录。
  • @@WITHOUT_NULL / @@STRIP_ENDING_LINE_BREAK：空字段按空字符串解析 / 剥掉行尾换行，默认 false。

5.2 结果输出组

  • @@FORMAT（-f）：结果集格式，CSV | TSV | FIXED | JSON | JSONL | LTSV | GFM | ORG | BOX | TEXT；默认值随输出目标动态变化（管道=CSV，终端/文件=TEXT）。实测三种格式：
$ csvq -f BOX "SELECT id, name, age FROM \`users.csv\` LIMIT 2"
┌────┬────────┬─────┐
│ id │  name  │ age │
├────┼────────┼─────┤
│ 1  │ Louis  │ 35  │
│ 2  │ Sean   │ 28  │
└────┴────────┴─────┘
$ csvq -f GFM "SELECT id, name FROM \`users.csv\` LIMIT 2"
|  id  |  name  |
| ---- | ------ |
| 1    | Louis  |
| 2    | Sean   |
$ csvq -f FIXED -M '[10,18]' "SELECT id, name FROM \`users.csv\` LIMIT 3"
id        name
1         Louis
2         Sean
3         Mildred

（FIXED 输出同样用累积切割位 -M；写列宽报 data encode error: invalid delimiter position。）

  • @@WRITE_DELIMITER / @@WITHOUT_HEADER / @@ENCLOSE_ALL / @@WRITE_ENCODING / @@LINE_BREAK / @@JSON_ESCAPE / @@PRETTY_PRINT：分别控制输出分隔符（实测 -D '|' 把导出 CSV 变成竖线）、是否去表头（实测 -N）、全字段加引号、输出编码（实测 -E SJIS 导出后 iconv -f SHIFT-JIS -t UTF-8 回读中文无损）、换行符（CRLF/CR/LF）、JSON 转义方式（BACKSLASH/HEX/HEXALL）、JSON 缩进。
  • @@SCIENTIFIC_NOTATION：大数指数记法开关，默认 false。
  • @@QUIET / @@STATS：-q 抑制操作日志（实测导出文件时不再打印进度信息）；-x 打印资源统计：
$ csvq -x "SELECT COUNT(*) AS n FROM \`users.csv\`"

      Resource Statistics
-------------------------------
  TotalTime:  0.000257 seconds
 TotalAlloc:   724,472 bytes
    HeapSys: 3,768,320 bytes
    Mallocs:    23,765 objects
      Frees:     2,208 objects

n
5

5.3 SQL 行为组

  • @@TIMEZONE（-z，默认 Local）：时间戳默认时区。实测本环境未装 tzdata 时仅接受 Local/UTC，区域名与偏移量都被拒：
$ csvq -z 'Asia/Tokyo' "SELECT 1"
incorrect usage: timezone "Asia/Tokyo" does not exist
$ csvq -z '+09:00' "SELECT NOW() AS ts"
incorrect usage: timezone "+09:00" does not exist
$ csvq -z UTC "SELECT NOW() AS ts_utc"
ts_utc
2026-11-03T03:43:19.889233323Z

另实测：Linux 标准 TZ 环境变量对 csvq 无效（TZ=Asia/Tokyo csvq "SELECT NOW()" 仍输出 UTC 时刻），时区只认 -z/@@TIMEZONE。需要区域名时先 apt-get install -y tzdata。

  • @@DATETIME_FORMAT（-t）：字符串→时间戳的解析格式（YYYY/MM/DD hh24:mi:ss 等记法）。实测对"字符串列直接比较"无影响——CSV 列未显式转型时按字符串比较，-t 'YYYY/MM/DD' 下 WHERE joined = '2019-04-01' 照常命中：
$ csvq -t 'YYYY/MM/DD' "SELECT id, name FROM \`users.csv\` WHERE joined = '2019-04-01'"
id,name
1,Louis
  • @@ANSI_QUOTES（-k）：双引号按标识符引用（默认 false，双引号是字符串）。
  • @@STRICT_EQUAL（-g）：DISTINCT/GROUP BY/ORDER BY 严格相等比较，默认 false。
  • @@LIMIT_RECURSION（默认 1000）：递归 CTE 最大迭代次数。
  • @@WAIT_TIMEOUT（-w，默认 10 秒）：文件被其他 csvq 会话锁住时的最长等待。
  • @@CPU（-p，默认 3）：并行度提示。

5.4 字符宽度组（东亚文本对齐）

@@EAST_ASIAN_ENCODING（-W）、@@COUNT_DIACRITICAL_SIGN（-S）、@@COUNT_FORMAT_CODE（-A）：控制定宽输出时全角/组合音符/格式符的计数宽度，处理中日韩文本表格对齐时开启。

5.5 交互壳组（csvq_env.json 的 interactive_shell 节）

键默认（官方样例）实测说明
prompt带 @#WORKING_DIRECTORY 的彩色模板自定义 "csvq2#" 后启动提示符即为 csvq2#（见 3.5 实录）
continuous_prompt" > "多行续读提示；实测 v1.18.1 交互壳换行不触发续读（见 7.4）
history_file.csvq_history实测用户级配置指向 /root/.config/csvq/csvq_history，会话命令逐条落盘
history_limit500历史条数上限
completiontrue内置补全（交互壳内 Tab；无独立 bash 补全脚本）
kill_whole_line / vi_modefalse行删除行为 / vi 编辑模式

palette.effectors 节按角色（label/number/string/boolean/datetime/null/object/attribute/identifier/value/emphasis/json_/syntax_）配置 effects（Bold/Italic…）、foreground、background，配合 @@COLOR（-c）启用 ANSI 着色。

六、生产配置模板

场景：运维服务器 root 日常查平面文件，16GB 内存、本地 SSD，终端为 xterm-256color。写入 /root/.config/csvq/csvq_env.json（键与取值均为本文实测可用组合）：

{
  "timezone": "UTC",
  "interactive_shell": {
    "history_file": "/root/.config/csvq/csvq_history",
    "history_limit": 1000,
    "prompt": "\u001b[32;1m@#WORKING_DIRECTORY\u001b[0m > ",
    "completion": true
  },
  "environment_variables": {
    "DATADIR": "/root/csvdemo"
  }
}

逐项说明：timezone 固定 UTC 避免服务器时区漂移影响时间戳比较（实测 -z UTC 可用；装 tzdata 后可换区域名）；history_limit 1000 便于回溯长排查会话；prompt 绿色目录 + @#WORKING_DIRECTORY 运行时常量（实测自定义 prompt 生效，未提交事务时可再拼 @#UNCOMMITTED）；environment_variables 注入 @%DATADIR 供脚本化查询引用（实测 ECHO @%MYENV 机制）。配套当前目录 csvqrc 只放无命令行默认值冲突的 SET（如 SET @@ALLOW_UNEVEN_FIELDS TO TRUE;），@@FORMAT 类不要放（见 7.2）。

七、常见问题

7.1 csvqrc 写 SET @@ROW_LIMIT 后 csvq 拒绝启动

实测报错 /root/csvdemo/csvqrc [L:1 C:5] @@ROW_LIMIT is an unknown flag 且 rc=1 中止。csvq 没有行数限制 flag（--row-limit 亦报 flag provided but not defined: -row-limit），限流一律写 SQL：SELECT ... LIMIT 100。

7.2 csvqrc 里 SET @@FORMAT 不生效

实测 SET @@FORMAT TO 'JSON'; 写入 csvqrc 后，-o 导出文件仍是框线 TEXT、管道输出仍是 CSV。原因：@@FORMAT 的默认值按输出目标动态判定（"CSV for output to pipe, TEXT otherwise"），在配置加载之后才套上，覆盖了 csvqrc 的值。结论：@@FORMAT 只在命令行 -f 显式指定时可靠（实测 csvq -f JSON -o out.json "SELECT ..." 导出正常）。

7.3 时区/时间格式怎么配都不对

先确认 tzdata 是否安装：未装时 Asia/Tokyo、+09:00 一律报 timezone "..." does not exist（实测）；TZ 环境变量对 csvq 无效（实测）。用 -z UTC 或安装 tzdata 后配 -z Asia/Shanghai。

7.4 交互壳里写多行 SQL 卡住/报错

实测每条语句必须单行完成，换行报 unexpected termination，continuous_prompt 配置在 v1.18.1 不触发续读。复杂脚本落文件用 csvq -s script.sql（实测多语句顺序执行、结果顺序打印）或交互壳内 SOURCE '/path/script.sql';。

7.5 LTSV 时间戳字段值被截/变形

LTSV 以 key:value 冒号分列，值内再含冒号（如 ISO 时间戳 time:2026-11-01T08:12:03+09:00）时实测值中冒号被吞、导出变 2026-11-01T081203+0900。规避：入库前把值内冒号转义/替换，或该类文件按 TSV/CSV 导入（-i TSV）再 SPLIT 处理。

7.6 改完 csvq_env.json 要重启会话吗

不用。交互壳内执行 RELOAD CONFIG; 即热加载（实测提示符实时变化，见 3.5）。

八、参考链接