User guide
Start with quick start and configuration.
Prepare data in a declared EPSG CRS with explicit XY axes for projected sources with a globally unique positive 32-bit integer identifier and one geometry family. CSV defaults to WKT; GeoParquet supports native/WKB geometry. Null geometry is allowed. Full-fetch sources must fit the record and 8 MiB bounds. Configure and qualify the P1 pass-through engine for larger sources.
node scripts/cdf-cli.js validate-config
node scripts/cdf-cli.js preflight -d default -o preflight-report.json
node scripts/cdf-cli.js test-connection -d default
node scripts/cdf-cli.js load-test -d default --full-fetch -q 100 -c 4 --cache disabled -o load-report.json
Preflight checks all rows within its bounded scan cap and reports schema/ID/geometry/full-fetch failures. Connection testing reads one feature and does not certify all source rows. Load testing measures concurrent model calls and reports SLO failures; see operations and measurement limits.
Use diagnostic limit/offset/geometry parameters as described in API reference. Readiness probes the database, while metrics require the configured token. Metrics reset after restart.
Caches are process-local. TTL mode may retain changes until expiry; select stat or an immutable version/qualified ETag for source-aware checks. Restart after changing configuration and to clear all caches immediately. SIGTERM/Ctrl+C drains work and closes the engine.
| Symptom | Action |
|---|---|
| Missing variable/config | Supply the exact documented config/secret value |
| Extension load fails | Check network/cache permissions, engine version, OS/architecture |
| Source not found | Choose a configured source name |
| Invalid IDs | Fix null, duplicate, noninteger, or out-of-range values |
| Oversized dataset/result | Partition or reduce geometry/attributes; do not silently truncate |
| Queue full/timeout | Check source latency and load before increasing limits |
| Hidden native HTTP error | Reproduce with trusted CLI; redact secret-bearing error output |
| HTTP 401 | Supply the correct Bearer token |
| Container exits | Verify token, production config, and preinstalled extensions |
Follow deployment and rollback for production changes.