tctl v1.17 batch command reference

How to run a tctl batch command.

A tctl batch command enables you to affect multiple existing Workflow Executions with a single command. A batch job runs in the background and affects Workflow Executions one at a time.

Use tctl batch starttctl batch start

How to start a batch job using tctl.

Learn more to start a batch job.

note

tctl-v1 can run batch and batch-v2 commands.

When starting a batch job, you must provide a List FilterWhat is a List Filter?

A List Filter is the SQL-like string that is provided as the parameter to an Advanced Visibility List API.

Learn more and the type of batch job that should occur. Batch jobs run in the background and affect Workflow Executions one at a time.

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

• tctl batch describetctl batch describe
  
  How to describe the progress of a batch job using tctl.
  
  Learn more
• tctl batch listtctl batch list
  
  How to list batch jobs using tctl.
  
  Learn more
• tctl batch starttctl batch start
  
  How to start a batch job using tctl.
  
  Learn more
• tctl batch terminatetctl batch terminate
  
  How to terminate a batch job using tctl.
  
  Learn more

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 that this batch job should operate.

The SQL-like query of Search AttributesWhat 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.

Learn more is the same as used by the tctl workflow list --query command.

Alias: -q

Example

tctl batch start --query <value>

--reason

Specify a reason for running this batch job.

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.

Example

tctl batch start --query <value> --batch_type <operation>

--signal_name

Specify the name of a SignalWhat is a Signal?

A Signal is an asynchronous request to a Workflow Execution.

Learn more. This modifier is required when --batch_type is signal.

Example

tctl batch start --query <value> --batch_type signal --signal_name <name>

--input

Pass input for the SignalWhat is a Signal?

A Signal is an asynchronous request to a Workflow Execution.

Learn more. 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.

Alias: y

Example

tctl batch start --query <value> --yes

list

The tctl batch list command lists all batch jobs.

tctl batch list <modifiers>

note

tctl-v1 can run batch and batch-v2 commands.

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.

Example

tctl batch list --pagesize <value>

describe

The tctl batch describe command describes the progress of a batch job.

tctl batch describe --job_id <id>

note

tctl can run batch and batch-v2 commands.

The following modifier controls the behavior of the command.

--job_id

Required modifier

Specify the job ID of a batch job.

Example

tctl batch describe --job_id <id>

terminate

The tctl batch terminate command terminates a batch job.

tctl batch terminate --job_id <id> <modifiers>

note

tctl-v1 can run batch and batch-v2 commands.

The following modifiers control the behavior of the command.

--job_id

Required modifier

Specify the job ID of a batch job.

Example

tctl batch terminate --job_id <id>

--reason

Specify a reason for terminating this batch job.

Example

tctl batch terminate --job_id <id> --reason <string>