开始一个会话
安装 @antv/ava 后,使用 ava 命令;本地 npm 安装也可通过 npx ava 运行。
ava source sales.csv > session.json
DATASET_ID=$(node -p 'JSON.parse(require("fs").readFileSync("session.json", "utf8")).datasetId')
ava schema "$DATASET_ID" > schema.jsonsource 准备好数据源后返回会话 ID。结构发现按需进行;schema 返回数据源结构,以及 language id(duckdb-sql、clickhouse-sql、postgresql、tsql、snowflake-sql、python 或 javascript),可选的顶层 instructions 说明方言规则或执行环境中的变量和结果约定。重复调用 schema 会复用会话缓存。已知的查询不必提前单独调用 schema,也可以直接执行。
加载结构化数据、查看 schema、计算 profile、读写 semantic、执行 query,以及 viz 都不需要模型密钥。如果要使用 AI 命令或文本数据源,请在创建会话前设置 OPENAI_API_KEY,以及可选的 OPENAI_MODEL、OPENAI_BASE_URL。会话创建后不能修改其模型配置。
数据源输入与引擎
ava source 接受一个或多个输入。每个输入可以是文件路径、URL、包含数据源配置的 @file,或用 - 从标准输入读取一份配置。文件类型根据扩展名推断,GitHub 仓库链接会自动识别。--type 可为文件路径或文件 URL 统一指定类型。使用 owner/name 传入仓库时,指定 --type github。
把多个输入放在同一条命令里,就能在同一个会话中分析这些数据。
ava source sales.csv customers.json costs.xlsx用返回的 datasetId 执行 ava schema <datasetId> 查看查询时使用的表名。支持一起分析的数据源见接入多个数据源。
使用 --engine 选择执行引擎。CLI 会为匹配的数据源配置推断 Supabase、ClickHouse、SQL Server、Snowflake,其余情况默认 DuckDB。引擎在会话期间固定,多源会话使用 DuckDB。连接和读取配置见数据源配置。
复用已有元数据
加载数据源后,可以为 schema、profile 或 semantic 提供 --file,读取已有 JSON 文件:
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 不会自动查找、合并定义文件,也不会将定义持久化到会话之外。
探索与分析
查看统计信息并执行查询:
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 替换默认指标列表;大型数据库只需要少量统计项时,建议使用针对性的查询。
创建会话时已配置模型后,可以用以下命令完成自然语言分析:
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 的硬性行数上限更高。
不依赖数据集会话的图表命令
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.jsonrecommend、visualize 需要模型;viz 不需要 API 密钥。省略 --output 时,校验配置并返回 { chartType, config },补齐缺省的 config.type,可用于页面直接渲染;指定 --output 时,将 HTML 写入新文件,不会覆盖已有文件。渲染前先确认推荐结果是图表配置,而非 null。
命令参数
全部命令都支持可选的布尔参数 -h / --help。下方列出的位置参数均为必填。
| 命令 | 位置参数 | 标志与默认值 |
|---|---|---|
source | 一个或多个 dataset:路径、URL、@file 或 - | -t / --type:csv-file、json-file、parquet、excel、sqlite、github,文件类型按扩展名推断。--engine:duckdb、python、javascript、supabase、clickhouse、sqlserver、snowflake,推断规则见上文。 |
schema | dataset-id | 可选 --file:已有 schema JSON 文件的路径。 |
profile | dataset-id | 可选 --file:已有 profile JSON 文件的路径;否则可用 --metrics 指定逗号分隔的指标名,默认标准指标集。传入空字符串则不计算统计项。 |
semantic | dataset-id | 可选 --file:Semantic JSON 文件的路径,用于替换会话中的完整定义;不提供时读取当前定义。 |
suggest | dataset-id | --count:整数 1—100,默认 3。 |
analyze | dataset-id、自然语言 query | --strategy:direct(默认)或 loop;结果限制见下方。 |
translate | dataset-id、自然语言 query | 无额外标志。 |
query | dataset-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 文件路径。省略时返回校验后的配置。 |
dispose | dataset-id | 无额外标志。 |
| 共享执行标志 | 类型 | 默认值 | 范围 |
|---|---|---|---|
--max-rows | 整数 | 200 | 1—10000。 |
--max-result-bytes | 整数 | 1048576 | 正的安全整数。 |
| 环境变量 | 必填 | 默认值与行为 |
|---|---|---|
OPENAI_API_KEY | AI 命令与文本提取需要 | 数据集会话在创建数据源前读取;独立的 recommend、visualize 在执行命令时读取。 |
OPENAI_MODEL | 否 | gpt-4o-mini。 |
OPENAI_BASE_URL | 否 | 服务商的默认端点。 |
会话生命周期
会话闲置 30 分钟后过期,重新加载数据源可获取新 ID。复用已保存的语义定义前,先确认它仍适用于当前数据源,再加载到新会话。
使用结束后释放会话:
ava dispose "$DATASET_ID"大多数命令返回 JSON;source 在终端中打印使用指引,通过管道或重定向时输出 JSON。错误写入标准错误流,退出码为 1。结构发现可能在数据源创建后失败;已有会话仍可执行已知查询,或重试结构发现。
各命令的具体选项以 ava --help 或 ava <command> --help 为准。
与 Agent 配合使用
Agent Skill 指南包含可复制的安装提示词、配置步骤和完整收入分析示例。Agent 使用自身的推理能力,通过 CLI 加载数据、执行查询并渲染图表。
analyze、suggest、recommend 等命令仍需要前文介绍的模型配置。