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​

cli.aliases​

[]string

Adds additional aliases to the CLI command.

service Example {
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {
      cli: {aliases: ["ghs", "hs"]}
    };
  }
}

cli.ignore​

bool

Prevents the generation of CLI commands for the query.

service Example {
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {
      cli: {ignore: true}
    };
  }
}

cli.name​

string

Overrides the default CLI command name for the query.

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

cli.usage​

string

Overrides the default CLI command usage for the query.

service Example {
  // GetHelloStatus retrieves the status of an existing Hello workflow
  rpc GetHelloStatus(GetHelloStatusInput) returns (GetHelloStatusOutput) {
    option (temporal.v1.query) = {
      cli: {usage: "get the status of a Hello workflow"}
    };
  }
}

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 }
      }
    };
  }
}