Skip to content
Browse documentation
Execution engines

DuckDB

Run SQL analysis against inline data, files, and attached databases.

Configure

typescript
const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
  engine: {
    type: 'duckdb',
    memoryLimit: '512MB',
    threads: 1,
    queryTimeoutMs: 30000,
    maxTempDirectorySize: '1GB',
  },
});

DuckDB is the default Node.js engine. It creates an in-memory instance and registers the source as tables or views. SQL generation uses the schema and optional profile.

Engine options

Set engine.type to duckdb. These are all additional fields accepted on engine.

FieldTypeRequiredMeaning / default
memoryLimitstringNoMemory limit, e.g. '512MB'. Default '512MB'.
threadsnumberNoNumber of worker threads. Default 1.
maxTempDirectorySizestringNoMax size of the spill (temp) directory, e.g. '1GB'. Unset = unlimited.
queryTimeoutMsnumberNoPer-query timeout in milliseconds. Default 30000.
allowCommunityExtensionsbooleanNoAllow DuckDB community extensions during source loading when explicitly needed.

Resource limits

Defaults are 512 MB of memory, one worker thread, and a 30-second query timeout. maxTempDirectorySize is optional; no spill-size limit is configured when omitted.

These options are separate from maxRows and maxResultBytes, which bound returned query results.

Source support

DuckDB supports inline CSV, JSON, and text; local or remote CSV, JSON, Parquet, and Excel; and MySQL, PostgreSQL, SQLite, and MongoDB sources. See data sources for configuration.

Execution security

AVA includes the following DuckDB security policies to reduce the risks of model-generated SQL:

  • Read-only execution: Allows exactly one read-only SELECT statement and rejects write operations and multi-statement queries.
  • Restricted external access: Disables external access after source registration, restricts local file access, and locks the connection configuration so queries cannot change security settings.
  • No automatic extension installation: Disables automatic extension installation and loading and unsigned extensions by default. Community extensions are also disabled unless explicitly required by a data source.
  • Resource limits: Limits memory, worker threads, and query time by default, with an optional limit for temporary spill space.
  • Bounded results: Uses maxRows and maxResultBytes to limit the number and size of returned rows, preventing oversized result sets.