Configuration
Default file: config/config.json. Override with CDF_CONFIG or constructor configPath. Constructor config accepts a direct object; explicitly resolve environment placeholders for this path. File loading resolves ${NAME} and fails for missing/empty variables. Environment files are not loaded automatically.
Sources
dataSources is a non-empty object, keyed by names containing letters, digits, underscores, or hyphens. defaultDataSource defaults to "default" if present, otherwise the first entry.
| Required field | Constraint |
|---|---|
| type | csv, json (tabular records), geoparquet, local-file |
| path or url | Local path, HTTPS/S3 GeoParquet, or opted-in CloudFS CSV/JSON/GeoParquet; no credentials/query/fragment |
| idField | Simple SQL identifier; globally unique positive integer 1–2,147,483,647 |
| geometryColumn | Simple SQL identifier different from idField |
Relative paths resolve against the application root. geometryEncoding is wkt, wkb, or native; defaults to wkt for CSV/JSON records and native otherwise. crs defaults to 4326 and accepts EPSG integers. Other sources require explicit axisOrder xy; DuckDB transforms to WGS84. Points/lines/polygons and multi variants are supported; one geometry family per layer, nullable geometry allowed.
For GeoParquet, use type geoparquet and a native geometry column with valid GeoParquet metadata, or explicit WKB encoding. Full-fetch validates the returned collection; the query engine qualifies IDs and geometry across the whole source before paging. The legacy features route validates each page, so qualify global uniqueness separately.
Limits and defaults
| Setting | Default | Unit/behavior |
|---|---|---|
| maxRecordCount | 2000 | Features, configurable 1–100,000 |
| performance.cacheEnabled | true | Boolean |
| performance.cacheTTL | 30000 | Milliseconds |
| performance.maxCacheEntries | 128 | LRU entries |
| performance.maxCachedBytes | 33554432 | Serialized bytes |
| performance.maxPendingQueries | 16 | Active + queued requests |
| performance.queueTimeoutMs | 15000 | Maximum queue wait in milliseconds |
| performance.initializationTimeoutMs | 30000 | Active initialization budget in milliseconds |
| performance.requestTimeoutMs | 30000 | Total admitted-operation lifetime in milliseconds |
| performance.queryTimeoutMs | 15000 | Native execution milliseconds |
| database.memoryLimit | 512MB | Engine budget, not all process memory |
| database.threads | 2 | Total 1–64 engine threads across workers |
| database.poolSize | 1 | Optional 1–8 exclusive native workers; divides memory/threads; CloudFS requires 1 |
| database.installExtensions | true | False for prebuilt production image |
| database.extensionDirectory | DuckDB default | Extension cache path |
| database.tempDirectory | OS temp | Parent for owned per-model/per-worker scratch directories |
| server.host / server.port | 127.0.0.1 / 3000 | Standalone listener |
Native results and GeoJSON responses are limited to 8 MiB. Deadline settings accept 1–3,600,000 milliseconds. Queue, initialization, execution and total deadlines apply independently; the first expiry wins. Cancelled/expired native work retains ownership until it settles. See preflight, metrics and cancellation.
CloudFS (opt-in)
cloudfs.enabled defaults to false. cloudfs.extensionVersion defaults to the reviewed build 4ca1432. cloudfs.credentials is keyed by sharepoint, onedrive, gdrive, dropbox, or vfs. Each profile accepts provider=token plus tokenEnv (an environment variable name), or gdrive provider=service_account plus keyJsonEnv. Raw tokens and arbitrary SQL/options are rejected. Credentials are resolved at connection initialization, not expanded into config.
CloudFS URIs require enabled=true and the corresponding profile; supported schemes are spfs, odfs, gdfs, dbxfs, vfs, and vfs+tls. Non-loopback agents require vfs+tls, which is blocked for reviewed build 4ca1432 pending an upstream routing fix. SFTP is blocked pending host-key verification. One active CloudFS model and one account per provider are allowed per process. Current 1.5.6 binaries are unavailable; see compatibility, examples, and qualification before activation.
Environment
CDF_CONFIG selects the config file. CDF_API_TOKEN supplies a token of at least 32 characters. NODE_ENV=production enforces authentication. HOST and PORT override the standalone bind. S3 uses DuckDB's ambient AWS credential chain; configure read-only workload access or AWS environment credentials. DUCKDB_EXTENSION_DIRECTORY is used by the image-build installation helper.
The model itself relies on ArcGIS access control and does not enforce forwarded user/tenant policies.
Migration
Older source arrays, missing ID/geometry fields, seconds-based TTL, and enabled experimental flags are incompatible. Unknown source types and enabled Azure/lakehouse/streaming/graph/MCP/Redis/prototype flags fail validation. Historical copied configs are unsupported; start with the current examples and validate.
Unknown configuration fields are rejected, including legacy security/tenant settings. Remove unsupported blocks rather than assuming they enforce a policy. Each supported block accepts only documented fields. Source queryMode, axisOrder, schema and freshness contracts are detailed in P1 configuration and migration, with a validated pass-through example.
Use the official DuckDB Node Neo client. Extensions must match its engine version and the deployment OS/architecture.