Skip to main content

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) or 0 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.
FrequencyFieldsCRON timing
Every minute—* * * * *
Every 5 minutes—*/5 * * * *
Every 15 minutes—*/15 * * * *
Every 30 minutes—*/30 * * * *
HourlyAt minuteM * * * *
DailyAt hour, At minuteM H * * *
WeeklyOn day of week, At hour, At minuteM H * * D
MonthlyOn day of month, At hour, At minuteM 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 runE-mailURL (data field)
RowsThe text 'The "query" query result:' and the rows as a table, up to the row capAll 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 LIMIT or 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:

HeaderValue
query-idID of the query
query-hashShare hash of the query
executed-by-nameScheduled task
executed-by-emailScheduled task
executed-by-ipIP 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.