AVA API

Use this reference to look up signatures, inputs, and return values after following the quickstart. The AVA data and visualization methods are asynchronous. See Events for lifecycle subscriptions and Custom engines for engine extension points.

API at a glance

More control These APIs expose individual operations that can be called independently.

Initialization

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.

Data

source

source(config: DataSourceConfig): Promise<void>

Loads a data source through the engine. It returns no value and does not discover the schema.

await ava.source({ type: 'json', options: { data: [{ revenue: 120 }] } });

Loading a source disposes the previous engine and clears the saved schema, profile, and semantic definitions. A failed load leaves no active source. Await pending operations before replacing a source.

schema

schema(options?: SchemaOptions, setter?: (options: SchemaOptions) => Schema): Promise<Schema>

Returns the structure of the loaded source. Without a setter, AVA returns the saved schema or discovers it through the engine and saves it.

const schema = await ava.schema();

To supply an existing schema, pass a function that returns it:

await ava.schema(undefined, () => savedSchema);

A setter receives the options object (default {}) and returns a Schema synchronously. Its result replaces the saved schema and clears the saved profile. AVA validates and copies the result; invalid results or thrown errors reject the call without changing previous metadata.

Requires a loaded source. Analysis and profiling obtain the schema when needed; direct query() does not. For the walkthrough, see Inspect your data.

Schema structure

The details depend on the source and engine. A query result's schema describes its output columns and is not a source Schema.

profile

profile(options?: ProfileOptions, setter?: (options: ProfileOptions) => Profile): Promise<Profile>

Calculates and saves statistics for the loaded source through the engine. Each call without a setter computes a fresh profile and requires engine profiling support.

const profile = await ava.profile({ metrics: ['row_count', 'mean'] });

To supply an existing profile, pass a function that returns it:

await ava.profile(undefined, () => savedProfile);

A setter receives the options object (default {}) and returns a Profile synchronously. It does not require engine profiling support. AVA validates and copies its result; invalid results or thrown errors reject the call without changing previous metadata. The options are passed to the setter; AVA does not calculate or filter metrics on its behalf.

Requires a loaded source. Both paths replace the saved profile, which analysis, translation, and suggestions can reuse. Setting a profile does not replace the saved schema.

Profile format

A profile attaches observations to existing schema models and columns by name:

A missing metric means it was not computed, not zero. Setting a schema clears the saved profile, so supply the schema first when providing both manually. Loading another source or calling dispose() clears schema, profile, and semantic definitions. Updating schema or profile retains semantic definitions.

Metrics

The default metrics are row_count, null_count, distinct_count, top_values, min, max, and mean. Additional built-in metrics are duplicate_count, min_length, max_length, sum, stddev, and median.

Each entry is a metric name or an object with an id and metric-specific options:

await ava.profile({
  metrics: ['row_count', { id: 'top_values', limit: 5 }],
});

Other built-in metrics accept no additional options. Unknown metrics and unknown option names are rejected when the engine computes the profile. Availability depends on the engine and field type.

metrics: [] produces empty metric objects. A new profile replaces previous statistics; metrics are not accumulated.

semantic

semantic(options?: SemanticOptions, setter?: (options: SemanticOptions) => Semantic): Promise<Semantic>

Reads or replaces the semantic definitions for the loaded source. Without a setter, returns the saved definitions, initially {}. This call does not discover the schema, compute a profile, or call an LLM.

await ava.semantic(undefined, () => ({
  description: 'Sales reporting; amounts are in USD.',
  cubes: [{
    name: 'revenue',
    baseObject: 'data',
    measures: [{ name: 'total', expression: 'SUM(revenue)', type: 'DOUBLE' }],
  }],
}));
 
const definitions = await ava.semantic();
await ava.semantic(undefined, () => ({})); // Clear the saved definitions.

The setter receives the options object and returns a Semantic synchronously. AVA validates and copies the result; invalid results or thrown errors leave the previous definitions unchanged. Requires a loaded source. Source replacement and disposal clear these definitions; schema and profile updates retain them.

Semantic contains business definitions and excludes model and column metrics; supply statistical observations through profile(). The combined context passed to engines remains a DataModel.

Start with Define data semantics for the authoring walkthrough and sales example. See semantic fields for the detailed reference.

For analyze(), translate(), and suggest(), AVA merges models and columns by name with the schema and profile. Unspecified models, columns, and observations remain available; model and column properties merge by key, with semantic values taking precedence. A supplied relationship or view list replaces its discovered counterpart, including when the list is empty. Each semantic model must declare exactly one source: tableReference, refSql, or baseObject.

These definitions provide context for query generation. Declaring a cube, view, or calculated column does not create database objects; generated queries must work with the configured engine.

Analysis and queries

analyze

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

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.

Visualization

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.

Cleanup

dispose

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

Semantic model reference

Semantic fields

All six top-level fields are optional. Supply only the sections your application needs. Names and required expressions must be nonempty strings. properties contains JSON values with finite numbers; keys such as description, unit, synonyms, and owner are application conventions, not built-in SDK behaviors.

Semantic models

A primary or unique key is a declaration, not an observed statistic. Verify it against the source. primaryKey: ['tenant_id', 'order_id'] is one composite key. uniqueKeys: ['email', ['tenant_id', 'external_id']] declares two alternative unique keys.

Semantic columns

Semantic relationships and views

Relationships and views accept additional JSON-valued attributes whose meaning is agreed on by your application and consumers.

Semantic cubes and expressions

Each entry in measures, dimensions, and timeDimensions uses the same fields:

For a calendar drill-down, define dimension expressions for year, month, and order_date, then declare hierarchies: { calendar: ['year', 'month', 'order_date'] }. A hierarchy describes a path; it does not generate those fields.

Model, column, cube, and expression objects reject unknown fields; put application annotations in properties where supported.

Semantic model sources

Call schema() and inspect model names, source references, and column types before writing mappings. Names match exactly within their owning model. The inline JSON source in the sales example is exposed as data; other sources can have different names and catalog or schema qualifiers.

Every entry in models needs a name and exactly one source selector, even when you only want to add a description to an existing model:

Use the existing schema model's name to enrich it. A different name adds a logical model; it does not rename the underlying table. A column needs both name and type, including when adding only a description. Copy the discovered type for physical columns; specify the result type for calculations.

baseObject, refSql, and column expression describe mappings for the query generator. A logical name is not automatically executable in query(). For example, a query using a calculated net_amount must inline its expression or define it in a subquery or CTE.

Semantic join and view examples

Add relationships when analysis spans more than one model. Add views when a reusable SQL definition makes business logic clearer. These snippets assume an existing source exposing orders and customers; they are separate from the single-table sales example.

Relationship example

import type { Semantic } from '@antv/ava';
 
const semantic = {
  relationships: [{
    name: 'order_customer',
    models: ['orders', 'customers'],
    joinType: 'MANY_TO_ONE',
    condition: 'orders.customer_id = customers.id',
    properties: { description: 'Each order belongs to one customer.' },
  }],
} satisfies Semantic;

models is an ordered pair. MANY_TO_ONE means many rows in the first model can match one row in the second. joinType describes cardinality; it does not choose LEFT JOIN or INNER JOIN. The join condition must include all parts of a composite key.

If you expose a relationship navigation column, set its relationship to the relationship's name , and its type to the target model name, for example { name: 'customer', type: 'customers', relationship: 'order_customer' }. The physical foreign-key column remains customer_id.

Check grain before aggregating across a join. Joining one order to many line items can repeat the order amount. A cardinality declaration supplies context; AVA does not verify uniqueness or automatically prevent double counting.

View and derived model example

import type { Semantic } from '@antv/ava';
 
const semantic = {
  views: [{
    name: 'paid_orders',
    statement: "SELECT * FROM orders WHERE status = 'paid'",
    dialect: 'duckdb',
    properties: { description: 'Paid orders only; this excludes fully refunded orders.' },
  }],
  models: [{
    name: 'paid_sales',
    baseObject: 'paid_orders',
    properties: { description: 'One row per paid order.' },
  }],
} satisfies Semantic;

Here a logical model references a named query. A generator can expand that query as a CTE or subquery. await ava.query('SELECT * FROM paid_orders') only works if that name already exists in the execution engine; saving this definition does not create it. A model's refSql can describe its source query directly when a separate named view is unnecessary.

Save and combine semantic definitions

Keep one complete definition in your application, version it alongside the source it describes, and pass it to AVA after source(). Calling the setter replaces the saved semantic object. It does not append definitions or patch the previous object.

await ava.semantic(undefined, () => completeDefinitions);
const saved = await ava.semantic();
await ava.semantic(undefined, () => ({})); // Clear all saved semantics.

Definitions can live in code or in an application-owned JSON file. For example, after loading a source in Node.js:

const { readFile } = require('node:fs/promises');
const definitions = JSON.parse(await readFile('./sales-semantic.json', 'utf8'));
await ava.semantic(undefined, () => definitions);

The JSON file contains the definition object, without the JavaScript variable declaration or setter. AVA accepts an object, not a file path; if you store YAML, parse it in your application before calling the setter. Reading and parsing the file can happen asynchronously before the setter returns the object.

When an operation needs its data model, AVA combines the inputs in this order:

Omitting a section retains the corresponding schema context. If adding a relationship alongside discovered foreign keys, include the discovered relationships you want to keep in the supplied list. Reading schema(), profile(), or semantic() still returns that input, not the combined model; there is no public method to read the merged DataModel.

Changing the schema clears the saved profile and retains semantic definitions. Profiling replaces observations and retains semantic definitions. Loading another source or calling dispose() clears all three. Reapply your saved definition after loading a new source, and review mappings if its structure changed. Calls require a loaded source; a failed source replacement leaves no active source.

The setter validates and copies its returned object. A validation failure or thrown error leaves the previous semantic definition in place.

Semantic validation

Structural validation checks field shapes, required fields, source-selector exclusivity, and nonempty measure lists. It does not prove that SQL is valid, referenced objects exist, key declarations hold, units are consistent, or business rules are correct. Duplicate semantic model names and duplicate column names within a model are rejected when building the combined model for analysis, translation, or suggestions, rather than by the setter alone.

Use the sales example’s pattern for your own definition:

1. Inspect schema() and map exact names and physical types. For remote sources, preserve catalog and schema qualifiers.
2. Have the business owner review grain, eligible statuses, null handling, units, and time meaning.
3. Run each declared expression against a small fixture with known answers. Include excluded rows, nulls, refunds, and join duplication where relevant.
4. Inspect translate() output for those same questions, then compare executed results with the known answers. A successful setter is not a successful end-to-end check.
5. Repeat the checks when the source schema or business definitions change.