Skip to content
Browse documentation
API Reference

Events

Observe data loading, model work, query execution, and cleanup.

Listen to events

AVA emits events while loading data, analyzing questions, and performing other operations. Subscribe by event name, or use '*' for every event:

typescript
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 ({}).

OperationStart eventStart dataEnd event
Create or dispose an enginecreatestart / disposestart{}createend / disposeend
Load a sourcesourcestart{ type }sourceend
Discover or set schemaschemastart{}schemaend
Compute or set profileprofilestart{}profileend
Set semantic definitionssemanticstart{}semanticend
Analyze a questionanalyzestart{ query }analyzeend
Visualize a resultvisualizestart{ query }visualizeend
Suggest questionssuggeststart{}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.

StepStart event and dataEnd event and successful data
Translate a questiontranslatestart: { query }; direct analysis also includes attempttranslateend: { dsl }
Execute a queryquerystart: { dsl }queryend: ExecutionResult
Summarize resultssummarizestart: { queryId }summarizeend: { queryExplanation, conclusion, limitations?, nextStep?, usage? }
Direct analysis stepstepstart: { step: 0 }stepend: { step: 0, action: 'SQL', text }
Loop iterationstepstart: { 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:

text
stepstart → querystart → queryend → stepend (action: EXPLORE)
stepstart → stepend (action: REFINE)

For example, a successful direct analyze() typically emits:

text
analyzestart → stepstart → translatestart → translateend → querystart → queryend
             → summarizestart → summarizeend → stepend → analyzeend

Retries 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

MethodBehavior
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.