Updates and queries

Active contributors: david, alex, yichaoyang

Purpose

Workflows are normally fire-and-forget: you start a workflow, it runs, and you read its result later. Updates and Queries make synchronous-style interaction possible:

• Query — read derived state from a running workflow without modifying it. The worker runs query handlers in a non-mutating workflow task.
• Update — submit a request that the workflow validates and (if accepted) processes. The caller can wait for Accepted (validation) or Completed (the workflow returned a result).

Both are implemented on top of speculative workflow tasks: a workflow task that is delivered to a worker but not written to history unless it produces durable side effects.

Source map

Surface	File / package
Public proto	temporal.api.update.v1.*, temporal.api.query.v1.*
Frontend handler	service/frontend/workflow_handler.go (UpdateWorkflowExecution, QueryWorkflow, PollWorkflowExecutionUpdate)
History API impls	service/history/api/updateworkflow/, service/history/api/pollupdate/, service/history/api/queryworkflow/
Speculative workflow task	docs/architecture/speculative-workflow-task.md
Update protocol & messages	docs/architecture/message-protocol.md, docs/architecture/workflow-update.md
Functional tests	tests/update_workflow_test.go (~223KB), tests/query_workflow_test.go, tests/update_workflow_sdk_test.go

How an Update flows

sequenceDiagram
    participant Caller
    participant FE as Frontend
    participant H as History
    participant Worker

    Caller->>FE: UpdateWorkflowExecution
    FE->>H: forward
    H->>H: enqueue speculative WFT
    H->>Worker: deliver WFT (no history append yet)
    Worker->>H: RespondWorkflowTaskCompleted with Update messages
    alt Accepted + Completed in same WFT
      H->>H: append events, complete update
    else Accepted only
      H->>H: append events, update is Pending
    end
    H-->>FE: Update outcome
    FE-->>Caller: outcome (Accepted / Completed)

The mechanism is documented end-to-end in docs/architecture/workflow-update.md. The wire format for Update messages between Frontend, History, and the SDK is at docs/architecture/message-protocol.md.

How a Query flows

Conceptually the same speculative-task machinery, but the result is read-only: the worker's query handler returns a result that is sent back to the caller without producing history events.

Entry points for modification

• Changing the message protocol: docs/architecture/message-protocol.md is the canonical reference. The protocol lives in temporal.api.update.v1 and temporal.api.protocol.v1.
• Tuning timeouts: dynamic-config keys prefixed frontend.update.* and history.update.*.
• Speculative workflow task changes: service/history/api/respondworkflowtaskcompleted/workflow_task_completed_handler.go is the central piece.

Related pages

• Workflows and activities
• Frontend service
• History service
• docs/architecture/workflow-update.md