Query Scheduling

The QueryScheduleController enables automated, recurring query execution. Schedules support cron expressions, interval-based timing, and one-time execution with full lifecycle management.

Base Path

/v1/schedules

Create a Schedule

curl -X POST http://query-engine:8080/v1/schedules \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-User-ID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "name": "Daily Revenue Report",
    "description": "Generates daily revenue summary by region",
    "queryText": "SELECT region, SUM(revenue) as total FROM orders WHERE order_date = current_date - interval '\''1'\'' day GROUP BY region",
    "scheduleType": "CRON",
    "cronExpression": "0 0 6 * * ?",
    "timezone": "America/New_York",
    "engineType": "TRINO",
    "maxRetries": 3,
    "retryDelaySeconds": 60,
    "timeoutSeconds": 3600,
    "priority": 3,
    "storeResults": true,
    "resultRetentionDays": 30,
    "notifyOnSuccess": false,
    "notifyOnFailure": true,
    "notificationEmails": "data-team@example.com"
  }'

Schedule Types

Type	Configuration	Example
`ONCE`	`startTime`	Run once at a specific time
`INTERVAL`	`intervalSeconds`	Run every N seconds
`CRON`	`cronExpression`	Cron-based scheduling
`DAILY`	`startTime` + `timezone`	Run daily at a specific time
`WEEKLY`	`startTime` + `timezone`	Run weekly
`MONTHLY`	`startTime` + `timezone`	Run monthly

Lifecycle Management

# List schedules
curl http://query-engine:8080/v1/schedules \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"
 
# Pause a schedule
curl -X POST http://query-engine:8080/v1/schedules/{scheduleId}/pause \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"
 
# Resume a paused schedule
curl -X POST http://query-engine:8080/v1/schedules/{scheduleId}/resume \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"
 
# Trigger immediate execution
curl -X POST http://query-engine:8080/v1/schedules/{scheduleId}/trigger \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"
 
# Delete a schedule
curl -X DELETE http://query-engine:8080/v1/schedules/{scheduleId} \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"

Execution History

curl http://query-engine:8080/v1/schedules/{scheduleId}/executions \
  -H "X-Tenant-ID: ..." \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "scheduleName": "Daily Revenue Report",
  "executionCount": 45,
  "successCount": 43,
  "failureCount": 2,
  "consecutiveFailures": 0,
  "lastExecutedAt": "2026-02-12T06:00:00Z",
  "lastExecutionStatus": "SUCCESS",
  "lastExecutionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nextScheduledAt": "2026-02-13T06:00:00Z"
}

Auto-Disable

Schedules are automatically disabled after 5 consecutive failures to prevent runaway error accumulation:

public boolean shouldAutoDisable() {
    return consecutiveFailures >= 5;
}

Schedule Status Values

Status	Description
`ACTIVE`	Schedule is running normally
`PAUSED`	Temporarily paused by user
`DISABLED`	Disabled manually or auto-disabled after failures
`COMPLETED`	One-time schedule has executed
`EXPIRED`	Past the configured `endTime`

Saved Queries Overview