Skip to main content

Temporal Signals and Queries

Signals and Queries are messages that provide data to and request data from a running Workflow Execution.

Signals and Queries are frequently used together.

Signals

A Signal is an external asynchronous request to a Workflow Execution.

A Signal is meant to deliver data to a running Workflow Execution which can be used to change variable values and the state of Workflow Execution. A Signal can not return data to the caller, use Queries for that. A Signal can be sent using a Temporal Client or from within a Workflow. When a Signal is sent, it is received by the Cluster and recorded as an Event to the Workflow Execution Event History. The Cluster will deduplicate Signals and use the first Signal with a particular Id. The next scheduled Workflow Task contains the Signal Event.

A Signal is a message with a unique Id. A Signal must include a destination (Namespace + Workflow Id).

A Signal Header includes the following:

  • Recipient: Workflow Execution (Namespace + Workflow Id)
  • Id: The unique id of the Signal.
  • Name: The queue in which the Signal will be added.

A Signal Body includes the following:

  • Any encodable data.

Workflow functions listen for Signals by the Signal name. Signals are delivered in the order they are received. Workflow Execution can optionally await on a single Signal name or multiple Signal names.

Queries

A Query is a synchronous operation that is used to report the state of a Workflow Execution.

The state of a running Workflow Execution is constantly changing. Queries are available to expose the internal Workflow Execution state to the external world.

  • A Query is a synchronous call from a Temporal Client.
  • A Query can carry arguments to specify which data it is requesting, as every Workflow can expose data to multiple types of Queries.
  • A Query must never mutate the state of the Workflow Execution.
  • If a Query is sent to a completed Workflow Execution, the final value is returned.
  • Query handling logic is implemented as code within the Workflow. Query handling logic must be read-only and cannot change the Workflow Execution state in any way, or contain any blocking code. This means that Query handling logic can not spawn Activity Executions.

In many SDKs the Temporal Client exposes a predefined _stack_track_ Query that returns the stack trace of all the threads owned by that Workflow Execution. This is a great way to troubleshoot a Workflow Execution in production.

Get notified of updates