tctl v1.16 batch command reference
How to run a tctl batch command.
A What is a Workflow Execution? A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.tctl batch command enables you to affect multiple existing Workflow Executions
Use tctl batch start to start a batch job.
When starting a batch job, you must provide a List Filter What is a List Filter? A List Filter is the SQL-like string that is provided as the parameter to an Advanced Visibility List API.
The List Filter identifies the set of Workflow Executions to be affected by the batch job.
The tctl batch start command shows you how many Workflow Executions will be affected by the batch job and asks you to confirm before proceeding.
The batch type determines what other parameters you must provide and what is being affected. There are three types of batch jobs:
- Signal: Send a Signal to the set of Workflow Executions that the List Filter specifies.
- Cancel: Cancel the set of Workflow Executions that the List Filter specifies.
- Terminate: Terminate the set of Workflow Executions that the List Filter specifies.
A successfully started batch job returns a Job ID.
You can use this Job ID in the tctl batch describe command, which describes the progress of a specific batch job.
You can also use the Job ID to terminate the batch job itself. Terminating a batch job does not roll back the operations already performed by the batch job.
tctl batch commands
start
The tctl batch start command starts a batch job.
tctl batch start --query <value> [<modifiers>]
The following modifiers control the behavior of the command.
--query
Required modifier
Specify the Workflow Executions What is a Workflow Execution? A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.
The SQL-like query of Search Attributes What is a Search Attribute? A Search Attribute is an indexed name used in List Filters to filter a list of Workflow Executions that have the Search Attribute in their metadata.tctl workflow list --query command.
Alias: -q
Example
tctl batch start --query <value>
--reason
Specify a reason for running this batch job.
Alias: --re
Example
tctl batch start --query <value> --reason <string>
--batch_type
Specify the operation that this batch job performs. The supported operations are signal, cancel, and terminate.
Alias: --bt
Example
tctl batch start --query <value> --batch_type <operation>
--signal_name
Specify the name of a Signal. This modifier is required when --batch_type is signal.
Alias: --sig
Example
tctl batch start --query <value> --batch_type signal --signal_name <name>
--input
Pass input for the Signal. Input must be in JSON format.
Alias: -i
Example
tctl batch start --query <value> --input <json>
--rps
Specify RPS of processing. The default value is 50.
Example
tctl batch start --query <value> --rps <value>
--yes
Disable the confirmation prompt.
Example
tctl batch start --query <value> --yes
list
Alias: l
The tctl batch list command lists all batch jobs.
tctl batch list [<modifiers>]
The following modifier controls the behavior of the command.
--pagesize
Specify the maximum number of batch jobs to list on a page. The default value is 30.
Alias: --ps
Example
tctl batch list --pagesize <value>
describe
Alias: desc
The tctl batch describe command describes the progress of a batch job.
tctl batch describe --job_id <id>
The following modifier controls the behavior of the command.
--job_id
Required modifier
Specify the job ID of a batch job.
Alias: --jid
Example
tctl batch describe --job_id <id>
terminate
The tctl batch terminate command terminates a batch job.
tctl batch terminate --job_id <id> [<modifiers>]
The following modifiers control the behavior of the command.
--job_id
Required modifier
Specify the job ID of a batch job.
Alias: --jid
Example
tctl batch terminate --job_id <id>
--reason
Specify a reason for terminating this batch job.
Alias: --re
Example
tctl batch terminate --job_id <id> --reason <string>