Update vs Signal vs Query - response types and consistency
Updates provide synchronous typed responses with strong consistency, suitable for request-response patterns. Signals provide no response (fire-and-forget) with eventual consistency, suitable for asynchronous state modifications. Queries provide synchronous typed responses but with eventual consistency, suitable for read-only operations. Updates are slower than Signals because they require a history write, but provide stronger consistency guarantees.
Update definition and key characteristics
A Workflow Update is an API that executes an Update handler to validate inputs, modify state, and return values synchronously to the client. The Update is recorded in Workflow history before returning, providing strong consistency. Updates require validation before accepting work and enable external systems to modify Workflow state synchronously with typed error handling.
Update validator execution and error handling
In all SDKs, the validator runs before the Update handler. If the validator throws an exception, the Update is rejected and the client receives a typed error. If the validator passes, the Update handler modifies state and returns a typed result. The Update is recorded in Workflow history before the response is returned to the client.
Update performance and limits
Updates are slower than Signals because they require a history write. The Update handler blocks Workflow Task execution and consumes Workflow Task execution time. Update arguments and return values are limited by the Workflow history event size, typically 2 MB per event. Each Update adds events to Workflow history, contributing to the 50K event limit. There is a maximum of 10 in-flight Updates per Workflow execution and a maximum of 2,000 total Updates in Workflow history.
When to use Updates
Use Updates for request-response patterns requiring immediate confirmation, input validation before accepting work, synchronous state modifications with typed responses, operations requiring strong consistency guarantees, and entity Workflows that need external state updates. Do not use Updates for fire-and-forget operations (use Signals), read-only operations (use Queries), high-throughput scenarios where latency matters, or operations that do not need an immediate response.
Update best practices
Validate early by checking inputs at the start of the Update handler to fail fast. Handle errors by throwing typed exceptions for validation failures. Return quickly and do not perform long operations in the Update handler. Track Update IDs only across Continue-As-New; within a single Workflow Execution, the Server deduplicates retried Updates automatically by Update ID. Set appropriate Update timeouts and ensure state modifications are atomic within the handler.
Update handler pitfalls
Do not perform long operations in the Update handler as they block Workflow Task execution; offload long-running work to Activities and use Workflow.await in the handler to wait for results. Avoid exceeding the 2,000 total Updates limit; use Continue-As-New before reaching the limit as the server sets SuggestContinueAsNew at 90%. Always set Update timeouts on the client side to prevent indefinite blocking if the Worker is unavailable. Do not assume you must set an Update ID for retry safety; the SDK auto-generates a unique updateId and retried client calls are deduplicated automatically. Avoid using Updates for fire-and-forget operations; use Signals instead as Updates require a Worker to be online and responsive.
Update ID deduplication scope
Within a single Workflow Execution, the Server deduplicates retried Updates automatically by Update ID, so a retry does not run the handler twice. Update ID deduplication is scoped to a single Workflow Run. You only need to track processed Update IDs in Workflow state when carrying them across a Continue-As-New boundary.
Update retry ID behavior
The SDK auto-generates a unique updateId when you do not provide one, and retried client calls are deduplicated automatically. Set a stable, business-meaningful updateId when you want a retried Update-with-Start to attach to an existing in-flight Update instead of starting duplicate work.
Signal delivery guarantees in Temporal
Temporal delivers Signals at least once. Include a deduplication key in Signal payloads and make Signal processing logic idempotent to handle duplicate deliveries.
Signal handler requirements in Python SDK
Signal handlers must be synchronous — they only append to a queue. All processing happens in the main loop to ensure sequential execution. The @workflow.signal decorator marks a method as a Signal handler. Signal handlers should not perform async operations or side effects; instead, they enqueue work for the main Workflow loop.
Query handler behavior in Workflows
Query handlers are read-only and do not generate Events. They are safe to call at high frequency. Query handlers must be synchronous and return the current state without modifying it. Queries allow external services to read Workflow state without side effects.
Update handler capabilities and blocking
Update handlers can be async and block until the Workflow processes them and returns a result, making them ideal for request-response patterns. Updates allow Activities to be executed directly within the handler. The Update blocks the caller until a confirmed result is returned from the Workflow.
Update validator in Temporal
An Update can have a validator method marked with @update_name.validator that runs before the Update is accepted into Event History. Rejection at the validator stage writes no Event. Validators are useful for early validation of Update parameters before committing them to history.
Processing order in Entity Workflow signal queue
Signal handlers append events to a queue synchronously. The main Workflow loop processes queued signals sequentially, one at a time. This ensures events are processed in order and prevents race conditions.
Activity execution during Update handlers
In Python and TypeScript SDKs, Update handlers can be async and execute Activities directly via await workflow.execute_activity(). This is safe when the Activity is idempotent — replay detects duplicate event_ids and returns without creating duplicate records. In Java SDK, Update handlers cannot be async; enqueue work for the main loop instead.
Python SDK signal on Workflow handle
Signal handlers are fire-and-forget: the call returns once the Temporal Server accepts the Signal. Use handle.signal(WorkflowClass.signal_method, args) to send a Signal to a running Workflow.
Python SDK query on Workflow handle
Queries are synchronous and read-only — no Events generated. Use handle.query(WorkflowClass.query_method) to read Workflow state. Queries are safe to call at high frequency without generating history bloat.
Python SDK execute_update on Workflow handle
Updates block until the Workflow processes them and returns a result. Use handle.execute_update(WorkflowClass.update_method, args) for synchronous request-response patterns. Ideal for checkout flows that need confirmed changes before proceeding.
WorkflowExecutionSignaled event indicates signal received
WorkflowExecutionSignaled event indicates the Workflow has received a Signal Event. It has fields: signal_name (Name/type of Signal to be fired), input (Deserialized to provide arguments to Workflow function), identity (Identifies Worker that signaled to Workflow), header (Information passed by sender of Signal copied into Workflow Task).
SignalExternalWorkflowExecutionInitiated event
SignalExternalWorkflowExecutionInitiated event indicates that the Temporal Server will try to Signal the targeted Workflow. It has fields: workflow_task_completed_event_id (Id of WorkflowTaskCompleted Event reported with), namespace (Namespace of Workflow that's to be signaled), workflow_execution (Identifies Workflow and run of Workflow Execution), signal_name (Name/type of Signal to be fired), input (Deserialized to provide arguments to Workflow Function), child_workflow_only (Set to true if this Workflow is child of Workflow which issued cancelation request), header (Information to be passed from Signal to targeted Workflow).
ExternalWorkflowExecutionSignaled event
ExternalWorkflowExecutionSignaled event indicates that the Temporal Server has successfully Signaled the targeted Workflow. It has fields: initiated_event_id (Id of SignalExternalWorkflowExecutionInitiated Event this Event corresponds to), namespace (Namespace of Workflow that was signaled to), workflow_execution (Identifies Workflow and run of Workflow Execution).
SignalExternalWorkflowExecutionFailed event
SignalExternalWorkflowExecutionFailed event indicates that the Temporal Server cannot Signal the targeted Workflow, usually because Workflow could not be found. It has fields: workflow_task_completed_event_id (Id of WorkflowTaskCompleted Event reported with), namespace (Namespace of Workflow that failed to execute), workflow_execution (Identifies Workflow and run of Workflow Execution), initiated_event_id (Id of RequestCancelExternalWorkflowExecutionInitiated Event this failure signal corresponds to).
WorkflowExecutionUpdateAcceptedEvent indicates update accepted
WorkflowExecutionUpdateAcceptedEvent indicates that a Workflow Execution has accepted an Update for execution. The original request input payload is both indicated and stored by this Event, as it generates no Event when initially requesting an Update. It has fields: protocol_instance_id (Instance of Update protocol with this Id executing this Update), accepted_request_message_id (Id of request message sent by Temporal Server to Worker), accepted_request_sequencing_event_id (Execute this Update after Event with this Id), accepted_request (Request input and metadata initially provided by invoker of Update and subsequently relayed by Temporal Server to Worker for acceptance and execution).
WorkflowExecutionUpdateCompletedEvent indicates update completed
WorkflowExecutionUpdateCompletedEvent indicates that a Workflow Execution has executed an Update to completion.
WorkflowExecutionUpdateCompleted event fields
The WorkflowExecutionUpdateCompleted event contains three fields: meta (the metadata associated with the Update, sourced from the initial request), accepted_event_id (the ID of the WorkflowExecutionUpdateAcceptedEvent that accepted this Update for execution), and outcome (the outcome of execution of this Update whether execution resulted in success or failure).
Update result waits for WorkflowExecutionUpdateCompleted event with outcome
Update result is delivered through the WorkflowExecutionUpdateCompleted event, which contains the outcome field indicating whether the execution resulted in success or failure.
Signal rate impact on Workflow lock latency
High rate of Signals to a single Workflow execution causes Workflow lock latency which in turn affects Schedule-to-start latency. To address this reduce the rate of Signals.