AVA ( Visual Analytics) is a technology framework designed for more convenient visual analytics. The first A has multiple meanings: AI native, Automated, Augmented, and VA stands for Visual Analytics. It can assist users in unstructured data loading, data processing and analysis, as well as visualization code generation.
✨ Features
- 💬 Natural-language analysis — Turn questions into executable queries, computed results, and summaries.
- 📊 Visualization — Recommend chart types and generate chart specifications and HTML.
- 🔍 Data profiling — Inspect tables and calculate missing-value counts, ranges, and averages.
- 💡 Question suggestions — Discover useful questions based on your data's structure and available statistics.
- 🔌 App and agent integration — Use AVA through its SDK, CLI, or agent skill.
- ⚙️ Multiple execution engines — Use DuckDB, Python/pandas, or remote databases in Node.js, and JavaScript in browsers.
- 🧩 Composable workflows — Combine data loading, query generation, direct queries, and chart rendering.
🚀 Getting started
📦 Installation
Install AVA 4.0 with Node.js 22.13+:
npm install @antv/ava@4
💻 Usage
Investigate a monthly sales decline: measure the change, identify the largest contributors, and visualize the breakdown.
Load data
Download sales.csv to your working directory. The sample contains 240 orders across 2025, with products, regions, channels, sales, and profit.
import { AVA } from '@antv/ava';
const ava = new AVA({
llm: {
model: '<your-model>',
apiKey: '<your-api-key>',
// baseURL: '<your-provider-api-url>',
},
});
await ava.source({ type: 'csv-file', options: { path: './sales.csv' } });
Ask questions
Measure the overall change using sales, the amount after discounts:
const overview = await ava.analyze(`
Compare total sales in January and February 2025 using the sales column.
Include the change and percentage change.
`);
console.log(overview.text);
Expected: sales fell from 38,897.18 to 21,804.11, down 17,093.07 (43.94%).
Find the products contributing to the decline:
const result = await ava.analyze(`
Compare January and February 2025 sales by product using the sales column.
Show both months and the change, ordered by the largest decline.
`);
console.log(result.text);
console.table(result.data);
Expected breakdown:
| Product | January sales | February sales | Change |
|---|
| Laptop | 19,688.10 | 3,596.00 | −16,092.10 |
| Standing Desk | 9,655.80 | 5,546.10 | −4,109.70 |
| Monitor | 6,536.25 | 4,731.00 | −1,805.25 |
| Pen Set | 232.20 | 127.71 | −104.49 |
| Bookshelf | 1,225.50 | 1,251.30 | +25.80 |
| Copy Paper | 59.19 | 137.06 | +77.87 |
| Notebook | 31.50 | 137.03 | +105.53 |
| Keyboard | 215.64 | 1,015.31 | +799.67 |
| Office Chair | 1,253.00 | 5,262.60 | +4,009.60 |
Laptops contributed the largest decline, while office chairs delivered the largest increase.
Visualize charts
Chart each product's contribution to the sales change:
import { writeFile } from 'node:fs/promises';
const chart = await ava.visualize({
query: 'Plot the sales change by product from January to February 2025 as a bar chart.',
data: result.data,
});
if (chart) {
await writeFile('sales-change.html', chart.html);
}
Open sales-change.html in a browser with internet access.
Find questions to explore
Get suggested questions for your data:
const suggestions = await ava.suggest();
console.log(suggestions);
💡 Suggested questions
How do sales change month by month?
Which products contribute the most profit?
How do sales compare across channels?
Understand your data
Check missing values and sales ranges:
console.log(await ava.schema());
console.log(await ava.profile({ metrics: ['row_count', 'null_count', 'min', 'max'] }));
The sample has one missing region and one missing quantity.
Release resources when finished:
await ava.dispose();
🔌 Connect your data
Connect files and databases, or load inline data.
Load an Excel workbook with source():
await ava.source({ type: 'excel', options: { path: './sales.xlsx' } });
See the data source guide for connection settings and engine support.
For browser applications, use @antv/ava/browser with inline data. See runtime configuration.
🧩 More ways to use AVA
The agent and CLI workflows run on Node.js 22.13+ on macOS or Linux.
Use with an Agent
Your agent plans the analysis; AVA runs queries and creates charts.
npm install -g @antv/ava@4
npx skills add antvis/AVA
In a new agent session, ask:
Use the AVA skill to analyze ./sales.csv. Compare January and February 2025
sales, identify the products contributing most to the change, and save a chart.
This workflow uses your agent's existing model. See agent setup.
Use from the CLI
Configure your model and load a CSV:
npm install -g @antv/ava@4
export OPENAI_API_KEY='<your-api-key>'
export OPENAI_MODEL='<your-model>'
# export OPENAI_BASE_URL='<your-provider-api-url>'
ava source ./sales.csv
Use the dataset ID returned by source:
ava analyze '<your-dataset-id>' 'Compare January and February 2025 sales by product, including the change.'
ava dispose '<your-dataset-id>'
analyze returns the answer as JSON. dispose releases the dataset. See all CLI commands.
Feishu Bitable links are detected automatically, both /base/ links and wiki-hosted /wiki/ links resolved through the wiki API: ava source "https://<tenant>.feishu.cn/base/<app_token>?table=<table_id>" or ava source "https://<tenant>.feishu.cn/wiki/<node_token>?table=<table_id>". Provide credentials through the source config, AVA_FEISHU_APP_ID/AVA_FEISHU_APP_SECRET, or ~/.ava/feishu.json; see the data source guide.
📚 Resources
🤝 Developer Contributions
Contributions are welcome. Include tests, examples, and documentation with new features.
Run npm test to test your changes. For model-backed tests, copy .env.example to .env and add your model settings.
🔗 Related Projects
📑 Papers
VizLinter - Chen, Q., Sun, F., Xu, X., Chen, Z., Wang, J. and Cao, N., 2021. VizLinter: A Linter and Fixer Framework for Data Visualization. IEEE transactions on visualization and computer graphics, 28(1), pp.206-216.
《数据可视化设计的类型学实践》（Exploring the Typology of Visualization Design） - 蓝星宇, 王嘉喆. 数据可视化设计的类型学实践, 《美术大观》, 2022(3), 149-152.
⚖️ License
MIT
