What is a Search Attribute?
A Search Attribute is an indexed field used in a List Filter to filter a list of Workflow Executions that have the Search Attribute in their metadata.
If a Temporal Cluster does not have Elasticsearch integrated, but a Workflow Execution is spawned and tagged with Search Attributes, no errors occur. However, you won't be able to use Advanced Visibility List APIs and List Filters to find and list the Workflow Execution.
When using Continue-As-New or a Temporal Cron Job, Search Attributes are carried over to the new Workflow Run by default.
Search Attributes maximums
Default total maximum number of Search Attribute keys per Temporal Cluster is 100.
Default single Search Attribute value size limit is 2 KB.
Total Search Attribute size: 40 KB
Default Search Attributes
A Temporal Cluster that is integrated with Elasticsearch has a set of default Search Attributes already available. These Search Attributes are created when the initial index is created.
| NAME | TYPE | DEFINITION |
|---|---|---|
| WorkflowType | Keyword | The type of Workflow. |
| WorkflowId | Keyword | Identifies the Workflow Execution. |
| ExecutionStatus | Keyword | The current state of the Workflow Execution. |
| StartTime | Datetime | The time at which the Workflow Execution started. |
| CloseTime | Datetime | The time at which the Workflow Execution completed. |
| ExecutionTime | Datetime | Same as StartTime for the most cases but different for cron Workflows and retried Workflows. For them it is the time at which the Workflow Execution actually begin running. |
| RunId | Keyword | Identifies the current Workflow Execution Run. |
| ExecutionDuration | Int | The time needed to run the Workflow Execution. Available only for closed Workflows. |
| HistoryLength | Int | The number of events in the history of Workflow Execution. Available only for closed Workflows. |
| StateTransitionCount | Int | The number of times that Workflow Execution has persisted its state. Available only for closed Workflows. |
| TaskQueue | Keyword | Task Queue used by Workflow Execution. |
| TemporalChangeVersion | Keyword | If workflow versioning is enabled, list of change/version pairs will be stored here. |
| BinaryChecksums | Keyword | List of binary Ids of Workers that run the Workflow Execution. |
| BatcherNamespace | Keyword | Used by internal batcher to indicate the Namespace where batch operation was applied to. |
| BatcherUser | Keyword | Used by internal batcher to indicate the user who started the batch operation. |
All default Search Attributes are reserved and read-only. (You cannot create a custom one with the same name or alter the existing one.)
ExecutionStatus values correspond to Workflow Execution Statuses: Running, Completed, Failed, Canceled, Terminated, ContinuedAsNew, TimedOut.
StartTime, CloseTime, and ExecutionTime are stored as dates but are supported by queries that use either EpochTime in nanoseconds or a string in RFC3339Nano format (such as "2006-01-02T15:04:05.999999999Z07:00").
ExecutionDuration is stored in nanoseconds but is supported by queries that use integers in nanoseconds, Golang duration format, or "hh:mm:ss" format.
CloseTime, HistoryLength, StateTransitionCount, and ExecutionDuration are present only in a Closed Workflow Execution.
ExecutionTime can differ from StartTime in retry and cron use cases.
Custom Search Attributes
Custom Search Attributes can be added to a Temporal Cluster by using tctl search-attribute create.
Adding a Search Attribute makes it available to use with Workflow Executions within that Cluster.
There is no hard limit on the number of attributes you can add. However, we recommend enforcing the following limits:
- Number of Search Attributes: 100 per Workflow
- Size of each value: 2 KB per value
- Total size of names and values: 40 KB per Workflow
Due to Elasticsearch limitations, you can only add Search Attributes. It is not possible to rename Search Attributes or remove them from the index schema.
The temporalio/auto-setup Docker image uses a pre-defined set of custom Search Attributes that are handy for testing. Their names indicate their types:
- CustomBoolField
- CustomDatetimeField
- CustomDoubleField
- CustomIntField
- CustomKeywordField
- CustomTextField
Types
Search Attributes must be one of the following types:
- Bool
- Datetime
- Double
- Int
- Keyword
- Text
Note:
Double is backed up by
scaled_floatElasticsearch type with scale factor 10000 (4 decimal digits).Datetime is backed up by
datetype with milliseconds precision in Elasticsearch 6 anddate_nanostype with nanoseconds precision in Elasticsearch 7.Int is 64-bit integer (
longElasticsearch type).Keyword and Text types are concepts taken from Elasticsearch. Each word in a Text is considered a searchable keyword. For a UUID, that can be problematic because Elasticsearch indexes each portion of the UUID separately. To have the whole string considered as a searchable keyword, use the Keyword type. For example, if the key
ProductIdhas the value of2dd29ab7-2dd8-4668-83e0-89cae261cfb1:- As a Keyword it would be matched only by
ProductId = "2dd29ab7-2dd8-4668-83e0-89cae261cfb1. - As a Text it would be matched by
ProductId = 2dd8, which could cause unwanted matches.
- As a Keyword it would be matched only by
The Text type cannot be used in the "Order By" clause.
Search Attributes as Workflow Execution metadata
To actually have results from the use of a List Filter, Search Attributes must be added to a Workflow Execution as metadata. How to do this entirely depends on the method by which you spawn the Workflow Execution:
Search Attributes implementation
To implement Search Attributes, see the following examples.
Check for currently running Workflows
To check how many Workflows are currently running, you must set up the Advanced Visibility feature, which depends on an integration with Elasticsearch.
After you integrate Elasticsearch with your Temporal Cluster, you can get information into the visibility of your running Workflows.
Choose from any of the following methods to get visibility on your running Workflows.
Using tctl commands
You can get information about running Workflows by running one of the following tctl commands.
tctl workflow list --query "ExecutionStatus='Running'"
tctl workflow count --query "ExecutionStatus='Running'"
If you receive the following error message, you need to configure the Advanced Visibility feature.
Error: unable to count workflows: Operation not supported. Please use on Elasticsearch
('export TEMPORAL_CLI_SHOW_STACKS=1' to see stack traces)
For more information, see the tctl reference content.
Using APIs
Alternatively, you can use the following APIs with your Visibility Query.
We don’t recommend using the APIs with high-rate calls.
All lists from APIs are paginated.
Using SDKs
For information on checking the Visibility of a Workflow programmatically, see the Search Attributes section on the Observability page.