Query Studio actions

Chronos can run SQL through Query Studio on a schedule, from a Core Hub platform event, from an incoming webhook, or as a step in a chained event. The Control Plane action is Query Studio; the API task type is query_studio.

The same form appears on Scheduler → Schedules (main action and chained events) and Scheduler → Events (one action per event). Saving the form stores the action. It does not run the query.

What runs, and where

Chronos does not put SQL on the crontab command line. At fire time it POSTs to Core Hub:

POST /query-studio/pipelines/{pipelineId}/agents/{agentId}/execute

with body {"sql": "…", "options": {"readOnly": true|false}}.

That is the same Query Studio execute path used by the workbench. The request times out after 120 seconds. A Hub HTTP 2xx whose payload reports status: ERROR (or a failed query) is treated as a Chronos failure.

Chronos authenticates as the scheduler module (scheduler-module JWT), not as a signed-in Query Studio user.

Target: pipeline and one agent

A Query Studio action is always pipeline-scoped. The UI hides groups and entities (pipelineOnly). entity_ids, group_ids, and with_snapshot are ignored.

Every action needs:

  • a pipeline

  • an explicit SQL-capable agent (agent_id)

The agent picker lists agents from Chronos GET /api/query-studio/agents, which proxies Core Hub GET /query-studio/agents. The list is filtered to SQL-capable agents on the selected pipeline. Labels look like database (display name — dialect).

If Chronos cannot list agents, the form shows Unable to load SQL-capable agents — check that the scheduler module is running and can reach Core Hub.

Choose the query

After you pick Query Studio and a pipeline, choose one of these options.

Saved query (default)

Search the combo box by name or description. The list is the current user’s Query Studio saved queries for that pipeline (queries with no pipelineId still appear). Helper text: Search by name. Chronos stores a snapshot of the SQL and runs it when the event fires.

Selecting a saved query:

  • stores saved_query_id

  • copies the current SQL into query_sql as a snapshot (the UI always sends this)

  • fills agent_id when the saved query has one

If the saved query has no agent_id, the SQL-capable agent dropdown appears and you must pick one. You cannot save without an agent.

The API still accepts saved_query_id without a SQL snapshot. Chronos then relies on the live Hub query at fire time, or fails if that fetch also has no SQL.

Custom SQL

Enable Use a custom query. That clears saved_query_id and shows:

  • the SQL-capable agent dropdown (required)

  • the Query Studio SQL editor (dialect-aware completion for the selected agent)

Helper text: Chronos stores this SQL and executes it when the event fires. Saving does not run the query.

Switching custom query off clears the SQL field so you pick a saved query again.

What SQL runs at fire time

How the action was saved What Chronos executes

Saved query

Fetches the live Query Studio saved query from Core Hub. If that SQL is present, Chronos uses it (and the live agent when the Hub returns one). If the fetch fails (404, 403, or error), Chronos falls back to the stored query_sql snapshot and agent_id.

Custom SQL

Runs the stored query_sql against the stored agent_id.

If neither live SQL nor a snapshot is available, the action fails.

Updating a saved query in Query Studio therefore changes the next Chronos run, unless Core Hub cannot serve that saved query — then the snapshot taken when you saved the schedule or event is used.

Allow a query to modify data

query_read_only defaults to true. Core Hub then runs with Query Options readOnly: true (SELECT-only / SafetyGate).

The UI has one checkbox for writes: I acknowledge this query can modify data. Checking it sets query_read_only to false. There is no separate Read only toggle. A warning then states that the query will run with write access when the event fires and can change or delete data.

Leave the acknowledgment unchecked for count validation, reconciliation, or other reads.

A query_read_only: null payload is treated as read-only (including on non-Query-Studio jobs, so those creates do not fail with HTTP 500).

Run a query on a schedule

  1. In the Control Plane, open Scheduler.

  2. Create a schedule or open an existing one.

  3. Select Query Studio as the action type.

  4. Select the pipeline (groups and entities are not shown).

  5. Search for and select a saved query, or enable Use a custom query and enter SQL.

  6. Confirm the SQL-capable agent. A saved query fills the agent when it contains an agent_id; otherwise select one from the agent picker.

  7. Leave I acknowledge this query can modify data unchecked unless the statement must modify data.

  8. Configure the repeating options and save the schedule.

For the rest of the schedule form, see Chronos Scheduler and Schedules.

Run a query from an event

The same fields apply to either Chronos event trigger:

  • Platform event — Chronos runs the Query Studio action when the selected Core Hub platform event occurs.

  • Webhook trigger — Chronos runs the Query Studio action when a caller posts to the event’s secret-protected trigger URL.

    1. In the Control Plane, open Scheduler → Events.

    2. Create an event.

    3. Select Platform event or Webhook trigger.

    4. Select Query Studio as the action.

    5. Select the pipeline, then a saved query or Use a custom query.

    6. Confirm the SQL-capable agent.

    7. Leave the write acknowledgment unchecked unless the query must modify data.

    8. Save the event.

The Events form does not show execution mode, webhook timeout, or more than one action. Those controls belong to Schedules chained events.

For trigger URLs, tokens, and platform-event behavior, see Events and Webhooks.

Add a query to a chained event

  1. Create or edit a schedule.

  2. Expand Chained Events and add an event.

  3. Select Query Studio as the action.

  4. Select the pipeline and a saved query, or enable Use a custom query.

  5. Confirm the SQL-capable agent.

  6. Leave the write acknowledgment unchecked unless the query must modify data.

  7. Place any subsequent Chronos actions after the query.

  8. Save the schedule.

Query Studio has no Core Hub completion webhook. In sync mode:

  • Chronos waits on the HTTP execute (up to 120 seconds), not on a Hub callback.

  • When Query Studio is the preceding step, the next sync event skips the webhook wait and treats that HTTP execute as done.

See Chained events for async vs sync and ordering.

API fields

Field Required Description

task_type

Yes

query_studio

pipeline_id

Yes

Pipeline whose agent runs the query.

agent_id

Yes

SQL-capable agent. Required even when saved_query_id is set.

query_sql

Conditional

Custom SQL, or snapshot of a saved query. Required when saved_query_id is omitted.

saved_query_id

No

Query Studio saved query. Omit for custom SQL.

query_read_only

No

Defaults to true. Set false only after the write acknowledgment.

Schedule example:

{
  "name": "Nightly staging cleanup",
  "task_type": "query_studio",
  "cron_expression": "0 3 * * *",
  "pipeline_id": "pipeline-123",
  "agent_id": "agent-456",
  "saved_query_id": "saved-query-789",
  "query_sql": "DELETE FROM staging_orders WHERE created_at < CURRENT_DATE - 7",
  "query_read_only": false,
  "enabled": true
}

Chained-event example (validate counts, then start CDC):

{
  "task_type": "query_studio",
  "pipeline_id": "pipeline-123",
  "agent_id": "agent-456",
  "saved_query_id": "saved-query-counts",
  "query_sql": "SELECT COUNT(*) FROM orders",
  "query_read_only": true,
  "execution_mode": "sync",
  "webhook_timeout_seconds": 3600
}

Examples

Use Query Studio actions to:

  • Remove old rows from staging or log tables (write acknowledgment required).

  • Compare source and target counts for validation or reconciliation.

  • Run a validation query before another chained Chronos action.

  • Perform scheduled maintenance SQL.

Troubleshooting

Symptom What to check

Unable to load saved queries

Sign-in session; Query Studio saved-query API.

Unable to load SQL-capable agents

Chronos module is up; GET chronos/api/query-studio/agents can reach Core Hub.

No saved queries for this pipeline

Save the query in Query Studio against that pipeline first, or use a custom query.

No SQL-capable agents on this pipeline

The pipeline has no agent Query Studio can execute against.

Action fails at fire time

Agent still exists; saved query still readable or snapshot SQL is present; query finishes within 120 seconds; write acknowledgment is set if the SQL is not read-only.

Related documentation