跳至正文
AVA使用文档
浏览文档
更多资源

命令行工具

在终端中加载数据、查询分析、生成图表，并复用本地会话。

开始一个会话

安装 @antv/ava 后，使用 ava 命令；本地 npm 安装也可通过 npx ava 运行。持久会话需要 macOS 或 Linux。

bash
ava source sales.csv > session.json
DATASET_ID=$(node -p 'JSON.parse(require("fs").readFileSync("session.json", "utf8")).datasetId')
ava schema "$DATASET_ID" > schema.json

source 准备好数据源后返回会话 ID。结构发现按需进行；schema 返回数据源结构，以及用于编写查询的 language（包含 name、fence 和可选的 instructions）。重复调用 schema 会复用会话缓存。已知的查询不必提前单独调用 schema，也可以直接执行。

加载结构化数据、查看 schema、计算 profile、读写 semantic、执行 query，以及 viz 都不需要模型密钥。如果要使用 AI 命令或文本数据源，请在创建会话前设置 OPENAI_API_KEY，以及可选的 OPENAI_MODEL、OPENAI_BASE_URL。会话创建后不能修改其模型配置。

数据源输入与引擎

ava source 接受文件或 URL、包含数据源配置的 @file，或用 - 读取标准输入。CSV、JSON、Parquet、Excel、SQLite 可根据扩展名推断类型；路径输入可用 --type 覆盖类型。配置文件和标准输入本身已包含类型。

使用 --engine 选择执行引擎。CLI 会为匹配的数据源配置推断 Supabase、ClickHouse，其余情况默认 DuckDB；这与 JavaScript 构造函数的行为不同。引擎在会话期间固定。连接和读取配置见数据源配置。

复用已有元数据

加载数据源后，可以为 schema、profile 或 semantic 提供 --file，读取已有 JSON 文件：

bash
ava schema "$DATASET_ID" --file schema.json
ava profile "$DATASET_ID" --file profile.json
ava semantic "$DATASET_ID" --file semantic.json

传入普通文件路径，不加 @。AVA 验证后将内容保存到会话中。设置 schema 会清空 profile，因此需要同时提供时，请先设置 schema。设置 profile 只替换统计信息，不替换 schema。设置 semantic 会替换完整业务定义，并保留 schema 和 profile；更新 schema 或 profile 也会保留 semantic。元数据应与当前数据源匹配。

不提供 --file 时，schema 使用缓存结构，或通过引擎发现；profile 重新计算统计信息；semantic 返回已保存的定义，初始值为 {}。profile 的 --file 不可与 --metrics 同时使用。详见 schema 行为、profile 行为和业务口径。

保留 semantic JSON 文件，可在不同会话中复用已确认的指标口径。加载内容为 {} 的文件即可清空当前定义；文件无效时，原有定义保持不变。验证只检查 JSON 结构，不能证明 SQL 正确或业务规则适用于当前数据源。CLI 不会自动查找、合并定义文件，也不会将定义持久化到会话之外。

探索与分析

查看统计信息并执行查询：

bash
ava profile "$DATASET_ID" --metrics row_count,null_count,mean > profile.json
ava query "$DATASET_ID" --dsl @query.sql --max-rows 100 > result.json

不传 --file 时，每次 profile 调用都会重新计算。--metrics 替换默认指标列表；大型数据库只需要少量统计项时，建议使用针对性的查询。

创建会话时已配置模型后，可以用以下命令完成自然语言分析：

bash
ava suggest "$DATASET_ID"
ava translate "$DATASET_ID" "Total revenue by region"
ava analyze "$DATASET_ID" "Total revenue by region" --strategy direct

这些操作会按需发现 schema，并使用已有 profile 和已加载的语义定义。query 按原样执行 DSL；语义定义不会改写查询，也不会创建数据库对象。CLI 支持 direct 和 loop。--max-rows 接受 1—10,000，默认 200；JavaScript API 的硬性行数上限更高。

不依赖数据集会话的图表命令

bash
ava recommend --query "Plot revenue by region" --data @rows.json > chart.json
ava viz --spec @chart.json --output chart.html
ava visualize --query "Plot revenue by region" --data @rows.json

recommend、visualize 需要模型；viz 按配置渲染，不需要 API 密钥。viz 的输出路径必须是新文件，不会覆盖已有文件。渲染前先确认推荐结果是图表配置，而非 null。

命令参数

全部命令都支持可选的布尔参数 -h / --help。下方列出的位置参数均为必填。

命令位置参数标志与默认值
sourcedataset：路径、URL、@file 或 --t / --type：csv-file、json-file、parquet、excel、sqlite，默认按扩展名推断。--engine：duckdb、python、javascript、supabase、clickhouse，推断规则见上文。
schemadataset-id可选 --file：已有 schema JSON 文件的路径。
profiledataset-id可选 --file：已有 profile JSON 文件的路径；否则可用 --metrics 指定逗号分隔的指标名，默认标准指标集。传入空字符串则不计算统计项。
semanticdataset-id可选 --file：Semantic JSON 文件的路径，用于替换会话中的完整定义；不提供时读取当前定义。
suggestdataset-id--count：整数 1—100，默认 3。
analyzedataset-id、自然语言 query--strategy：direct（默认）或 loop；结果限制见下方。
translatedataset-id、自然语言 query无额外标志。
querydataset-id必填 --dsl：代码、@file 或 -，不能为空，最多 512 KiB；可选 --max-rows、--max-result-bytes 见下方。
visualize无必填 --query：文本；必填 --data：JSON 对象数组、@file 或 -；可选 -o / --output：新的 HTML 文件路径。
recommend无必填 --query：文本；必填 --data：JSON 对象数组、@file 或 -。
viz无必填 --spec：JSON、@file 或 -，包含 chartType 和 config 对象；必填 -o / --output：新的 HTML 文件路径。
disposedataset-id无额外标志。
共享执行标志类型默认值范围
--max-rows整数2001—10000。
--max-result-bytes整数1048576正的安全整数。
环境变量必填默认值与行为
OPENAI_API_KEYAI 命令与文本提取需要数据集会话在创建数据源前读取；独立的 recommend、visualize 在执行命令时读取。
OPENAI_MODEL否gpt-4o-mini。
OPENAI_BASE_URL否服务商的默认端点。

会话生命周期

会话闲置 30 分钟后过期，重新加载数据源可获取新 ID。复用已保存的语义定义前，先确认它仍适用于当前数据源，再加载到新会话。

使用结束后释放会话：

bash
ava dispose "$DATASET_ID"

大多数命令返回 JSON；source 在终端中打印使用指引，通过管道或重定向时输出 JSON。错误写入标准错误流，退出码为 1。结构发现可能在数据源创建后失败；已有会话仍可执行已知查询，或重试结构发现。

各命令的具体选项以 ava --help 或 ava <command> --help 为准。

与 Agent 配合使用

Agent Skill 指南包含可复制的安装提示词、配置步骤和完整收入分析示例。Agent 使用自身的推理能力，通过 CLI 加载数据、执行查询并渲染图表。

analyze、suggest、recommend 等命令仍需要前文介绍的模型配置。

在 GitHub 编辑本页