AVA API

Use this reference to look up inputs after following the quickstart. Types and defaults below follow the current src/ava.ts implementation. All instance methods listed here are asynchronous.

Constructor

new AVA(config: AVAConfig)

The constructor does not load data. Engine creation happens on source().

Model options

Fields below belong to config.llm.

String model names use OpenAI-compatible Chat Completions by default. A supplied model object is used directly. Usage callbacks are not a complete accounting stream for every LLM request.

Engine options

config.engine.type is required when engine is supplied. Supported values are duckdb, python, javascript, supabase, and clickhouse, plus names registered through registerEngine(). Omitting engine selects DuckDB. JavaScript, Supabase, and ClickHouse accept no additional engine fields; connection credentials belong to source().

DuckDB

Set engine.type to duckdb. These are all additional fields accepted on engine.

Python

Set engine.type to python. These are all additional fields accepted on engine.

Registered engines

Set engine.type to the name passed to registerEngine(). Additional fields are forwarded to the engine constructor as options. This is an SDK-only capability; the CLI supports built-in engine names.

registerEngine

registerEngine(type: string, engineClass: EngineClass): void

Exported by both SDK entry points. Register an engine implemented in your own application before loading a source.

Registration affects the loaded SDK module only. See Custom engines for a complete external implementation and lifecycle details.

source

source(config: DataSourceConfig): Promise<void>

Returns no value. Call schema() to inspect the loaded source. Reloading clears the cached schema and profile.

schema

schema(): Promise<Schema> takes no parameters. Requires a loaded source. Returns tables and optional relations; see schema and metadata.

profile

profile(options?: ProfileOptions): Promise<Profile>

Supported built-in metric names: row_count, null_count, distinct_count, top_values, min, max, mean, duplicate_count, min_length, max_length, sum, stddev, median. Other metrics accept no additional options. Unknown metrics and unknown option names are rejected. Availability depends on the engine's definitions and the field type.

Requires a loaded source and an engine with profile(). Returns and caches a Profile; metrics: [] skips metric computation. See profiling for the output format.

analyze

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

subset has no additional options. These retry controls differ from llm.maxRetries. See strategy behavior and requirements.

Requires a loaded source. Returns an ExecutionResult plus:

translate

translate(query: string): Promise<string>

Requires a loaded source. Returns generated DSL without executing it; use query() to execute that string.

query

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

Requires a loaded source. Does not generate or summarize a query with the model.

ExecutionOptions

These limits bound returned data; they are separate from engine execution timeouts.

ExecutionResult

suggest

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

Requires a loaded source. Returns suggestions sorted by descending score, each with query: string, score: number (0–1), and reason: string.

visualize and recommend

visualize(analysisResult): Promise<VisualizeResponse | null>

recommend(analysisResult): Promise<ChartSpec | null>

Both methods accept the same input:

Neither requires a loaded source. Both use the model and return null for empty data or when no chart is recommended. Generation errors propagate. recommend() returns a ChartSpec; visualize() additionally returns html: string containing a standalone chart page.

viz

viz(spec: ChartSpec): Promise<string>

ChartType values: line, column, bar, pie, area, scatter, dual-axes, histogram, boxplot, radar, funnel, waterfall, liquid, word-cloud, violin, venn, treemap, sankey, table, summary.

Returns a standalone HTML string. Does not require a loaded source or call a model. See chart specifications.

dispose

dispose(): Promise<void> takes no parameters. Releases the current engine and clears the schema and profile. Await it in a finally block.

Event methods

AVA inherits synchronous on, once, off, emit, and getEvents methods from the AntV event emitter. See event method parameters.

executionResult helper

executionResult<T>(rows: T[], schema: QueryColumn[], options?: ExecutionOptions, upstreamTruncatedBy?: 'maxRows' | 'maxResultBytes'): ExecutionResult<T>

A synchronous helper exported by both SDK entry points for custom engine implementations. Import it from @antv/ava or @antv/ava/browser.

Returns bounded data, schema, and either rowCount for a complete result or truncation metadata for a partial result. Throws if an individual result field exceeds 1 MiB. The helper bounds already-produced rows; it does not limit query execution or input memory use.