API 参考

完成快速开始后，可以在这里查阅方法签名、输入与返回值。AVA 的数据和可视化方法均为异步方法。生命周期订阅见事件，引擎扩展点见自定义引擎。

API 速览

分步控制 这些 API 提供可独立调用的单步操作。

初始化

构造函数

new AVA(config: AVAConfig)

构造函数不加载数据，引擎会在 source() 时创建。

模型选项

以下字段位于 config.llm 中。

以字符串传入模型名称时，默认使用兼容 OpenAI 的 Chat Completions ；传入模型对象时则直接使用该对象。用量回调并不完整覆盖每次模型请求，不能用来汇总全部用量。

引擎选项

提供 engine 时，config.engine.type 必填。支持 duckdb、python、javascript、supabase、clickhouse，以及通过 registerEngine() 注册的名称。省略 engine 时选择 DuckDB。JavaScript、Supabase、ClickHouse 没有其他引擎字段，连接凭证放在 source() 中。

DuckDB

将 engine.type 设为 duckdb。engine 接受的全部额外字段如下。

Python

将 engine.type 设为 python。engine 接受的全部额外字段如下。

已注册的引擎

将 engine.type 设为传给 registerEngine() 的名称。其余字段以 options 传给引擎构造函数。这是 SDK 能力，CLI 仅支持内置引擎名。

数据

source

source(config: DataSourceConfig): Promise<void>

通过引擎加载数据源，没有返回值，也不会发现 schema。

await ava.source({ type: 'json', options: { data: [{ revenue: 120 }] } });

加载数据源会释放旧引擎，清除保存的 schema、profile 和业务语义。加载失败后没有活动数据源。替换数据源前，请等待正在进行的操作完成。

schema

schema(options?: SchemaOptions, setter?: (options: SchemaOptions) => Schema): Promise<Schema>

返回已加载数据源的结构。不提供 setter 时，AVA 优先返回已保存的 schema；没有缓存则通过引擎发现并保存。

const schema = await ava.schema();

如需提供已有 schema，传入返回该对象的函数：

await ava.schema(undefined, () => savedSchema);

Setter 接收选项对象（默认 {}），同步返回 Schema。结果会替换已保存的 schema，并清空 profile。AVA 会验证并复制结果；结果无效或 setter 抛错时，调用失败，原有元数据保持不变。

需要先加载数据源。分析和统计会按需获取 schema，直接 query() 不要求提前发现结构。使用流程见了解数据结构。

Schema 结构

具体内容取决于数据源和引擎。查询结果中的 schema 描述输出列，并不是数据源的 Schema。

profile

profile(options?: ProfileOptions, setter?: (options: ProfileOptions) => Profile): Promise<Profile>

通过引擎计算并保存已加载数据源的统计信息。不传 setter 时，每次调用都会重新计算，需要引擎支持统计。

const profile = await ava.profile({ metrics: ['row_count', 'mean'] });

如需提供已有 profile，传入返回该对象的函数：

await ava.profile(undefined, () => savedProfile);

Setter 接收选项对象（默认 {}），同步返回 Profile，不要求引擎支持统计。AVA 会验证并复制结果；无效结果或 setter 抛错会让调用失败，并保留原有元数据。选项直接传给 setter，AVA 不会代替它计算或过滤指标。

需要先加载数据源。两条路径都会替换已保存的 profile，供分析、翻译和推荐问题复用。设置 profile 不会替换 schema。

Profile 格式

Profile 通过名称，将统计信息附加到已有的 schema 模型和列上：

指标缺失表示未计算，不代表零。设置 schema 会清空 profile，因此手动提供两者时应先设置 schema。加载新数据源或调用 dispose() 会清空 schema、profile、semantic；更新 schema 或 profile 会保留 semantic。

统计指标

默认指标为 row_count、null_count、distinct_count、top_values、min、max、mean。其他内置指标包括 duplicate_count、min_length、max_length、sum、stddev、median。

每项可以是指标名称，也可以是包含 id 和该指标专用选项的对象：

await ava.profile({
  metrics: ['row_count', { id: 'top_values', limit: 5 }],
});

其他内置指标没有额外选项。引擎计算 profile 时会拒绝未知指标与未知选项名。指标是否可用取决于引擎及字段类型。

metrics: [] 会生成空的指标对象。新 profile 替换旧统计信息，不会累加之前的指标。

semantic

semantic(options?: SemanticOptions, setter?: (options: SemanticOptions) => Semantic): Promise<Semantic>

读取或替换已加载数据源的语义定义。不传 setter 时返回已保存的定义，初始为 {}。这个调用不会发现 schema、计算 profile 或请求大模型。

await ava.semantic(undefined, () => ({
  description: 'Sales reporting; amounts are in USD.',
  cubes: [{
    name: 'revenue',
    baseObject: 'data',
    measures: [{ name: 'total', expression: 'SUM(revenue)', type: 'DOUBLE' }],
  }],
}));
 
const definitions = await ava.semantic();
await ava.semantic(undefined, () => ({})); // Clear the saved definitions.

Setter 接收选项对象，同步返回 Semantic。AVA 验证并复制结果；结果无效或 setter 抛错时保留之前的定义。需要先加载数据源。替换数据源或释放实例会清空语义；更新 schema、profile 会保留它。

Semantic 描述业务定义，不包含模型或列的 metrics；统计信息应通过 profile() 提供。引擎接收的组合上下文仍是 DataModel。

编写流程和销售示例见补充业务语义，详细字段见语义字段。

在 analyze()、translate()、suggest() 中，AVA 按名称将语义中的模型和列与 schema、profile 合并。未指定的模型、列及统计信息仍可使用；模型和列的属性按键合并，同名键以语义值为准。显式提供的关系或视图列表会整体替换发现的列表，包括空列表。每个语义模型都必须且只能声明一种来源：tableReference、refSql 或 baseObject。

这些定义为查询生成提供上下文。声明 cube、view 或计算列不会创建数据库对象，生成的查询仍须能在配置的引擎中执行。

分析与查询

analyze

analyze(query: string, config?: AnalysisConfig): Promise<AnalysisResponse>

这些重试控制与 llm.maxRetries 不同，详见策略行为及使用要求。

需要先加载数据源。返回 ExecutionResult，并附加：

translate

translate(query: string): Promise<string>

需要先加载数据源。只返回生成的 DSL，不执行；可用 query() 执行返回的字符串。

query

query(dsl: string, options?: ExecutionOptions): Promise<ExecutionResult>

需要先加载数据源，不会调用模型生成查询或总结结果。

ExecutionOptions

这些选项限制返回数据，与引擎执行超时相互独立。

ExecutionResult

suggest

suggest(count?: number): Promise<SuggestResult[]>

需要先加载数据源。按评分降序返回推荐问题，每项包含 query: string、score: number（0—1）、reason: string。

可视化

visualize 与 recommend

visualize(analysisResult): Promise<VisualizeResponse | null>

recommend(analysisResult): Promise<ChartSpec | null>

两种方法接受相同的输入：

两种方法都不要求加载数据源，均调用模型；数据为空或没有推荐出图表时返回 null，生成错误则直接抛出。recommend() 返回 ChartSpec；visualize() 还返回 html: string，包含独立的图表页面。

viz

viz(spec: ChartSpec): Promise<string>

ChartType 可选值：line、column、bar、pie、area、scatter、dual-axes、histogram、boxplot、radar、funnel、waterfall、liquid、word-cloud、violin、venn、treemap、sankey、table、summary。

返回独立 HTML 字符串，无需加载数据源，也不会调用模型。参见图表配置。

资源清理

dispose

dispose(): Promise<void> 没有参数，释放当前引擎并清空 schema、profile 与业务语义。应在 finally 中等待它执行完成。

语义模型参考

语义字段

六个顶层字段均可选，按应用需要提供即可。名称和必填表达式必须是非空字符串。properties 包含 JSON 值，其中的数值必须有限；description、unit、synonyms、owner 等键是应用约定，不代表 SDK 内置行为。

语义模型

主键、唯一键是声明，不是统计结论，需要对照数据源验证。primaryKey: ['tenant_id', 'order_id'] 表示一个复合键；uniqueKeys: ['email', ['tenant_id', 'external_id']] 则声明两个候选唯一键。

语义列

语义关系与视图

关系和视图允许额外的 JSON 属性，由应用及其使用方约定含义。

语义 Cube 与表达式

measures、dimensions 和 timeDimensions 的每一项都使用以下字段：

例如，按日历下钻时，先定义 year、month、order_date 的维度表达式，再声明 hierarchies: { calendar: ['year', 'month', 'order_date'] }。层级只描述路径，不会自动生成这些字段。

模型、列、Cube 和表达式对象会拒绝未知字段；需要应用注释时，放在支持的 properties 中。

语义模型来源

编写映射前，先调用 schema() 检查模型名称、来源引用与列类型。名称必须在所属模型内准确匹配。销售示例的内存 JSON 暴露为 data；其他数据源可能使用不同名称，并带有 catalog 或 schema 限定信息。

models 中的每一项都需要 name，并且 只能选择一种 来源，即使只是想给已有模型补充描述：

使用已有 schema 模型的 name 可以补充该模型。换用其他名称会新增逻辑模型，不会重命名底层表。列即使只补充描述，也必须提供 name 和 type；物理列沿用发现的类型，计算列声明结果类型。

baseObject、refSql 和列的 expression 为查询生成器描述映射。逻辑名称不代表能直接交给 query() 执行。例如，查询计算列 net_amount 时，需要展开其表达式，或通过子查询、CTE 定义。

语义关系与视图示例

跨模型分析时添加关系；可复用 SQL 有助于表达业务逻辑时添加视图。以下片段假定已有数据源提供 orders、customers，与前面的单表销售示例相互独立。

关系示例

import type { Semantic } from '@antv/ava';
 
const semantic = {
  relationships: [{
    name: 'order_customer',
    models: ['orders', 'customers'],
    joinType: 'MANY_TO_ONE',
    condition: 'orders.customer_id = customers.id',
    properties: { description: 'Each order belongs to one customer.' },
  }],
} satisfies Semantic;

models 是有序模型对。MANY_TO_ONE 表示第一模型的多行可以匹配第二模型的一行。joinType 描述基数，不决定使用 LEFT JOIN 还是 INNER JOIN。复合键的连接条件需要包含所有键字段。

如果暴露关系导航列，应将 relationship 设为关系的 名称 ，将 type 设为目标模型名，例如 { name: 'customer', type: 'customers', relationship: 'order_customer' }。物理外键列仍是 customer_id。

跨表聚合前先检查行粒度。一笔订单连接多条明细时，订单金额可能被重复计算。基数声明只提供上下文，AVA 不会验证唯一性，也不会自动避免重复计数。

视图与派生模型示例

import type { Semantic } from '@antv/ava';
 
const semantic = {
  views: [{
    name: 'paid_orders',
    statement: "SELECT * FROM orders WHERE status = 'paid'",
    dialect: 'duckdb',
    properties: { description: 'Paid orders only; this excludes fully refunded orders.' },
  }],
  models: [{
    name: 'paid_sales',
    baseObject: 'paid_orders',
    properties: { description: 'One row per paid order.' },
  }],
} satisfies Semantic;

这里的逻辑模型引用一个命名查询，生成器可以将其展开为 CTE 或子查询。只有执行引擎中已存在 paid_orders 时，await ava.query('SELECT * FROM paid_orders') 才能执行；保存定义不会创建它。不需要单独命名视图时，也可以直接用模型的 refSql 描述来源查询。

保存并合并语义定义

在应用中保留一份完整定义，与对应数据源一起管理版本，并在 source() 之后传给 AVA。每次 setter 都替换已保存的整个语义对象，不会追加或局部修改旧定义。

await ava.semantic(undefined, () => completeDefinitions);
const saved = await ava.semantic();
await ava.semantic(undefined, () => ({})); // Clear all saved semantics.

定义可保存在代码或应用自己的 JSON 文件中。例如，Node.js 加载数据源后：

const { readFile } = require('node:fs/promises');
const definitions = JSON.parse(await readFile('./sales-semantic.json', 'utf8'));
await ava.semantic(undefined, () => definitions);

JSON 文件只包含定义对象，不带 JavaScript 变量声明或 setter。AVA 接受对象而非文件路径；如果保存为 YAML，请先在应用中解析，再调用 setter。读取和解析文件可以异步完成，setter 本身同步返回对象。

操作需要数据模型时，AVA 按以下顺序组合输入：

省略某部分会保留对应的 schema 上下文。需要在已发现的外键之外新增关系时，应在传入列表中包含仍要保留的关系。读取 schema()、profile()、semantic() 返回的仍是各自输入，不是组合模型；目前没有公开方法读取合并后的 DataModel。

更新 schema 会清空 profile、保留语义；计算 profile 会替换统计信息、保留语义；加载新数据源或调用 dispose() 会清空三者。加载新数据源后应重新应用保存的定义，并在结构变化时复核映射。这些调用都需要活动数据源，替换数据源失败后则没有活动数据源。

Setter 验证并复制返回对象。验证失败或 setter 抛错时，之前的语义定义保持不变。

语义验证

结构验证检查字段形状、必填项、来源选择器的互斥性及非空指标列表，但 不能证明 SQL 有效、引用对象存在、键声明成立、单位一致或业务规则正确。重复的语义模型名、同一模型内的重复列名，会在分析、翻译或推荐问题组装组合模型时被拒绝，而非仅由 setter 拒绝。

为自己的数据定义口径时，可以沿用销售示例的验证流程：

1. 查看 schema()，准确匹配名称与物理类型。远程数据源需保留 catalog 和 schema 限定信息。
2. 请业务负责人复核行粒度、纳入统计的状态、空值处理、单位与时间口径。
3. 用答案已知的小数据集逐一运行表达式，按需覆盖被排除记录、空值、退款及连接重复计数等情况。
4. 针对同样的问题检查 translate() 输出，再将执行结果与已知答案对照。Setter 成功不等于端到端验证成功。
5. 数据源结构或业务定义变化后，重新执行这些检查。