跳至正文
AVA使用文档
浏览文档
分析与可视化

分析数据

用自然语言提问，获得可检查的查询结果与分析结论。

已经有明确的问题，直接调用 analyze()；还没想好从哪里入手，可以先用 suggest() 找分析方向。想先检查生成的代码、再决定是否执行，就把 translate() 和 query() 分开调用。

下面的示例假定已经配置好 ava，并通过 source() 加载了数据。安装与完整配置示例见安装与快速开始。

示例沿用快速开始中的小型销售数据集：

regionrevenue
East120
West90
East80

提出分析问题

将自然语言问题传给 analyze()：

typescript
const result = await ava.analyze('What is total revenue by region?');
console.log(result.text);
console.table(result.data);

analyze() 按需获取 schema，结合已有 profile 和你提供的业务语义，生成查询、执行并整理答案。业务语义可以说明哪些订单计入收入等规则。它返回数据与文字，不会直接生成图表。

读懂返回结果

上面的问题可能返回如下结果。结论的措辞、生成的查询和列别名会随模型而变化。

json
{
  "query": "What is total revenue by region?",
  "text": "East has total revenue of 200, compared with 90 for West.",
  "schema": [{ "name": "region" }, { "name": "total_revenue" }],
  "data": [
    { "region": "East", "total_revenue": 200 },
    { "region": "West", "total_revenue": 90 }
  ],
  "rowCount": 2
}
字段类型含义
querystring原始问题。
textstring模型生成的总结；includeSummary 为 false 时为空字符串。
schemaQueryColumn[]返回列的定义，每列包含 name: string 和可选的 type: string。
dataRecord<string, unknown>[]可用于展示、导出或可视化的结果行。
rowCountnumber，可选结果完整时的行数，不是输入数据集的总行数。
sqlstring，可选实际执行的查询；使用 Python 或 JavaScript 引擎时，这个字段名仍保持不变。
markdownstring，可选返回时提供的 Markdown 内容。
truncatedtrue，可选实际数据超过结果限制，返回结果不完整。
truncatedBy'maxRows' 或 'maxResultBytes'，可选触发截断的限制项。

请通过 schema 读取实际返回的列名，不要假定模型一定使用 total_revenue 这个别名。

配置一次分析

analyze(query: string, config?: AnalysisConfig) 接受以下输入：

参数类型必填默认值与行为
querystring是自然语言问题。
configAnalysisConfig否{}。
config.includeSummaryboolean否true；设为 false 可跳过结果总结。
config.maxRowsnumber否200，限制返回行数。
config.maxResultBytesnumber否1048576（1 MiB），限制序列化后的结果数据大小。
config.strategyAnalysisStrategyConfig否默认直接分析，详见策略选项。

例如，最多返回 100 行，并跳过文字总结：

typescript
const result = await ava.analyze('What is total revenue by region?', {
  includeSummary: false,
  maxRows: 100,
  maxResultBytes: 1048576,
});
 
console.log(result.text); // ''
console.table(result.data);

处理不完整的结果

假设这份两地区的结果使用了 maxRows: 1，简化后的返回内容可能是：

json
{
  "schema": [{ "name": "region" }, { "name": "total_revenue" }],
  "data": [{ "region": "East", "total_revenue": 200 }],
  "truncated": true,
  "truncatedBy": "maxRows"
}

这只是部分答案。将它作为完整结果展示前，应先检查截断字段：

typescript
if (result.truncated) {
  console.log(`Showing a partial result: ${result.truncatedBy} was reached.`);
}

maxRows 向下取整后限制在 1—1000000 之间；取整后超出安全整数范围则使用默认值。maxResultBytes 向下取整后最小为 1，非有限值使用默认值。这两项限制也适用于下面的 query()；它们约束返回数据，并不限制查询的总耗时或内存消耗。

推荐分析问题

使用 suggest() 获取分析方向。也可以先计算 profile，为上下文补充统计信息；这一步可选，且不调用大模型。

typescript
await ava.profile();
const suggestions = await ava.suggest(2);
console.log(suggestions);
参数类型必填默认值与行为
countnumber否3，期望获取的推荐问题数量。

suggest() 需要先加载数据源，并会调用已配置的模型。有最新 profile 时使用 profile，否则使用 schema。

推荐结果

对于销售数据集，返回数组可能如下：

json
[
  {
    "query": "What is total revenue by region?",
    "score": 0.95,
    "reason": "Compare each region's contribution to overall revenue."
  },
  {
    "query": "What is average revenue per record in each region?",
    "score": 0.82,
    "reason": "Compare typical record values across regions with different record counts."
  }
]

这些只是示例，并非固定输出。在界面中可以这样使用各字段：

字段类型使用方式
querystring展示为可选择的问题，并传给 analyze()。
scorenumber用于排序。数值限制在 0—1 之间，并按降序排列；它表示问题的分析价值，不是答案的可信度。
reasonstring解释这个问题为什么值得分析，例如展示在问题下方。

最多返回 count 条推荐，也可能返回空数组。提示词会要求模型让问题和推荐理由沿用数据集的语言。

分析推荐的问题

typescript
if (suggestions.length > 0) {
  const selected = suggestions[0];
  const answer = await ava.analyze(selected.query);
  console.log(selected.reason);
  console.table(answer.data);
}

分析策略

analyze() 默认直接分析。如果问题需要不同的处理方式，可以为每次调用指定策略：

策略适用情况
direct问题明确，生成并执行一个查询即可回答。
loop需要先做中间探索，再形成答案。

示例、重试控制与步数限制见分析策略。

分开生成与执行查询

用 translate() 先查看生成的代码，再决定是否交给 query() 执行：

typescript
const dsl = await ava.translate('What is total revenue by region?');
console.log(dsl); // Display the generated query for review.
 
// Run this step when your application is ready to execute the query.
const rows = await ava.query(dsl, {
  maxRows: 100,
  maxResultBytes: 1048576,
});
console.table(rows.data);
方法参数类型必填与默认值
translate(query)querystring必填，自然语言问题。
query(dsl, options?)dslstring必填，使用当前引擎语言的可执行语句。
query(dsl, options?)optionsExecutionOptions可选，默认值见下方。
query(dsl, options?)options.maxRowsnumber可选，200；边界规则与 analyze() 相同。
query(dsl, options?)options.maxResultBytesnumber可选，1048576；边界规则与 analyze() 相同。

两个方法都需要先加载数据源。translate() 结合模型、schema 和已有 profile，返回字符串；query() 直接执行传入语句，不会做模型翻译、总结或自动纠错。

默认 Node.js 配置生成 SQL；其他引擎则使用各自的 SQL 方言、Python 或 JavaScript。SQL 引擎会验证查询是否只读；Python 和 JavaScript 的执行限制取决于各自的环境。

query() 返回前文介绍的 schema、data 和可选截断信息，但不包含分析结果中的 query、text、sql 字段。

错误处理与资源清理

未加载数据源、模型请求失败、推荐结果无法解析，或重试后仍执行失败等情况，都会让调用抛出错误。不要把错误当成没有数据的答案。

在分析调用外处理错误，并在使用结束后释放实例：

typescript
try {
  const result = await ava.analyze('What is total revenue by region?');
  console.table(result.data);
} catch (error) {
  console.error('Analysis failed:', error);
} finally {
  await ava.dispose();
}

请始终等待清理完成。再次调用 source() 会替换数据集，并清空 schema 和 profile 缓存；新数据源需要统计信息时，请重新调用 profile()。

在 GitHub 编辑本页