Scheduling Queries
A schedule runs a query automatically at set times and sends the result to a list of recipients: e-mail addresses, URLs, or both. This turns any query into an automated report — a daily sales summary, a weekly KPI digest, or an hourly health check.
Opening the schedules
In the queries list, the clock button (Schedule) of a query opens the Query schedule window. It is available to members who can edit the query. A query that has schedules shows a clock icon (Scheduled) next to its name.
- Add schedule adds a schedule that runs daily at 08:00; change it in its tabs.
- The list on the left shows every saved schedule by its recipients and its next run time.
- Save saves every schedule of the window, all of them or none: when one of them cannot be saved (for example because of a cron expression Kvery cannot read), none of the window's schedules are saved.
A query can have more than one schedule, which is handy when different recipients need the same report at different cadences. Each schedule has four tabs: Time, Notification, Variables and Delete.
Timing
On the Time tab:
- Select timezone — the time zone the schedule's times are meant in. The next run time is calculated in this time zone.
- Frequency — a preset, or Custom (see the table below).
- CRON timing — the cron expression of the schedule (minute, hour, day of month,
month, day of week), with a link to crontab.guru. The
presets fill it in; with Custom you write it yourself, for example
*/10 * * * *(every 10 minutes) or0 7 * * 1-5(weekdays at 07:00). A saved expression that no preset produces opens as Custom. An expression Kvery cannot read is refused with "Wrong CRON expression!" when you save; then none of the window's schedules are saved, so correct it and click Save again.
| Frequency | Fields | CRON timing |
|---|---|---|
| Every minute | — | * * * * * |
| Every 5 minutes | — | */5 * * * * |
| Every 15 minutes | — | */15 * * * * |
| Every 30 minutes | — | */30 * * * * |
| Hourly | At minute | M * * * * |
| Daily | At hour, At minute | M H * * * |
| Weekly | On day of week, At hour, At minute | M H * * D |
| Monthly | On day of month, At hour, At minute | M H D * * |
| Custom | — | written by you |
Recipients
On the Notification tab:
- Notification e-mails and/or URLs — type an e-mail address or a URL and press Enter to add it. An entry that is neither is skipped, and a recipient listed twice gets one message. On app.kvery.io a URL that points to an internal address of the server's network is not called.
- For e-mail, the maximum number of rows in the table — the row cap of the e-mailed table: 25 rows by default, which you can change per schedule (1–999; 0 or empty uses the default).
- Only notify in case of an error! — only failed runs are sent; a successful run sends nothing.
Parameters
On the Variables tab, give values to the query's form variables, so the scheduled run is fully self-contained. The tab is shown only when the query has form fields that are not hidden.
What the recipients receive
A run whose result table is empty sends nothing. Otherwise every recipient gets the result:
| Result of the run | URL (data field) | |
|---|---|---|
| Rows | The text 'The "query" query result:' and the rows as a table, up to the row cap | All rows |
| Success without a result table (for example a query that only writes data) | 'The "query" query was executed successfully!' | 1 |
| Error | 'An error occurred while executing the "query" query!' | Something went wrong! |
The e-mail
Every e-mail has the subject "query - query result" (query is the query's description) and ends with the address of Kvery. When the result has more rows than the cap, the e-mail says "The table shows only the first N rows!" and links to the query's run page in Kvery; the link carries the schedule's parameter values, except the values of password fields. The e-mail never contains the error message of a failed run: look it up in the logs.
For larger result sets, consider:
- adding a
LIMITor aggregating the data in the query itself, or - e-mailing a summary and linking recipients to the full shared query or dashboard.
The URL request
A URL recipient gets a POST request with a form-encoded body
(application/x-www-form-urlencoded), which works as a webhook:
data— the result from the table above. Rows arrive as nested fields, one index per row (data[0][column]=value), and are not limited by the row cap.- The schedule's parameter values, by variable name.
The request carries these headers:
| Header | Value |
|---|---|
query-id | ID of the query |
query-hash | Share hash of the query |
executed-by-name | Scheduled task |
executed-by-email | Scheduled task |
executed-by-ip | IP address of the Kvery server |
Monitoring scheduled runs
Every scheduled execution is recorded in the logs with its response code. If a scheduled query starts failing — for example after a schema change — the log shows the error so you can fix it quickly. Filter the logs by response code to find failures fast.
Removing a schedule
Open the schedule's Delete tab and click DELETE SCHEDULE. The query itself is unaffected and can still be run manually or via its API.
Tips
- Schedules run server-side and do not require you to be logged in.
- A scheduled run uses the published version of the query: an unpublished draft is not run until you publish it. The parameters of the schedule form come from that version too. Drafts are kept only while a query is shared, so for a query that is not shared this is its latest saved version.
- Because schedules run in the background, they are a good fit for heavier queries that you would not want to wait on interactively.
- Combine scheduling with history: if a scheduled report breaks after an edit, roll the query back and the next run is healthy again.