Data sources

Choose a data source above, then use its example and parameter table below. CSV and JSON each support inline content and files.

Connect a source

Create an AVA instance, then call source({ type, options }):

import { AVA } from '@antv/ava';
 
const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
});
 
await ava.source({
  type: 'json',
  options: { data: [{ city: 'Hangzhou', revenue: 120 }] },
});
 
const schema = await ava.schema();

source() returns no value. Calling it again replaces the current source and clears its cached schema and profile. Use schema() to inspect the actual table and field names, and call await ava.dispose() when finished.

The examples use Node.js. Supabase and ClickHouse include their required constructor settings alongside the source call. For frontend applications, see browser usage.

CSV

Inline CSV

Pass the CSV content as a string with type: 'csv'.

await ava.source({
  type: 'csv',
  options: { csv: 'city,revenue\nHangzhou,120\nShanghai,200' },
});

CSV files

Use type: 'csv-file' with a local path or HTTP(S) URL. For a protected URL, supply request headers in options.headers.

await ava.source({
  type: 'csv-file',
  options: {
    path: 'https://example.com/sales.csv',
    headers: { Authorization: 'Bearer YOUR_TOKEN' },
    options: { header: true, delim: ';' },
  },
});

CSV reader options

Use these fields in options.options for csv and csv-file sources with DuckDB. Every field is optional. AVA forwards supplied values to read_csv; omitted values use DuckDB reader defaults or detection. Defaults below describe individual reader settings; automatic detection can determine the effective header, delimiter, and types.

JSON

Inline JSON

Pass an array of objects with type: 'json'.

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

JSON files

Use type: 'json-file' with a local path or HTTP(S) URL.

await ava.source({
  type: 'json-file',
  options: { path: './sales.json' },
});

Parquet

Read a Parquet file from a local path or HTTP(S) URL.

await ava.source({
  type: 'parquet',
  options: { path: './sales.parquet' },
});

Excel

Read a workbook from a local path or HTTP(S) URL. Each sheet becomes a separate table; call schema() to discover their names.

await ava.source({
  type: 'excel',
  options: { path: './sales.xlsx' },
});

Text

Extract structured rows from unstructured text. This source calls your configured model.

await ava.source({
  type: 'text',
  options: { text: 'Hangzhou revenue was 120. Shanghai revenue was 200.' },
});

SQLite

Open a local SQLite database in read-only mode.

await ava.source({
  type: 'sqlite',
  options: { path: './analytics.sqlite' },
});

MySQL

Connect to a database and discover its tables.

await ava.source({
  type: 'mysql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.MYSQL_PASSWORD,
  },
});

PostgreSQL

Connect to a database and discover its tables.

await ava.source({
  type: 'postgresql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.POSTGRES_PASSWORD,
  },
});

MongoDB

Load collections from the specified database. Use structured connection fields or supply connection, which takes precedence over them.

await ava.source({
  type: 'mongodb',
  options: {
    connection: process.env.MONGODB_URI!,
    database: 'analytics',
  },
});

Supabase

Provide your project reference and a Supabase Management API access token. Your application obtains and refreshes the token.

const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
  engine: { type: 'supabase' },
});
await ava.source({
  type: 'supabase',
  options: {
    projectRef: 'YOUR_PROJECT_REF',
    accessToken: process.env.SUPABASE_ACCESS_TOKEN!,
  },
});

ClickHouse

Provide a server endpoint and database. Use url or host; url takes precedence when both are present.

const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
  engine: { type: 'clickhouse' },
});
await ava.source({
  type: 'clickhouse',
  options: {
    url: 'http://localhost:8123',
    database: 'analytics',
    username: 'reader',
    password: process.env.CLICKHOUSE_PASSWORD,
  },
});

Connection fields

AVA requires an endpoint even though the underlying client has a localhost default.

Forwarded client fields

ClickHouseSourceOptions also accepts the following fields from @clickhouse/client. This table follows the installed client type declarations (1.23.1); these fields are owned by that dependency. AVA forwards them when creating the client.

All forwarded fields are optional. Server settings are an extensible, server-version-dependent map rather than an AVA-defined finite list. The dependency's ClickHouseSettings type and your server determine accepted keys. Tracer, agent, logger, and connection objects implement the corresponding client contracts; they are not plain AVA configuration objects.

Nested client options

Zstd compression requires Node.js 22.15 or newer in this client. Response compression may conflict with the engine's enforced read-only server settings; leave it disabled unless the server permits it.

SSH options

Nested under options.ssh for MySQL and PostgreSQL.