Async Export

For large result sets, the Query Engine supports asynchronous exports with progress tracking. The client submits an export request, receives an export ID, and polls for completion before downloading the file.

Workflow

1. POST /v1/queries/{id}/export/async    --> Returns exportId
2. GET  /v1/queries/exports/{id}/progress --> Poll until COMPLETED
3. GET  /v1/queries/exports/{id}/download --> Download file
4. DELETE /v1/queries/exports/{id}        --> Cleanup

Step 1: Submit Async Export

curl -X POST http://query-engine:8080/v1/queries/a1b2c3d4-e5f6-7890/export/async \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"format": "CSV", "includeHeader": true, "compress": true}'

{
  "exportId": null,
  "executionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS",
  "format": "CSV"
}

Step 2: Check Progress

curl http://query-engine:8080/v1/queries/exports/e1f2a3b4-c5d6-7890/progress \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "exportId": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "executionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS",
  "format": "CSV",
  "startedAt": "2026-02-12T10:30:00Z",
  "totalRows": 500000,
  "rowsProcessed": 245000,
  "percentComplete": 49
}

Step 3: Download Completed Export

curl -O http://query-engine:8080/v1/queries/exports/e1f2a3b4-c5d6-7890/download \
  -H "Authorization: Bearer $JWT_TOKEN"

The response includes appropriate headers:

Content-Disposition: attachment; filename="export-a1b2c3d4-12345.csv"
Content-Length: 24576000
Content-Type: text/csv

Step 4: Cleanup

After downloading, clean up the temporary export file:

curl -X DELETE http://query-engine:8080/v1/queries/exports/e1f2a3b4-c5d6-7890 \
  -H "Authorization: Bearer $JWT_TOKEN"

Export Status Values

Status	Description
`PENDING`	Export queued
`IN_PROGRESS`	Export actively writing
`COMPLETED`	Export finished, file ready for download
`FAILED`	Export failed with error

Configuration

query:
  export:
    temp-dir: /tmp/query-exports
    max-rows: 1000000
    chunk-size: 10000

Property	Default	Description
`query.export.temp-dir`	`/tmp/query-exports`	Temporary directory for export files
`query.export.max-rows`	`1000000`	Maximum rows per export
`query.export.chunk-size`	`10000`	Rows processed per batch (controls progress granularity)

JSON Export Optimization