公开入口
index.ts 注册全部 Node.js 引擎,导出 AVA 和公开类型;index.browser.ts 只注册 JavaScript。ava.ts 协调数据源状态、数据模型、事件与引擎生命周期。
源码目录
| 源码 | 职责 |
|---|---|
ava.ts | 公开 API、数据源状态与生命周期 |
types.ts | 统一维护公开类型定义及 schema 推导类型 |
contracts/ | 按 source、schema、profile、semantic、query、analyze、suggest 与图表 API 组织契约 |
engines.ts | 引擎选择与注册表 |
analysis/ | Direct 与 Loop 分析策略 |
duckdb/ | SQL 引擎、数据源加载器与统计 |
interpreter/javascript/ | 内存数据与 JavaScript 执行 |
interpreter/python/ | pandas 执行与数据源验证 |
remote/supabase/ | Management API、结构发现与统计 |
remote/clickhouse/ | 远程 SQL、结构发现与统计 |
remote/snowflake/ | Snowflake 驱动会话、结构发现与统计 |
query/ | 查询生成与方言验证 |
visualization/ | 图表推荐、GPT-Vis 配置与 HTML 生成 |
suggest/ | 分析问题推荐 |
event/ | 事件类型与载荷 |
cli/ | 命令与本地数据集会话 |
util/ | 目录组装、模型格式化、指标执行规则与结果限制 |
契约按公开 API 组织。source/ 按数据源类型分文件维护运行时 schema,包括 CSV/JSON/Excel 读取选项;source/index.ts 组装数据源联合契约,source/shared.ts 维护共用的文件与连接字段。schema.ts、profile.ts、semantic.ts、query.ts、analyze.ts、translate.ts、suggest.ts 分别维护对应 API 输入与输出的运行时 schema。visualize.ts 维护 recommend()、viz()、visualize() 共用的图表结构。跨 API 的 JSON 值与数据模型基础定义放在 shared/。
types.ts 汇总公开的配置、引擎、策略及数据类型定义;数据类型从运行时 schema 推导。数据模型组装器维护从公共元数据字段派生的严格输入校验。模块通过 contracts/index.ts 导入 API schema,从所属模块导入内部 schema,通过 types.ts 导入类型;契约定义之间直接引用,避免循环依赖。index.ts 与 index.browser.ts 统一导出 API 输入、输出 schema,类型沿用原有名称;CLI 消息协议、AI 阶段输出与引擎专用限制仍由各自模块维护。
方法与模块的对应关系
| 公开方法 | 职责与实现 |
|---|---|
source() / schema() / dispose() | ava.ts 中的数据源状态与引擎生命周期 |
profile() | 各引擎实现统计计算,共享指标约定位于 util/profile.ts |
analyze() | 分发到 analysis/direct.ts 或 analysis/loop.ts |
translate() / query() | 引擎的 getDSL() / execute() |
suggest() | suggest/index.ts |
recommend() | visualization/advisor.ts 与配置生成 |
viz() | visualization/generator.ts 中的 HTML 包装 |
visualize() | 组合 recommend() 和 viz() |
上下文与状态
每个 AVA 实例持有一个活动引擎及其 schema、profile 缓存。source() 加载数据,schema() 在首次使用时发现结构;profile() 重新计算并保存统计信息;需要时再由缓存元数据组装数据模型。重新加载或释放实例会清空两类缓存。
引擎持有数据与连接。load() 不返回元数据,schema() 发现结构,profile(schema, options?) 计算统计信息,getDSL(query, dataModel) 使用 AVA 组装的数据模型。共享数据校验位于 contracts/;目录组装与指标执行工具保留在 util/。
分析策略共享一个运行时,其中包括引擎、模型配置、数据模型与事件发射器。查询结果限制通过共享工具统一规范化。
文档组织方式
每个主题都是 site/content/docs/ 下的独立 MDX 文件,按 data/、analysis/、visualization/、engines/、reference/ 分组。这样的组织对应公开能力,无需将每个内部辅助函数都拆成独立的用户文档。