Skip to main content

Trigger workflows with queries

Learn how to trigger tasks using queries with Retool Workflows.

You can trigger a workflow using messages polled from Amazon SQS or Kafka streaming services. Query triggers poll a topic or queue on a configured interval and trigger a workflow run for each message retrieved.

Add a query trigger​

To add a trigger, click the startTrigger block or open the Triggers tab in the left panel.

You can create multiple query triggers to poll for messages from different queues and at different intervals, in addition to using a webhook or schedule trigger. The highest frequency at which you can poll for messages is once per minute.

If you use an Amazon SQS resource, the Action type is automatically set to Receive messages from a queue. For a Kafka resource, the Action type is automatically set to Consume messages from a topic.

Set polling options​

Expand the Advanced Settings section to configure how often you want Retool to poll for new messages. You can schedule polling using Interval mode to specify the frequency using a set of options. For more granularity, use Cron mode to provide cron syntax.

Configure querying on an interval​

Use the Schedule option to configure a Retool to poll for messages periodically. You can configure a schedule that triggers every n minutes, hours, days, weeks, or months.

Configure an interval schedule.

Configure querying on a cron schedule​

Check out some examples to learn more about cron syntax.

Retool Workflows supports cron syntax when configuring a query trigger. The bottom of the Advanced Settings section displays a human-readable version of the values you provide. You can also hover the cursor over the label for each input to display a tooltip with syntax reference.

Configure a cron schedule.

Configure workflow run behavior​

Workflows function differently depending on whether you use them with Amazon SQS or Kafka.

  • Retool ensures that each unique message is used by only one workflow run at a time. Two workflows cannot action on the same message at the same time.
  • Query triggers can receive up to 20 SQS messages at one time, and Retool triggers a unique workflow run per message. The workflow runs execute in parallel.
  • Because SQS supports only one consumer group per queue, you cannot have more than one workflow consuming from the same SQS queue.

Conclude the workflow run​

At the end of each workflow run, you must mark the message as deleted (Amazon SQS) or committed (Kafka) to prevent it from being retrieved by the next query trigger. Complete the following steps to ensure that each message is consumed only once.

  1. Add a resource query block to your workflow that accesses your Amazon SQS resource.
  2. Set the Action type to Delete a message from a queue.
  3. Set the Queue to the same queue that you defined in the query trigger.
  4. Set the Receipt Handle to {{startTrigger.data.receiptHandle}}.