Listen to events
AVA emits events while loading data, analyzing questions, and performing other operations. Subscribe by event name, or use '*' for every event:
import { AVA } from '@antv/ava';
const ava = new AVA({ llm: { model: 'your-model' } });
const listener = (event) => console.log(event.type, event.data);
ava.on('*', listener);
try {
await ava.source({ type: 'json', options: { data: [{ sales: 120 }] } });
} finally {
ava.off('*', listener);
await ava.dispose();
}Each event has a lowercase type and a data object. For example, sourcestart has data: { type: 'json' }. Event classes and constants are not exported by the public package; use the names below as strings.
Most operations emit a start and an end event. A failed operation emits an end event with data.error: { message, name? } and rejects its Promise. Check for error before treating an end event as a success. A precondition failure, such as a missing source, can occur before the start event.
Lifecycle events
These events mark AVA operations. Successful end events have empty data ({}).
| Operation | Start event | Start data | End event |
|---|---|---|---|
| Create or dispose an engine | createstart / disposestart | {} | createend / disposeend |
| Load a source | sourcestart | { type } | sourceend |
| Discover or set schema | schemastart | {} | schemaend |
| Compute or set profile | profilestart | {} | profileend |
| Set semantic definitions | semanticstart | {} | semanticend |
| Analyze a question | analyzestart | { query } | analyzeend |
| Visualize a result | visualizestart | { query } | visualizeend |
| Suggest questions | suggeststart | {} | suggestend |
Cached schema reads and semantic reads do not emit events. recommend() and viz() do not emit their own events.
Analysis events
These events describe steps within analysis. Direct calls to translate() and query() emit the same translation and query events.
| Step | Start event and data | End event and successful data |
|---|---|---|
| Translate a question | translatestart: { query }; direct analysis also includes attempt | translateend: { dsl } |
| Execute a query | querystart: { dsl } | queryend: ExecutionResult |
| Summarize results | summarizestart: { queryId } | summarizeend: { queryExplanation, conclusion, limitations?, nextStep?, usage? } |
| Direct analysis step | stepstart: { step: 0 } | stepend: { step: 0, action: 'SQL', text } |
| Loop iteration | stepstart: { step, finalAttempt? } | stepend: { step, action, text, finalAttempt? } |
Failed end events carry { error }. A step failure also carries step; the loop's final fallback includes finalAttempt: true on both step events. step is zero-based. See analysis strategies for these steps.
In direct analysis, one step wraps translation, all query retries, and optional summarization. stepend reports action: 'SQL' and the summary conclusion as text, or an empty string when summary is disabled. A recovered query error stays on queryend; exhausting retries or a translation/summary failure also produces stepend.error.
In loop analysis, stepstart fires before the model call. stepend fires after the whole iteration, including all its queries, and reports the model's action (EXPLORE, REFINE, SQL, or CONFIRM) and text. The text excludes the leading protocol tag; the action is available separately in action. Iterations without queries still emit both step events. A recoverable query failure appears on queryend; the iteration can finish normally so the next step can correct it. A failure that stops the analysis appears on stepend.error, where action and text may be absent.
For example, an exploration step followed by a refinement step emits:
stepstart → querystart → queryend → stepend (action: EXPLORE)
stepstart → stepend (action: REFINE)For example, a successful direct analyze() typically emits:
analyzestart → stepstart → translatestart → translateend → querystart → queryend
→ summarizestart → summarizeend → stepend → analyzeendRetries can repeat translation and query events. The summary is omitted when includeSummary is false.
Direct and loop analysis events include context.eventId and context.stepId. Each start/end pair shares an internal pairId, producing event IDs ${pairId}:start and ${pairId}:end; each operation and retry gets a new pair ID.
In direct analysis, stepId groups events from the same analysis and parentStepIds is empty. The summary's data.queryId references the successful query-end event's complete ID, including :end.
In loop analysis, each iteration has its own stepId, shared by its step and query events. context.parentStepIds is empty for the first iteration and contains the previous iteration's ID for later iterations. The final fallback gets a new step ID and follows the same rule.
In both strategies, step events use ${stepId}:start and ${stepId}:end as their event IDs; each operation inside a step uses its own pair ID. Standalone translate() / query() calls do not currently include this context or emit step events.
Listener parameters
| Method | Behavior |
|---|---|
on(name, listener, once?) | Subscribe; the optional once flag defaults to false. |
once(name, listener) | Subscribe for one invocation. |
off(name?, listener?) | Remove a listener, all listeners for a name, or all listeners if omitted. Pass the same listener reference used to subscribe. |
emit(name, ...args) | Emit an event manually. |
getEvents() | Return the listener registry. |
These methods are synchronous; on, once, and off return the emitter. Synchronous listener errors propagate, and asynchronous listeners are not awaited. Event data is not copied; use structuredClone(event) if you need a snapshot.