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(config) with the data location and reader settings:

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 and prepares the data for execution. Schema discovery is deferred until schema() or another operation needs it. Calling source() again replaces the current source and clears its cached metadata. Use schema() to inspect 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',
    options: { columns: { city: 'VARCHAR', revenue: 'DOUBLE' }, sample_size: -1 },
  },
});

JSON reader options

Both JSON source types accept options.options when using the DuckDB engine. All fields are optional. The complete DuckDB JSON reader parameter list is exposed as JSONReadOptions:

Inline data is serialized as an uncompressed JSON array; choose compatible reader options. Remote files are downloaded to temporary paths, so set compression explicitly for compressed URLs.

Parquet

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

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

Excel

Read an .xlsx workbook from a local path or HTTP(S) URL. Each selected worksheet becomes a separate table named after the sheet. Call schema() to inspect the resulting tables and columns.

await ava.source({
  type: 'excel',
  options: {
    path: './sales.xlsx',
    sheets: [
      { sheet: 'Sales', range: 'A3:F100', header: true },
      { sheet: 'Costs', range: 'B2:C50', header: false },
    ],
  },
});

Source options

Sheet selection and reader options

Each entry in sheets contains a required sheet and optional ExcelReadOptions fields. Set these fields directly on the sheet entry, as shown above.

A supplied sheets list must be non-empty, and every name must exist in the workbook and appear only once. Ranges must be valid, bounded A1 rectangles. Invalid selections and unsupported fields are rejected.

Engine behavior

Both engines support sheet, range, and header. The Python engine rejects the four DuckDB-only options in the table above.

DuckDB reader options follow read_xlsx, except that AVA defaults header to true instead of inferring it. For example, to preserve mixed cell types as text and continue past empty rows:

await ava.source({
  type: 'excel',
  options: {
    path: './sales.xlsx',
    sheets: [{ sheet: 'Sales', all_varchar: true, stop_at_empty: false }],
  },
});

DuckDB rejects workbooks containing sheet names with literal XML entity text, such as Sales & Tax, because its Excel extension can confuse them with another sheet. Rename those sheets or use the Python engine. Ordinary ampersands, quotes, and Unicode names are supported.

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',
  },
});

Feishu Bitable

Use type: 'feishu-bitable' with the DuckDB engine in Node.js. Rows are exposed as one read-only view named data.

await ava.source({
  type: 'feishu-bitable',
  options: {
    url: 'https://my.feishu.cn/base/APP_TOKEN?table=TABLE_ID',
    appId: process.env.AVA_FEISHU_APP_ID,
    appSecret: process.env.AVA_FEISHU_APP_SECRET,
  },
});

Provide url, or both appToken and tableId, along with appId and appSecret. The CLI also reads credentials from AVA_FEISHU_APP_ID / AVA_FEISHU_APP_SECRET or ~/.ava/feishu.json.

Both /base/ and wiki-hosted /wiki/ links are supported. Wiki links require wiki read access and wiki space membership so the app can resolve the Bitable. The view query parameter is ignored. Complex cells (people, attachments, links, formulas, locations, and groups) are flattened to comma-separated text.

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.