Skip to content
Browse documentation
Working with data

Data sources

Load inline data, files, database tables, and data from online services.

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.

FieldTypeRequiredMeaning
typestringYesSource type. The sections below describe the supported values.
optionsSource-specific objectYesReader or connection settings for that source type.
namestringNoSource 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.

typescript
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 name for each source.
  • With two or more sources, ava.schema() lists tables as sourceName.tableName. A CSV source exposes one table named data, 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.
typescript
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'.

typescript
await ava.source({
  type: 'csv',
  options: { csv: 'city,revenue\nHangzhou,120\nShanghai,200\nBeijing,160' },
});
FieldTypeRequiredMeaning / default
csvstringYesRaw CSV content string
optionsCSVReadOptionsNoCSV 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.

typescript
await ava.source({
  type: 'csv-file',
  options: {
    path: 'https://example.com/sales.csv',
    headers: { Authorization: 'Bearer YOUR_TOKEN' },
    options: { header: true, delim: ';' },
  },
});
FieldTypeRequiredMeaning / default
pathstringYesLocal file path or http(s) URL
headersRecord<string, string>NoHTTP headers for remote sources (e.g. Authorization)
optionsCSVReadOptionsNoCSV 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.

FieldTypeRequiredMeaning / default
headerbooleanNoFirst line of each file contains the column names. Default false
namesstring[]NoColumn names, as a list
columnsRecord<string, string>NoColumn names → types struct, e.g. { col1: 'INTEGER' }. Disables schema auto-detection
typesstring[] | Record<string, string>NoColumn types, by position (list) or by name (struct)
all_varcharbooleanNoSkip type detection and read all columns as VARCHAR. Default false
normalize_namesbooleanNoRemove non-alphanumeric chars from column names; prefix reserved keywords with _
force_not_nullstring[]NoColumns that must not be matched against the NULL string
delimstringNoField delimiter (up to 4 bytes). Default ','
quotestringNoQuote character. Default '"'
escapestringNoEscape character for the quote within quoted values. Default '"'
commentstringNoCharacter used to initiate comments
new_linestringNoNew line character(s): '\r' | '\n' | '\r\n'
auto_detectbooleanNoAuto detect CSV parameters. Default true
auto_type_candidatesstring[]NoTypes the sniffer considers when detecting column types, e.g. ['BIGINT', 'DATE']
dateformatstringNoDate format used when parsing dates
timestampformatstringNoTimestamp format used when parsing timestamps
decimal_separatorstringNoDecimal separator for numbers. Default '.'
thousandsstringNoThousands separator (single char, different from decimal_separator)
nullstrstring | string[]NoString(s) that represent a NULL value
allow_quoted_nullsbooleanNoAllow the conversion of quoted values to NULL. Default true
sample_sizenumberNoNumber of sample lines for auto detection. Default 20480
buffer_sizenumberNoSize of the read buffers in bytes. Default 16 * max_line_size
files_to_sniffnumberNoFiles used by the sniffer for multi-file schema detection; -1 = all. Default 10
max_line_sizenumberNoMaximum line size in bytes. Default 2000000
parallelbooleanNoUse the parallel CSV reader. Default true
skipnumberNoNumber of lines to skip at the start of each file. Default 0
ignore_errorsbooleanNoIgnore any parsing errors encountered. Default false
null_paddingbooleanNoPad short rows with NULL values on the right. Default false
strict_modebooleanNoThrow an error upon encountering any issue. Default true
store_rejectsbooleanNoSkip faulty lines and store them in the rejects table. Default false
rejects_tablestringNoTemp table name for faulty lines. Default 'reject_errors'
rejects_scanstringNoTemp table name for faulty scans. Default 'reject_scans'
rejects_limitnumberNoUpper limit on faulty lines recorded per file; 0 = no limit. Default 0
encodingstringNoFile encoding: 'utf-8' | 'utf-16' | 'latin-1'. Default 'utf-8'
compressionstringNoCompression method: 'none' | 'gzip' | 'zstd'. Default auto (from file extension)
union_by_namebooleanNoAlign columns from different files by name instead of position. Default false
hive_partitioningbooleanNoInterpret the path as a Hive partitioned path. Default auto-detected
filenamebooleanNoAdd the source file path to each row as a filename column. Default false

JSON

Inline JSON

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

typescript
await ava.source({
  type: 'json',
  options: { data: [{ city: 'Hangzhou', revenue: 120 }] },
});
FieldTypeRequiredMeaning / default
dataany[]YesArray of rows to load.
optionsJSONReadOptionsNoDuckDB reader parameters below.

JSON files

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

typescript
await ava.source({
  type: 'json-file',
  options: {
    path: './sales.json',
    options: { columns: { city: 'VARCHAR', revenue: 'DOUBLE' }, sample_size: -1 },
  },
});
FieldTypeRequiredMeaning / default
pathstringYesLocal file path or http(s) URL
headersRecord<string, string>NoHTTP headers for remote sources (e.g. Authorization)
optionsJSONReadOptionsNoDuckDB 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:

ParameterTypeDefaultMeaning
auto_detectbooleantrueInfer schema
columnsRecord<string, string>UnsetNames → DuckDB types; selects columns
compression'auto_detect' | 'none' | 'gzip' | 'zstd''auto_detect'Codec
dateformatstring'iso'Date pattern
field_appearance_thresholdnumber0.1Sparse-object MAP threshold
filenamebooleanfalseInclude filename in SELECT *
format'auto' | 'unstructured' | 'newline_delimited' | 'array''auto'Input layout for read_json
hive_partitioningbooleanAuto-detectedPath partitions
ignore_errorsbooleanfalseSkip errors; NDJSON only
map_inference_thresholdnumber200STRUCT subfield limit; -1 disables MAP inference
maximum_depthnumber-1Inference depth; -1 unlimited
maximum_object_sizenumber16777216Bytes per object
maximum_sample_filesnumber32Files sampled
records'auto' | 'true' | 'false''auto'Unpack objects
sample_sizenumber20480Objects sampled; -1 scans all
timestampformatstring'iso'Timestamp pattern
union_by_namebooleanfalseMerge 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.

typescript
await ava.source({
  type: 'parquet',
  options: { path: './sales.parquet' },
});
FieldTypeRequiredMeaning / default
pathstringYesLocal file path or http(s) URL
headersRecord<string, string>NoHTTP 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.

typescript
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

FieldTypeRequiredMeaning / default
pathstringYesLocal file path or HTTP(S) URL
headersRecord<string, string>NoHTTP headers for remote sources, such as Authorization
sheetsExcelSheetOptions[]NoSheets 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.

FieldTypeDefaultMeaning
sheetstringRequiredExact worksheet name; also used as the table name
rangestringInferred by the engineInclusive A1 rectangle, such as B3:F100
headerbooleantrueUse the first row of the selected range as column names; false keeps it as data
all_varcharbooleanfalseDuckDB only: read all cells as VARCHAR
ignore_errorsbooleanfalseDuckDB only: replace cells that fail type conversion with NULL
stop_at_emptybooleanfalse with range, otherwise trueDuckDB only: stop reading at the first empty row
empty_as_varcharbooleanfalseDuckDB 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:

typescript
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 &amp; 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.

typescript
await ava.source({
  type: 'text',
  options: { text: 'Hangzhou revenue was 120. Shanghai revenue was 200.' },
});
FieldTypeRequiredMeaning / default
textstringYesUnstructured text to extract using the configured model.

Databases

SQLite

Open a local SQLite database in read-only mode.

typescript
await ava.source({
  type: 'sqlite',
  options: { path: './analytics.sqlite' },
});
FieldTypeRequiredMeaning / default
pathstringYesLocal SQLite database file path.

MySQL

Connect to a database and discover its tables.

typescript
await ava.source({
  type: 'mysql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.MYSQL_PASSWORD,
  },
});
FieldTypeRequiredMeaning / default
hoststringYesDatabase hostname.
portnumberNoDefault: 3306.
databasestringYesDatabase to expose.
userstringNoDatabase user; omitted if not supplied.
passwordstringNoDatabase password; omitted if not supplied.
sshSSHOptionsNoOptional SSH tunnel.

PostgreSQL

Connect to a database and discover its tables.

typescript
await ava.source({
  type: 'postgresql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.POSTGRES_PASSWORD,
  },
});
FieldTypeRequiredMeaning / default
hoststringYesDatabase hostname.
portnumberNoDefault: 5432.
databasestringYesDatabase to expose.
userstringNoDatabase user; omitted if not supplied.
passwordstringNoDatabase password; omitted if not supplied.
schemastringNoSchema the tables live in (defaults to public)
sshSSHOptionsNoOptional 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:

typescript
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:

FieldTypeRequiredMeaning / default
hoststringYesSSH server hostname.
portnumberNoDefault: 22.
userstringYesSSH login user.
passwordstringNoSSH login password.
hostKeyFingerprintstringYesExpected 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.

typescript
await ava.source({
  type: 'mongodb',
  options: {
    connection: process.env.MONGODB_URI!,
    database: 'analytics',
  },
});
FieldTypeRequiredMeaning / default
connectionstringNoAdvanced connection string, e.g. host=localhost port=27017 or mongodb://user:pass@host:27017/db. Takes precedence over all structured fields when provided.
hoststringNoMongoDB hostname or IP address (default localhost).
portnumberNoMongoDB port number (default 27017).
databasestringYesDatabase containing the collections to load.
userstringNoMongoDB username.
passwordstringNoMongoDB password.
authSourcestringNoAuthentication database (MongoDB authSource).
srvbooleanNoUse SRV connection format (for MongoDB Atlas).
tlsbooleanNoEnable TLS/SSL encryption. Alias: ssl.
sslbooleanNoAlias for tls.
tlsCAFilestringNoPath to CA certificate file for TLS.
tlsAllowInvalidCertificatesbooleanNoAllow invalid certificates (testing only, default false).

SQL Server

Provide a server hostname and database. Use SQL authentication.

typescript
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!,
  },
});
FieldTypeRequiredMeaning / default
hoststringYesSQL Server hostname or IP address.
portnumberNoDefault: 1433.
databasestringYesDatabase to analyze.
userstringYesSQL-authentication login.
passwordstringYesLogin password.
schemastringNoRestrict discovery to one schema; otherwise use all visible user tables and views.
encryptbooleanNoEncrypt the connection; true.
trustServerCertificatebooleanNoTrust the server certificate without verification; false. Only enable for a trusted self-signed test server.
connectionTimeoutMsnumberNoConnection deadline; 10000 ms.
requestTimeoutMsnumberNoQuery 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.

typescript
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!,
  },
});
FieldTypeRequiredMeaning / default
accessTokenstringYesOAuth access token from the Supabase Management API OAuth flow
projectRefstringYesProject 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.

typescript
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

FieldTypeRequiredMeaning / default
hoststringhost or urlHost or host:port; AVA adds http:// if the scheme is absent.
urlstringhost or urlFull server URL; takes precedence over host.
portnumberNoOverrides the endpoint's port.
databasestringYesDatabase to discover and query.
usernamestringNoClient username; takes precedence over user. Client default: default.
userstringNoAlias for username.
passwordstringNoClient 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.

FieldTypeDefault / meaning
pathnamestringEmpty; extra proxy path.
request_timeoutnumber30000 milliseconds.
max_open_connectionsnumber10 sockets per host.
compressionObjectRequest and response compression; nested fields below.
access_tokenstringUnset; ClickHouse Cloud JWT. Do not combine with username/password.
applicationstringEmpty; application name.
clickhouse_settingsClickHouseSettingsEmpty; server settings map. AVA enforces readonly: '1' on every query, overriding a conflicting setting.
logObjectClient logging options below.
session_idstringEmpty; no explicit server session.
rolestring | string[]Unset; server roles.
http_headersRecord<string, string>Empty; additional request headers.
additional_headersRecord<string, string>Deprecated client alias; use http_headers.
keep_aliveObjectSocket reuse options below.
jsonPartial<JSONHandling>Native JSON.parse / JSON.stringify; callbacks below.
tracerClickHouseTracerUnset; client tracing implementation.
use_multipart_paramsbooleanfalse; always send query parameters as multipart data.
use_multipart_params_autobooleanfalse; use multipart when encoded parameters exceed 4096 characters.
tlsTLS options objectUnset; certificate fields below.
http_agenthttp.Agent | https.AgentUnset; a custom agent supersedes max_open_connections, tls, and keep_alive. Experimental client API.
set_basic_auth_headerbooleantrue; send a Basic Authorization header. Experimental.
capture_enhanced_stack_tracebooleanfalse; capture extended client stacks. Experimental.
max_response_headers_sizenumberUnset; Node.js response header byte limit applies.
connectionConnection<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

FieldTypeRequired / default
compression.responseboolean | { codec: 'gzip' | 'zstd' | 'br' }Optional; false. true selects gzip.
compression.requestboolean | RequestCompressionOptional; false. true selects gzip.
compression.request.codec'gzip' | 'zstd' | 'br'Required in the object form.
compression.request.levelnumberOptional for gzip/zstd; codec default.
compression.request.qualitynumberOptional for Brotli; default 4.
log.LoggerClassnew () => LoggerOptional; client's default logger.
log.levelClickHouseLogLevelOptional; WARN. Values: TRACE, DEBUG, INFO, WARN, ERROR, OFF.
keep_alive.enabledbooleanOptional; true.
keep_alive.idle_socket_ttlnumberOptional; 2500 ms; 0 disables idle socket management.
keep_alive.eagerly_destroy_stale_socketsbooleanOptional; false.
tls.ca_certBufferRequired when tls is supplied.
tls.certBufferRequired for mutual TLS.
tls.keyBufferRequired for mutual TLS.
json.parse<T>(input: string) => TOptional; parses a JSON string.
json.stringify<T>(input: T) => stringOptional; 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.

sql
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:

typescript
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',
  },
});
FieldTypeRequiredMeaning / default
accountstringYesAccount identifier, orgname-accountname.
databasestringYesDatabase to discover and query.
schemastringNoSchema whose tables and views are exposed; also the session's default schema. Default PUBLIC.
warehousestringNoWarehouse that runs the queries; defaults to the user's DEFAULT_WAREHOUSE.
rolestringNoRole for the session; defaults to the user's DEFAULT_ROLE. Use a read-only role.
usernamestringFor most methodsLogin name.
authenticatorstringNoDriver authentication method, such as SNOWFLAKE_JWT, PROGRAMMATIC_ACCESS_TOKEN or OAUTH. Default SNOWFLAKE (password).
privateKeystringFor SNOWFLAKE_JWTPEM private key; or set privateKeyPath to read it from a file, and privateKeyPass for an encrypted key.
tokenstringFor token methodsProgrammatic access token or OAuth access token; or set tokenFilePath.
passwordstringFor SNOWFLAKEPassword. Snowflake is phasing out single-factor password sign-in, so prefer key pairs or tokens.
queryTimeoutMsnumberNoLimit 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.

typescript
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 (WITH is allowed), quoting table and column names exactly as listed by schema(). Procedures, SYSTEM$ functions, and dynamic function calls such as IDENTIFIER(name)(...) are rejected.
  • Use maxRows and maxResultBytes to limit the number of rows and size of returned results.
  • NUMBER values become JavaScript numbers when conversion preserves their digits; larger or more precise values stay decimal strings. Float NaN and infinities stay strings. Dates use YYYY-MM-DD; times and timestamps have nine fractional digits, with an offset for time-zone types. VARIANT, OBJECT and ARRAY are parsed JSON; BINARY is 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.