Choose a data source above, then use its example and parameter table below. CSV and JSON each support inline content and files.
Connect data sources
Pass one configuration object or a nonempty array of configurations to ava.source(). Each configuration describes where the data comes from and how to read it.
| Field | Type | Required | Meaning |
|---|---|---|---|
type | string | Yes | Source type. The sections below describe the supported values. |
options | Source-specific object | Yes | Reader or connection settings for that source type. |
name | string | No | Source name used to qualify table names in a batch of multiple sources. |
Each call releases the current dataset and clears its metadata before loading. A failed load leaves the instance without an active dataset. After loading, use ava.schema() to inspect the table structure. Call await ava.dispose() when finished.
Connect one source
Pass one configuration object. This example uses the default engine in the Node.js SDK.
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 }] },
});Connect multiple sources
AVA can analyze data from CSV, JSON, Parquet, Excel, text, SQLite, MySQL, PostgreSQL, MongoDB, Lark Base, Tencent Docs SmartSheet, and GitHub together.
In the Node.js SDK, use ava.source([...]) to connect multiple data sources in one call.
- Use a unique
namefor each source. - With two or more sources,
ava.schema()lists tables assourceName.tableName. A CSV source exposes one table nameddata, and an Excel workbook exposes one table per selected sheet. - A single source keeps its original table names whether passed as an object or a one-entry array.
await ava.source([
{ name: 'orders', type: 'csv-file', options: { path: './sales.csv' } },
{ name: 'workbook', type: 'excel', options: { path: './sales.xlsx' } },
]);
const schema = await ava.schema();Files
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\nBeijing,160' },
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
csv | string | Yes | Raw CSV content string |
options | CSVReadOptions | No | CSV reader options. |
CSV files
Use type: 'csv-file' with a local path or HTTP(S) URL. For a protected URL, supply request headers in options.headers.
For remote CSV, JSON, Parquet, and Excel files, a nonempty headers object restricts redirects to the same origin (scheme, hostname, and effective port), with a limit of 20 redirects. This applies to both DuckDB and Python, including custom Python executors. Cross-origin redirects fail before the next request, even when the only header is Accept or the redirect upgrades HTTP to HTTPS. Downloads without headers, or with headers: {}, retain the underlying downloader's redirect behavior. Use the final trusted URL when a protected download requires a different origin.
await ava.source({
type: 'csv-file',
options: {
path: 'https://example.com/sales.csv',
headers: { Authorization: 'Bearer YOUR_TOKEN' },
options: { header: true, delim: ';' },
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
path | string | Yes | Local file path or http(s) URL |
headers | Record<string, string> | No | HTTP headers for remote sources (e.g. Authorization) |
options | CSVReadOptions | No | CSV reader options. |
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.
| Field | Type | Required | Meaning / default |
|---|---|---|---|
header | boolean | No | First line of each file contains the column names. Default false |
names | string[] | No | Column names, as a list |
columns | Record<string, string> | No | Column names → types struct, e.g. { col1: 'INTEGER' }. Disables schema auto-detection |
types | string[] | Record<string, string> | No | Column types, by position (list) or by name (struct) |
all_varchar | boolean | No | Skip type detection and read all columns as VARCHAR. Default false |
normalize_names | boolean | No | Remove non-alphanumeric chars from column names; prefix reserved keywords with _ |
force_not_null | string[] | No | Columns that must not be matched against the NULL string |
delim | string | No | Field delimiter (up to 4 bytes). Default ',' |
quote | string | No | Quote character. Default '"' |
escape | string | No | Escape character for the quote within quoted values. Default '"' |
comment | string | No | Character used to initiate comments |
new_line | string | No | New line character(s): '\r' | '\n' | '\r\n' |
auto_detect | boolean | No | Auto detect CSV parameters. Default true |
auto_type_candidates | string[] | No | Types the sniffer considers when detecting column types, e.g. ['BIGINT', 'DATE'] |
dateformat | string | No | Date format used when parsing dates |
timestampformat | string | No | Timestamp format used when parsing timestamps |
decimal_separator | string | No | Decimal separator for numbers. Default '.' |
thousands | string | No | Thousands separator (single char, different from decimal_separator) |
nullstr | string | string[] | No | String(s) that represent a NULL value |
allow_quoted_nulls | boolean | No | Allow the conversion of quoted values to NULL. Default true |
sample_size | number | No | Number of sample lines for auto detection. Default 20480 |
buffer_size | number | No | Size of the read buffers in bytes. Default 16 * max_line_size |
files_to_sniff | number | No | Files used by the sniffer for multi-file schema detection; -1 = all. Default 10 |
max_line_size | number | No | Maximum line size in bytes. Default 2000000 |
parallel | boolean | No | Use the parallel CSV reader. Default true |
skip | number | No | Number of lines to skip at the start of each file. Default 0 |
ignore_errors | boolean | No | Ignore any parsing errors encountered. Default false |
null_padding | boolean | No | Pad short rows with NULL values on the right. Default false |
strict_mode | boolean | No | Throw an error upon encountering any issue. Default true |
store_rejects | boolean | No | Skip faulty lines and store them in the rejects table. Default false |
rejects_table | string | No | Temp table name for faulty lines. Default 'reject_errors' |
rejects_scan | string | No | Temp table name for faulty scans. Default 'reject_scans' |
rejects_limit | number | No | Upper limit on faulty lines recorded per file; 0 = no limit. Default 0 |
encoding | string | No | File encoding: 'utf-8' | 'utf-16' | 'latin-1'. Default 'utf-8' |
compression | string | No | Compression method: 'none' | 'gzip' | 'zstd'. Default auto (from file extension) |
union_by_name | boolean | No | Align columns from different files by name instead of position. Default false |
hive_partitioning | boolean | No | Interpret the path as a Hive partitioned path. Default auto-detected |
filename | boolean | No | Add the source file path to each row as a filename column. Default false |
JSON
Inline JSON
Pass an array of objects with type: 'json'.
await ava.source({
type: 'json',
options: { data: [{ city: 'Hangzhou', revenue: 120 }] },
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
data | any[] | Yes | Array of rows to load. |
options | JSONReadOptions | No | DuckDB reader parameters below. |
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 },
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
path | string | Yes | Local file path or http(s) URL |
headers | Record<string, string> | No | HTTP headers for remote sources (e.g. Authorization) |
options | JSONReadOptions | No | DuckDB reader parameters below. |
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:
| Parameter | Type | Default | Meaning |
|---|---|---|---|
auto_detect | boolean | true | Infer schema |
columns | Record<string, string> | Unset | Names → DuckDB types; selects columns |
compression | 'auto_detect' | 'none' | 'gzip' | 'zstd' | 'auto_detect' | Codec |
dateformat | string | 'iso' | Date pattern |
field_appearance_threshold | number | 0.1 | Sparse-object MAP threshold |
filename | boolean | false | Include filename in SELECT * |
format | 'auto' | 'unstructured' | 'newline_delimited' | 'array' | 'auto' | Input layout for read_json |
hive_partitioning | boolean | Auto-detected | Path partitions |
ignore_errors | boolean | false | Skip errors; NDJSON only |
map_inference_threshold | number | 200 | STRUCT subfield limit; -1 disables MAP inference |
maximum_depth | number | -1 | Inference depth; -1 unlimited |
maximum_object_size | number | 16777216 | Bytes per object |
maximum_sample_files | number | 32 | Files sampled |
records | 'auto' | 'true' | 'false' | 'auto' | Unpack objects |
sample_size | number | 20480 | Objects sampled; -1 scans all |
timestampformat | string | 'iso' | Timestamp pattern |
union_by_name | boolean | false | Merge schemas |
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' },
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
path | string | Yes | Local file path or http(s) URL |
headers | Record<string, string> | No | HTTP headers for remote sources (e.g. Authorization) |
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
| Field | Type | Required | Meaning / default |
|---|---|---|---|
path | string | Yes | Local file path or HTTP(S) URL |
headers | Record<string, string> | No | HTTP headers for remote sources, such as Authorization |
sheets | ExcelSheetOptions[] | No | Sheets to load and their individual read settings; omitted loads all sheets with header: true |
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.
| Field | Type | Default | Meaning |
|---|---|---|---|
sheet | string | Required | Exact worksheet name; also used as the table name |
range | string | Inferred by the engine | Inclusive A1 rectangle, such as B3:F100 |
header | boolean | true | Use the first row of the selected range as column names; false keeps it as data |
all_varchar | boolean | false | DuckDB only: read all cells as VARCHAR |
ignore_errors | boolean | false | DuckDB only: replace cells that fail type conversion with NULL |
stop_at_empty | boolean | false with range, otherwise true | DuckDB only: stop reading at the first empty row |
empty_as_varchar | boolean | false | DuckDB only: infer empty cells as VARCHAR instead of DOUBLE |
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.' },
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
text | string | Yes | Unstructured text to extract using the configured model. |
Databases
SQLite
Open a local SQLite database in read-only mode.
await ava.source({
type: 'sqlite',
options: { path: './analytics.sqlite' },
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
path | string | Yes | Local SQLite database file path. |
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,
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
host | string | Yes | Database hostname. |
port | number | No | Default: 3306. |
database | string | Yes | Database to expose. |
user | string | No | Database user; omitted if not supplied. |
password | string | No | Database password; omitted if not supplied. |
ssh | SSHOptions | No | Optional SSH tunnel. |
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,
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
host | string | Yes | Database hostname. |
port | number | No | Default: 5432. |
database | string | Yes | Database to expose. |
user | string | No | Database user; omitted if not supplied. |
password | string | No | Database password; omitted if not supplied. |
schema | string | No | Schema the tables live in (defaults to public) |
ssh | SSHOptions | No | Optional SSH tunnel. |
SSH options
To reach MySQL or PostgreSQL through a bastion, add ssh under options. The database host and port must be reachable from the bastion.
First, obtain the SSH server's host key fingerprint from its administrator over a trusted channel. The administrator can read it on the server with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256. Use the SHA256:... value in your connection configuration:
await ava.source({
type: 'mysql', // PostgreSQL: 'postgresql'
options: {
host: 'db.internal',
database: 'analytics',
user: 'reader',
password: process.env.DB_PASSWORD,
ssh: {
host: 'bastion.example.com',
user: 'ssh-user',
password: process.env.SSH_PASSWORD,
hostKeyFingerprint: 'SHA256:REPLACE_WITH_SERVER_FINGERPRINT',
},
},
});Fields inside options.ssh:
| Field | Type | Required | Meaning / default |
|---|---|---|---|
host | string | Yes | SSH server hostname. |
port | number | No | Default: 22. |
user | string | Yes | SSH login user. |
password | string | No | SSH login password. |
hostKeyFingerprint | string | Yes | Expected host key fingerprint, SHA256:<base64> without padding. |
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',
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
connection | string | No | Advanced connection string, e.g. host=localhost port=27017 or mongodb://user:pass@host:27017/db. Takes precedence over all structured fields when provided. |
host | string | No | MongoDB hostname or IP address (default localhost). |
port | number | No | MongoDB port number (default 27017). |
database | string | Yes | Database containing the collections to load. |
user | string | No | MongoDB username. |
password | string | No | MongoDB password. |
authSource | string | No | Authentication database (MongoDB authSource). |
srv | boolean | No | Use SRV connection format (for MongoDB Atlas). |
tls | boolean | No | Enable TLS/SSL encryption. Alias: ssl. |
ssl | boolean | No | Alias for tls. |
tlsCAFile | string | No | Path to CA certificate file for TLS. |
tlsAllowInvalidCertificates | boolean | No | Allow invalid certificates (testing only, default false). |
SQL Server
Provide a server hostname and database. Use SQL authentication.
const ava = new AVA({
llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
engine: { type: 'sqlserver' },
});
await ava.source({
type: 'sqlserver',
options: {
host: 'localhost',
database: 'analytics',
user: 'reader',
password: process.env.SQLSERVER_PASSWORD!,
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
host | string | Yes | SQL Server hostname or IP address. |
port | number | No | Default: 1433. |
database | string | Yes | Database to analyze. |
user | string | Yes | SQL-authentication login. |
password | string | Yes | Login password. |
schema | string | No | Restrict discovery to one schema; otherwise use all visible user tables and views. |
encrypt | boolean | No | Encrypt the connection; true. |
trustServerCertificate | boolean | No | Trust the server certificate without verification; false. Only enable for a trusted self-signed test server. |
connectionTimeoutMs | number | No | Connection deadline; 10000 ms. |
requestTimeoutMs | number | No | Query deadline; 30000 ms. |
Grant SELECT and VIEW DEFINITION permissions to the SQL login.
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!,
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
accessToken | string | Yes | OAuth access token from the Supabase Management API OAuth flow |
projectRef | string | Yes | Project reference (as returned by GET https://api.supabase.com/v1/projects) |
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
| Field | Type | Required | Meaning / default |
|---|---|---|---|
host | string | host or url | Host or host:port; AVA adds http:// if the scheme is absent. |
url | string | host or url | Full server URL; takes precedence over host. |
port | number | No | Overrides the endpoint's port. |
database | string | Yes | Database to discover and query. |
username | string | No | Client username; takes precedence over user. Client default: default. |
user | string | No | Alias for username. |
password | string | No | Client password; empty by default. |
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.
| Field | Type | Default / meaning |
|---|---|---|
pathname | string | Empty; extra proxy path. |
request_timeout | number | 30000 milliseconds. |
max_open_connections | number | 10 sockets per host. |
compression | Object | Request and response compression; nested fields below. |
access_token | string | Unset; ClickHouse Cloud JWT. Do not combine with username/password. |
application | string | Empty; application name. |
clickhouse_settings | ClickHouseSettings | Empty; server settings map. AVA enforces readonly: '1' on every query, overriding a conflicting setting. |
log | Object | Client logging options below. |
session_id | string | Empty; no explicit server session. |
role | string | string[] | Unset; server roles. |
http_headers | Record<string, string> | Empty; additional request headers. |
additional_headers | Record<string, string> | Deprecated client alias; use http_headers. |
keep_alive | Object | Socket reuse options below. |
json | Partial<JSONHandling> | Native JSON.parse / JSON.stringify; callbacks below. |
tracer | ClickHouseTracer | Unset; client tracing implementation. |
use_multipart_params | boolean | false; always send query parameters as multipart data. |
use_multipart_params_auto | boolean | false; use multipart when encoded parameters exceed 4096 characters. |
tls | TLS options object | Unset; certificate fields below. |
http_agent | http.Agent | https.Agent | Unset; a custom agent supersedes max_open_connections, tls, and keep_alive. Experimental client API. |
set_basic_auth_header | boolean | true; send a Basic Authorization header. Experimental. |
capture_enhanced_stack_trace | boolean | false; capture extended client stacks. Experimental. |
max_response_headers_size | number | Unset; Node.js response header byte limit applies. |
connection | Connection<Stream.Readable> | Unset; experimental client backend connection. Overrides the default HTTP transport and its options. |
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
| Field | Type | Required / default |
|---|---|---|
compression.response | boolean | { codec: 'gzip' | 'zstd' | 'br' } | Optional; false. true selects gzip. |
compression.request | boolean | RequestCompression | Optional; false. true selects gzip. |
compression.request.codec | 'gzip' | 'zstd' | 'br' | Required in the object form. |
compression.request.level | number | Optional for gzip/zstd; codec default. |
compression.request.quality | number | Optional for Brotli; default 4. |
log.LoggerClass | new () => Logger | Optional; client's default logger. |
log.level | ClickHouseLogLevel | Optional; WARN. Values: TRACE, DEBUG, INFO, WARN, ERROR, OFF. |
keep_alive.enabled | boolean | Optional; true. |
keep_alive.idle_socket_ttl | number | Optional; 2500 ms; 0 disables idle socket management. |
keep_alive.eagerly_destroy_stale_sockets | boolean | Optional; false. |
tls.ca_cert | Buffer | Required when tls is supplied. |
tls.cert | Buffer | Required for mutual TLS. |
tls.key | Buffer | Required for mutual TLS. |
json.parse | <T>(input: string) => T | Optional; parses a JSON string. |
json.stringify | <T>(input: T) => string | Optional; serializes a value. |
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.
Snowflake
Use the snowflake source and engine in Node.js to analyze tables and views on your Snowflake warehouse. Each source discovers one schema and returns query results to AVA.
Permissions
Prepare a warehouse, database and schema. The connection role needs USAGE on each, plus SELECT on the tables and views to analyze. For a shared database such as SNOWFLAKE_SAMPLE_DATA, grant IMPORTED PRIVILEGES. Keep procedure, external function and integration privileges out of this role.
The following example creates a read-only service user with key-pair authentication. Replace <public-key-body> with your public key; the connection below uses the corresponding private key file.
CREATE ROLE AVA_READER;
GRANT USAGE ON WAREHOUSE AVA_WH TO ROLE AVA_READER;
GRANT USAGE ON DATABASE ANALYTICS TO ROLE AVA_READER;
GRANT USAGE ON SCHEMA ANALYTICS.SALES TO ROLE AVA_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS.SALES TO ROLE AVA_READER;
GRANT SELECT ON ALL VIEWS IN SCHEMA ANALYTICS.SALES TO ROLE AVA_READER;
CREATE USER AVA_READER_SVC TYPE = SERVICE DEFAULT_ROLE = AVA_READER DEFAULT_WAREHOUSE = AVA_WH
RSA_PUBLIC_KEY = '<public-key-body>';
GRANT ROLE AVA_READER TO USER AVA_READER_SVC;Queries consume warehouse credits. Enable auto-suspend and a resource monitor to control usage.
Connection fields
Set both the engine and source type to snowflake, then provide your account, credentials and warehouse:
const ava = new AVA({
llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
engine: { type: 'snowflake' },
});
await ava.source({
type: 'snowflake',
options: {
account: 'myorg-myaccount',
username: 'AVA_READER_SVC',
authenticator: 'SNOWFLAKE_JWT',
privateKeyPath: '/secure/ava_reader_key.p8',
warehouse: 'AVA_WH',
role: 'AVA_READER',
database: 'ANALYTICS',
schema: 'SALES',
},
});| Field | Type | Required | Meaning / default |
|---|---|---|---|
account | string | Yes | Account identifier, orgname-accountname. |
database | string | Yes | Database to discover and query. |
schema | string | No | Schema whose tables and views are exposed; also the session's default schema. Default PUBLIC. |
warehouse | string | No | Warehouse that runs the queries; defaults to the user's DEFAULT_WAREHOUSE. |
role | string | No | Role for the session; defaults to the user's DEFAULT_ROLE. Use a read-only role. |
username | string | For most methods | Login name. |
authenticator | string | No | Driver authentication method, such as SNOWFLAKE_JWT, PROGRAMMATIC_ACCESS_TOKEN or OAUTH. Default SNOWFLAKE (password). |
privateKey | string | For SNOWFLAKE_JWT | PEM private key; or set privateKeyPath to read it from a file, and privateKeyPass for an encrypted key. |
token | string | For token methods | Programmatic access token or OAuth access token; or set tokenFilePath. |
password | string | For SNOWFLAKE | Password. Snowflake is phasing out single-factor password sign-in, so prefer key pairs or tokens. |
queryTimeoutMs | number | No | Limit for each statement in milliseconds. Snowflake enforces it (statement and queue timeouts) and the client cancels the statement when it expires. Default 30000. |
Other driver connection options, including host, proxy settings and queryTag (default AVA), are forwarded. AVA manages result formats and session cleanup. Loading fails if the database, schema or warehouse is missing or unauthorized.
Query execution
Use schema() to inspect authorized tables, views and declared keys, query() to execute Snowflake SQL, or analyze() to ask a question. analyze() sends the question and dataset metadata to your configured model to generate SQL. By default, it also sends query results to the model for a summary; pass { includeSummary: false } to skip that summary.
try {
const result = await ava.analyze('What is the total order amount for each month?');
console.log(result.data, result.text);
} finally {
await ava.dispose();
}- Write a single read-only
SELECT(WITHis allowed), quoting table and column names exactly as listed byschema(). Procedures,SYSTEM$functions, and dynamic function calls such asIDENTIFIER(name)(...)are rejected. - Use
maxRowsandmaxResultBytesto limit the number of rows and size of returned results. NUMBERvalues become JavaScript numbers when conversion preserves their digits; larger or more precise values stay decimal strings. FloatNaNand infinities stay strings. Dates useYYYY-MM-DD; times and timestamps have nine fractional digits, with an offset for time-zone types.VARIANT,OBJECTandARRAYare parsed JSON;BINARYis hexadecimal text.
Online services
Lark Base
Read records from a Base table. Set up Lark Base.
Tencent Docs SmartSheet
Read fields and records from a SmartSheet subtable. Connect Tencent Docs.
GitHub
Read issues and pull requests. Connect GitHub.