跳至正文
浏览文档
理解与接入数据

接入数据

连接内存数据、文件、数据库和在线服务。

在上方找到你的数据类型,再参照对应示例,填入自己的路径或连接信息。CSV 和 JSON 既可以读文件,也可以直接传入内容。

接入数据源

调用 ava.source() 时,可以传入一份数据源配置,也可以传入非空的配置数组。每份配置描述数据来自哪里以及如何读取。

字段类型必填含义
typestring是数据源类型,支持的取值见下方各章节。
options数据源对应的对象是对应数据源的读取或连接设置。
namestring否接入多个数据源时,用作表名的前缀。

每次调用都会先释放当前数据集并清空元数据,再加载新数据。加载失败后,实例没有活动数据集。加载成功后,用 ava.schema() 查看表结构,使用完毕后调用 await ava.dispose() 释放资源。

接入单个数据源

传入一个配置对象。以下代码使用 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 }] },
});

接入多个数据源

AVA 支持同时分析来自 CSV、JSON、Parquet、Excel、文本、SQLite、MySQL、PostgreSQL、MongoDB、飞书多维表格、腾讯文档智能表格和 GitHub 的数据。

在 Node.js SDK 中,使用 ava.source([...]) 一次接入多个数据源。

  • 为每个数据源设置唯一的 name。
  • 接入两个或更多数据源时,ava.schema() 按 源名.表名 列出表。CSV 提供一张名为 data 的表,Excel 工作簿中的每张选定工作表各对应一张表。
  • 只接入一个数据源时,配置对象和单元素数组都沿用原表名。
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();

文件

CSV

直接传入 CSV

设置 type: 'csv',以字符串传入 CSV 内容。

typescript
await ava.source({
  type: 'csv',
  options: { csv: 'city,revenue\nHangzhou,120\nShanghai,200\nBeijing,160' },
});
字段类型必填含义与默认值
csvstring是原始 CSV 字符串。
optionsCSVReadOptions否CSV 读取选项。

读取 CSV 文件

设置 type: 'csv-file',传入本地路径或 HTTP(S) URL。URL 需要鉴权时,可在 options.headers 中提供请求头。

远程 CSV、JSON、Parquet 和 Excel 文件只要传入非空 headers,就仅允许同来源跳转(协议、主机名和有效端口均相同),最多跳转 20 次。此规则同时适用于 DuckDB 和 Python,包括自定义 Python 执行器。跨来源跳转会在发送下一次请求前报错,即使请求头只有 Accept,或跳转是从 HTTP 升级到 HTTPS。未传请求头或传入 headers: {} 时,保留底层下载器原有的跳转行为。需要从其他来源下载受保护文件时,请直接使用已确认可信的最终地址。

typescript
await ava.source({
  type: 'csv-file',
  options: {
    path: 'https://example.com/sales.csv',
    headers: { Authorization: 'Bearer YOUR_TOKEN' },
    options: { header: true, delim: ';' },
  },
});
字段类型必填含义与默认值
pathstring是本地文件路径或 HTTP(S) URL。
headersRecord<string, string>否远程数据源的 HTTP 请求头,例如 Authorization。
optionsCSVReadOptions否CSV 读取选项。

CSV 读取选项

DuckDB 引擎的 csv、csv-file 数据源可在 options.options 中使用以下字段,全部可选。AVA 将显式提供的值转发给 read_csv;省略时使用 DuckDB 的默认值或自动检测结果。下表说明各读取选项自身的默认值,实际表头、分隔符和类型也可能由自动检测确定。

字段类型必填含义与默认值
headerboolean否文件首行是否包含列名,默认 false。
namesstring[]否列名列表。
columnsRecord<string, string>否列名到类型的映射,例如 { col1: 'INTEGER' };设置后关闭结构自动检测。
typesstring[] | Record<string, string>否按位置提供类型列表,或按列名提供类型映射。
all_varcharboolean否跳过类型检测,将所有列读为 VARCHAR,默认 false。
normalize_namesboolean否移除列名中的非字母数字字符,并为保留字添加下划线前缀。
force_not_nullstring[]否不参与 NULL 字符串匹配的列。
delimstring否字段分隔符,最多 4 字节,默认 ','。
quotestring否引号字符,默认 '"'。
escapestring否引号包裹的字段内,用于转义引号的字符,默认 '"'。
commentstring否注释起始字符。
new_linestring否换行符:'\r'、'\n' 或 '\r\n'。
auto_detectboolean否自动检测 CSV 参数,默认 true。
auto_type_candidatesstring[]否检测列类型时考虑的候选类型,例如 ['BIGINT', 'DATE']。
dateformatstring否解析日期使用的格式。
timestampformatstring否解析时间戳使用的格式。
decimal_separatorstring否数字的小数分隔符,默认 '.'。
thousandsstring否千位分隔符,须为单个字符,且与 decimal_separator 不同。
nullstrstring | string[]否代表 NULL 的一个或多个字符串。
allow_quoted_nullsboolean否允许将引号包裹的值转换成 NULL,默认 true。
sample_sizenumber否自动检测时采样的行数,默认 20480。
buffer_sizenumber否读取缓冲区大小,单位字节,默认 16 * max_line_size。
files_to_sniffnumber否多文件结构检测时采样的文件数;-1 表示全部,默认 10。
max_line_sizenumber否单行大小上限,单位字节,默认 2000000。
parallelboolean否使用并行 CSV 读取器,默认 true。
skipnumber否跳过每个文件开头的行数,默认 0。
ignore_errorsboolean否忽略解析错误,默认 false。
null_paddingboolean否对较短的行在右侧补 NULL,默认 false。
strict_modeboolean否遇到任何问题即抛错,默认 true。
store_rejectsboolean否跳过出错行并保存到拒绝记录表,默认 false。
rejects_tablestring否保存出错行的临时表名,默认 'reject_errors'。
rejects_scanstring否保存出错扫描的临时表名,默认 'reject_scans'。
rejects_limitnumber否每个文件记录的出错行数上限;0 表示不限制,默认 0。
encodingstring否文件编码,可选 'utf-8'、'utf-16'、'latin-1',默认 'utf-8'。
compressionstring否压缩方式,可选 'none'、'gzip'、'zstd',默认根据扩展名检测。
union_by_nameboolean否多个文件按列名而非列位置对齐,默认 false。
hive_partitioningboolean否将路径解释为 Hive 分区路径,默认自动检测。
filenameboolean否为每行添加保存来源文件路径的 filename 列,默认 false。

JSON

直接传入 JSON

设置 type: 'json',传入对象数组。

typescript
await ava.source({
  type: 'json',
  options: { data: [{ city: 'Hangzhou', revenue: 120 }] },
});
字段类型必填含义与默认值
dataany[]是待加载的数据行数组。
optionsJSONReadOptions否下方的 DuckDB 读取参数。

读取 JSON 文件

设置 type: 'json-file',传入本地路径或 HTTP(S) URL。

typescript
await ava.source({
  type: 'json-file',
  options: {
    path: './sales.json',
    options: { columns: { city: 'VARCHAR', revenue: 'DOUBLE' }, sample_size: -1 },
  },
});
字段类型必填含义与默认值
pathstring是本地文件路径或 HTTP(S) URL。
headersRecord<string, string>否远程数据源的 HTTP 请求头,例如 Authorization。
optionsJSONReadOptions否下方的 DuckDB 读取参数。

JSON 读取选项

使用 DuckDB 时,两种 JSON 数据源均接受 options.options,所有字段可选。 JSONReadOptions 暴露完整的 DuckDB JSON 读取参数:

参数类型默认值含义
auto_detectbooleantrue推断数据结构。
columnsRecord<string, string>未设置列名到 DuckDB 类型的映射,同时用于选择列。
compression'auto_detect' | 'none' | 'gzip' | 'zstd''auto_detect'压缩编解码方式。
dateformatstring'iso'日期格式。
field_appearance_thresholdnumber0.1稀疏对象推断为 MAP 的阈值。
filenamebooleanfalse在 SELECT * 中包含文件名。
format'auto' | 'unstructured' | 'newline_delimited' | 'array''auto'read_json 的输入组织形式。
hive_partitioningboolean自动检测根据路径识别分区。
ignore_errorsbooleanfalse跳过错误,仅适用于 NDJSON。
map_inference_thresholdnumber200STRUCT 子字段数量阈值;-1 关闭 MAP 推断。
maximum_depthnumber-1结构推断深度;-1 表示不限。
maximum_object_sizenumber16777216单个对象的字节上限。
maximum_sample_filesnumber32采样文件数量。
records'auto' | 'true' | 'false''auto'是否展开对象。
sample_sizenumber20480采样对象数量;-1 扫描全部。
timestampformatstring'iso'时间戳格式。
union_by_namebooleanfalse合并数据结构。

内存数据会序列化为未压缩的 JSON 数组,请选择与此兼容的读取选项。 远程文件会下载到临时路径,读取压缩 URL 时应显式设置 compression。

Parquet

从本地路径或 HTTP(S) URL 读取 Parquet 文件。

typescript
await ava.source({
  type: 'parquet',
  options: { path: './sales.parquet' },
});
字段类型必填含义与默认值
pathstring是本地文件路径或 HTTP(S) URL。
headersRecord<string, string>否远程数据源的 HTTP 请求头,例如 Authorization。

Excel

从本地路径或 HTTP(S) URL 读取 .xlsx 工作簿。每个被选中的工作表会成为一张独立的表,以工作表名称命名。调用 schema() 可查看生成的表与列。

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

数据源选项

字段类型必填含义与默认值
pathstring是本地文件路径或 HTTP(S) URL。
headersRecord<string, string>否远程数据源的 HTTP 请求头,例如 Authorization。
sheetsExcelSheetOptions[]否要加载的工作表及各自的读取设置;省略时加载全部工作表,并使用 header: true。

工作表选择与读取选项

sheets 中的每一项都包含必填的 sheet,以及可选的 ExcelReadOptions 字段。读取选项直接放在工作表项上,写法如上例所示。

字段类型默认值含义
sheetstring必填精确的工作表名称,同时作为表名。
rangestring由引擎推断包含首尾边界的 A1 矩形范围,例如 B3:F100。
headerbooleantrue将所选范围的第一行作为列名;设为 false 时保留为数据。
all_varcharbooleanfalse仅 DuckDB:将所有单元格读为 VARCHAR。
ignore_errorsbooleanfalse仅 DuckDB:类型转换失败的单元格改为 NULL。
stop_at_emptyboolean有 range 时为 false,否则为 true仅 DuckDB:遇到第一个空行时停止读取。
empty_as_varcharbooleanfalse仅 DuckDB:将空单元格推断为 VARCHAR,而非 DOUBLE。

提供 sheets 时,列表不能为空;每个工作表名必须存在且只能出现一次。范围必须是有效、有界的 A1 矩形。无效选择及不受支持的字段会被拒绝。

引擎行为

两种引擎都支持 sheet、range 和 header。Python 引擎会拒绝上表中的四个 DuckDB 专用选项。

DuckDB 的读取选项遵循 read_xlsx,但 AVA 默认 header 为 true,而非自动推断。例如,要将混合类型单元格保留为文本,并继续读取空行之后的数据:

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

DuckDB 会拒绝含有字面 XML 实体文本工作表名的工作簿,例如 Sales &amp; Tax,因为 Excel 扩展可能将它与另一张表混淆。请重命名这些工作表,或使用 Python 引擎。普通的 &、引号和 Unicode 名称均受支持。

文本

从非结构化文本中提取数据行。这种数据源会调用已配置的模型。

typescript
await ava.source({
  type: 'text',
  options: { text: 'Hangzhou revenue was 120. Shanghai revenue was 200.' },
});
字段类型必填含义与默认值
textstring是使用已配置模型提取的非结构化文本。

数据库

SQLite

以只读模式打开本地 SQLite 数据库。

typescript
await ava.source({
  type: 'sqlite',
  options: { path: './analytics.sqlite' },
});
字段类型必填含义与默认值
pathstring是本地 SQLite 数据库文件路径。

MySQL

连接数据库并发现其中的表。

typescript
await ava.source({
  type: 'mysql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.MYSQL_PASSWORD,
  },
});
字段类型必填含义与默认值
hoststring是数据库主机名。
portnumber否默认 3306。
databasestring是要暴露的数据库。
userstring否数据库用户,不提供则省略。
passwordstring否数据库密码,不提供则省略。
sshSSHOptions否可选的 SSH 隧道。

PostgreSQL

连接数据库并发现其中的表。

typescript
await ava.source({
  type: 'postgresql',
  options: {
    host: 'localhost',
    database: 'analytics',
    user: 'reader',
    password: process.env.POSTGRES_PASSWORD,
  },
});
字段类型必填含义与默认值
hoststring是数据库主机名。
portnumber否默认 5432。
databasestring是要暴露的数据库。
userstring否数据库用户,不提供则省略。
passwordstring否数据库密码,不提供则省略。
schemastring否表所属的数据库 schema,默认 public。
sshSSHOptions否可选的 SSH 隧道。

SSH 选项

通过跳板机访问 MySQL 或 PostgreSQL 时,在 options 中添加 ssh。数据库的 host 和 port 应填写跳板机能够访问的地址与端口。

先通过可信渠道向 SSH 服务器管理员获取主机密钥指纹。管理员可在服务器上运行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256,将输出中的 SHA256:... 值填入连接配置:

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

options.ssh 中的字段:

字段类型必填含义与默认值
hoststring是SSH 服务器主机名。
portnumber否默认 22。
userstring是SSH 登录用户。
passwordstring否SSH 登录密码。
hostKeyFingerprintstring是预期的主机密钥指纹,格式为 SHA256:<base64>,不带填充字符。

MongoDB

加载指定数据库中的集合。可以使用结构化连接字段,也可以提供优先级更高的 connection。

typescript
await ava.source({
  type: 'mongodb',
  options: {
    connection: process.env.MONGODB_URI!,
    database: 'analytics',
  },
});
字段类型必填含义与默认值
connectionstring否高级连接字符串,例如 host=localhost port=27017 或 mongodb://user:pass@host:27017/db;提供后优先于所有结构化字段。
hoststring否MongoDB 主机名或 IP 地址,默认 localhost。
portnumber否MongoDB 端口号,默认 27017。
databasestring是包含待加载集合的数据库。
userstring否MongoDB 用户名。
passwordstring否MongoDB 密码。
authSourcestring否鉴权数据库,对应 MongoDB 的 authSource。
srvboolean否使用 SRV 连接格式,适用于 MongoDB Atlas。
tlsboolean否启用 TLS/SSL 加密,别名为 ssl。
sslboolean否tls 的别名。
tlsCAFilestring否TLS 的 CA 证书文件路径。
tlsAllowInvalidCertificatesboolean否允许无效证书,仅用于测试,默认 false。

Supabase

提供项目标识与 Supabase Management API 访问令牌;应用负责获取和刷新令牌。

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!,
  },
});
字段类型必填含义与默认值
accessTokenstring是Supabase Management API OAuth 流程返回的 OAuth 访问令牌。
projectRefstring是项目标识,可从 GET https://api.supabase.com/v1/projects 的结果中获取。

ClickHouse

提供服务端点和数据库。使用 url 或 host;同时存在时 url 优先。

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

连接字段

字段类型必填含义与默认值
hoststringhost 或 url主机名或 host:port;没有协议时,AVA 自动补上 http://。
urlstringhost 或 url完整的服务 URL,优先于 host。
portnumber否覆盖端点中的端口号。
databasestring是要发现结构和执行查询的数据库。
usernamestring否客户端用户名,优先于 user;客户端默认值为 default。
userstring否username 的别名。
passwordstring否客户端密码,默认空字符串。

虽然底层客户端默认可连接 localhost,AVA 仍要求显式提供端点。

透传的客户端字段

ClickHouseSourceOptions 也接受以下 @clickhouse/client 字段。下表基于已安装客户端的类型声明(1.23.1);这些字段由该依赖定义,AVA 会在创建客户端时透传。

字段类型默认值与含义
pathnamestring默认为空,用于指定额外的代理路径。
request_timeoutnumber默认 30000 毫秒。
max_open_connectionsnumber每个主机默认最多 10 个 socket 连接。
compression对象请求和响应压缩,嵌套字段见下方。
access_tokenstring默认未设置,用于 ClickHouse Cloud JWT;不可与用户名、密码同时使用。
applicationstring默认为空,应用名称。
clickhouse_settingsClickHouseSettings默认为空,服务端设置映射。AVA 每次查询都会强制 readonly: '1',覆盖冲突设置。
log对象客户端日志选项,见下方。
session_idstring默认为空,不显式指定服务端会话。
rolestring | string[]默认未设置,服务端角色。
http_headersRecord<string, string>默认为空,额外的 HTTP 请求头。
additional_headersRecord<string, string>已废弃的客户端别名,请使用 http_headers。
keep_alive对象Socket 复用选项,见下方。
jsonPartial<JSONHandling>默认使用原生 JSON.parse / JSON.stringify;回调见下方。
tracerClickHouseTracer默认未设置,客户端追踪实现。
use_multipart_paramsboolean默认 false,始终以 multipart 发送查询参数。
use_multipart_params_autoboolean默认 false,编码后的参数超过 4096 个字符时使用 multipart。
tlsTLS 选项对象默认未设置,证书字段见下方。
http_agenthttp.Agent | https.Agent默认未设置。自定义 agent 会取代 max_open_connections、tls 和 keep_alive;这是实验性客户端 API。
set_basic_auth_headerboolean默认 true,发送 Basic Authorization 请求头;实验性选项。
capture_enhanced_stack_traceboolean默认 false,记录扩展客户端调用栈;实验性选项。
max_response_headers_sizenumber默认未设置,使用 Node.js 的响应头字节上限。
connectionConnection<Stream.Readable>默认未设置,实验性的客户端后端连接;会覆盖默认 HTTP 传输及其选项。

透传字段全部可选。服务端设置是可扩展、与服务端版本有关的映射,并非 AVA 固定定义的字段清单;可用键由依赖的 ClickHouseSettings 类型和实际服务端共同决定。Tracer、agent、logger 与 connection 对象需要实现相应的客户端接口,并非普通的 AVA 配置对象。

嵌套客户端选项

字段类型必填与默认值
compression.responseboolean | { codec: 'gzip' | 'zstd' | 'br' }可选,默认 false;true 表示使用 gzip。
compression.requestboolean | RequestCompression可选,默认 false;true 表示使用 gzip。
compression.request.codec'gzip' | 'zstd' | 'br'使用对象形式时必填。
compression.request.levelnumbergzip / zstd 可选,默认使用编解码器的级别。
compression.request.qualitynumberBrotli 可选,默认 4。
log.LoggerClassnew () => Logger可选,默认使用客户端的 logger。
log.levelClickHouseLogLevel可选,默认 WARN;可选值为 TRACE、DEBUG、INFO、WARN、ERROR、OFF。
keep_alive.enabledboolean可选,默认 true。
keep_alive.idle_socket_ttlnumber可选,默认 2500 毫秒;0 表示禁用闲置 socket 管理。
keep_alive.eagerly_destroy_stale_socketsboolean可选,默认 false。
tls.ca_certBuffer提供 tls 时必填。
tls.certBuffer双向 TLS 时必填。
tls.keyBuffer双向 TLS 时必填。
json.parse<T>(input: string) => T可选,用于解析 JSON 字符串。
json.stringify<T>(input: T) => string可选,用于序列化值。

此客户端的 Zstd 压缩需要 Node.js 22.15 或更高版本。响应压缩可能与引擎强制的服务端只读设置冲突;除非服务端允许,否则请保持关闭。

Snowflake

在 Node.js 中使用 snowflake 数据源和引擎,分析 Snowflake 仓库中的表和视图。每个数据源对应一个 schema,查询结果返回 AVA。

权限

准备好仓库、数据库和 schema。连接角色需要三者的 USAGE 权限,以及待分析表和视图的 SELECT 权限。SNOWFLAKE_SAMPLE_DATA 这类共享数据库需要授予 IMPORTED PRIVILEGES。请勿向该角色授予存储过程、外部函数或集成的使用权限。

以下示例创建使用密钥对认证的只读服务用户。将 <public-key-body> 替换为公钥正文,下方连接配置使用对应的私钥文件。

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;

查询会消耗仓库 credits,请开启自动挂起并配置资源监控来控制用量。

连接字段

将引擎和数据源类型均设为 snowflake,填入账号、凭证和仓库信息:

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',
  },
});
字段类型必填含义与默认值
accountstring是账号标识,格式为 orgname-accountname。
databasestring是要发现和查询的数据库。
schemastring否暴露其中表和视图的 schema,也是会话的默认 schema。默认 PUBLIC。
warehousestring否执行查询的仓库,默认使用用户的 DEFAULT_WAREHOUSE。
rolestring否会话使用的角色,默认使用用户的 DEFAULT_ROLE。请使用只读角色。
usernamestring多数认证方式必填登录名。
authenticatorstring否驱动的认证方式,如 SNOWFLAKE_JWT、PROGRAMMATIC_ACCESS_TOKEN 或 OAUTH。默认 SNOWFLAKE(密码)。
privateKeystringSNOWFLAKE_JWT 时必填PEM 格式私钥;也可用 privateKeyPath 从文件读取,加密的私钥用 privateKeyPass 提供口令。
tokenstring令牌类认证时必填Programmatic access token 或 OAuth 访问令牌;也可用 tokenFilePath 从文件读取。
passwordstringSNOWFLAKE 时必填密码。Snowflake 正在逐步停用单因素密码登录,建议使用密钥对或令牌。
queryTimeoutMsnumber否单条语句的时限(毫秒)。由 Snowflake 执行(语句超时和排队超时),到期时客户端也会取消语句。默认 30000。

其他驱动连接选项,如 host、代理设置和 queryTag(默认 AVA),会透传给驱动。结果格式和会话清理由 AVA 管理。数据库、schema 或仓库不存在或未授权时,加载会报错。

查询执行

用 schema() 查看已授权的表、视图和声明的键,用 query() 执行 Snowflake SQL,或用 analyze() 以自然语言提问。analyze() 会将问题和数据集元数据发送给配置的模型来生成 SQL;默认还会将查询结果发送给模型生成摘要,传入 { includeSummary: false } 可跳过摘要。

typescript
try {
  const result = await ava.analyze('每个月的订单总金额是多少?');
  console.log(result.data, result.text);
} finally {
  await ava.dispose();
}
  • 使用单条只读 SELECT(支持 WITH),按 schema() 列出的名称为表和列加双引号。存储过程、SYSTEM$ 函数,以及 IDENTIFIER(name)(...) 形式的动态函数调用会被拒绝。
  • maxRows 和 maxResultBytes 分别限制返回结果的行数和大小。
  • NUMBER 在转换不损失数字位数时转为 JavaScript 数字,更大或更精确的值保留为十进制字符串;浮点数的 NaN 和无穷大保留为字符串。日期使用 YYYY-MM-DD,时间和时间戳带九位小数,时区类型附带偏移量。VARIANT、OBJECT 和 ARRAY 是解析后的 JSON,BINARY 是十六进制文本。

在线服务

飞书多维表格

读取多维表格记录。查看飞书配置指南。

腾讯文档智能表格

读取智能子表的字段和记录。查看腾讯文档配置指南。

GitHub

读取仓库中的 Issue 和 Pull Request。查看 GitHub 配置指南。