Skip to main content

Query

Queries are defined as Protobuf RPCs annotated with the temporal.v1.query method option. They're mapped to workflows using the query workflow option. See the Queries guide for more usage details.

warning

Query definitions must specify a non-empty output parameter. Query definitions can omit an input parameter by specifying the native google.protobuf.Empty message type in its place. This requires an additional google/protobuf/empty.proto protobuf import.

example.proto
syntax="proto3";

package example.v1;

import "temporal/v1/temporal.proto";

service Example {
  // Hello returns a friendly greeting
  rpc Hello(HelloInput) returns (HelloOutput) {
    option (temporal.v1.workflow) = {
      query: { ref: 'GetHelloStatus' }
    };
  }

  // GetHelloStatus retrieves the status of an existing Hello workflow
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {};
  }
}

Options​

name​

string

Fully qualified Query type name. Defaults to protobuf method full name (e.g. example.v1.Example.GetHelloStatus)

service Example {
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {
      name: "GetHelloStatus"
    };
  }
}

patches​

[]temporal.v1.Patch

Controls how a particular Patch is implemented in generated code, overriding any plugin or service-level configuration.

service Example {
  option (temporal.v1.service) = {
    patches: [
      { version: PV_64, mode: PV_MARKER },
    ]
  };

  rpc Example(ExampleInput) returns (ExampleOutput) {
    option (temporal.v1.query) = {
      patches: [
        { version: PV_64, mode: PV_ENABLED }
      ]
    }
  }
}

xns​

temporal.v1.XNSActivityOptions

Used to configure cross-namespace activity options.

note

This requires the enable-xns plugin option to be enabled.

service Example {
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {
      xns: {
        heartbeat_timeout: { seconds: 30 }
        heartbeat_interval: { seconds: 10 }
        start_to_close_timeout: { seconds: 300 }
      }
    };
  }
}