Skip to main content

Visibility

This guide provides a comprehensive overview of Temporal Visibility.

The term Visibility, within the Temporal Platform, refers to the subsystems and APIs that enable an operator to view Workflow Executions that currently exist within a Cluster.

Standard Visibility​

Standard Visibility, within the Temporal Platform, is the subsystem and APIs that list Workflow Executions by a predefined set of filters.

Open Workflow Executions can be filtered by a time constraint and either a Workflow Type, Workflow Id, or Run Id.

Closed Workflow Executions can be filtered by a time constraint and either a Workflow Type, Workflow Id, Run Id, or Execution Status (Completed, Failed, Timed Out, Terminated, Canceled, or Continued-As-New).

Advanced Visibility​

Advanced Visibility, within the Temporal Platform, is the subsystem and APIs that enable the listing, filtering, and sorting of Workflow Executions through a custom SQL-like List FilterLink preview iconWhat 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.

List Filter​

A List Filter is the SQL-like string that is provided as the parameter to a VisibilityLink preview iconWhat is Visibility?

The term Visibility, within the Temporal Platform, refers to the subsystems and APIs that enable an operator to view Workflow Executions that currently exist within a Cluster.

Learn more List API.

A List Filter contains Search AttributeLink preview iconWhat 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 names, Search Attribute values, and operators to pull a filtered list of Workflow Executions from the Visibility store.

List Filter Search AttributeLink preview iconWhat 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 names are case sensitive, and each List Filter is scoped by a single NamespaceLink preview iconWhat is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

Learn more.

A List Filter that uses a time range has a resolution of 1 ns on ElasticsearchLink preview iconHow to integrate Elasticsearch into a Temporal Cluster

To integrate Elasticsearch with your Temporal Cluster, edit the persistence section of your development.yaml configuration file and run the index schema setup commands.

Learn more and 1 µs for SQL databasesLink preview iconHow to set up Visibility in a Temporal Cluster

Visibility storage is set up as a part of your Persistence store to enable listing and filtering details about Worklfow Executions that exist on your Temporal Cluster.

Learn more.

Supported operators​

A List Filter contains Search AttributeLink preview iconWhat 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 names, Search Attribute values, and the following supported operators:

  • =, !=, >, >=, <, <=
  • AND, OR, ()
  • BETWEEN ... AND
  • IN
  • ORDER BY

The ORDER BY operator is supported only when Elasticsearch is used as the Visibility store.

The ORDER BY operator is currently not supported in Temporal Cloud.

Custom Search Attributes of the Text type cannot be used in ORDER BY clauses.

Partial string match​

The = operator works like CONTAINS to find Workflows with Search Attributes that contain a specific word.

For example, if you have a custom Search Attribute named Description of Text type with the value of "The quick brown fox jumps over the lazy dog", searching for Description='quick' or Description='fox' will successfully return the Workflow. However, partial word searches such as Description='qui' or Description='laz' will not return the Workflow. This is because Elasticsearch's tokenizer is configured to return complete words as tokens.

Efficient API usage​

An Advanced List Filter API may take longer to respond if it is retrieving a large number of Workflow Executions (over 10,000).

With Temporal Server v1.20 and later, you can use the CountWorkflow API to efficiently count the number of Workflow ExecutionsLink preview iconWhat 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.

Learn more.

Paginate the results with the ListWorkflow API by using the page token to retrieve the next page; continue until the page token is null/nil.

List Filter examples​

The following is a List Filter set with tctlLink preview icontctl workflow list

How to list open or closed Workflow Executions using tctl.

Learn more:

WorkflowType = "main.YourWorkflowDefinition" and ExecutionStatus != "Running" and (StartTime > "2021-06-07T16:46:34.236-08:00" or CloseTime > "2021-06-07T16:46:34-08:00")

When used, a list of Workflows that meet the following conditions are returned:

  • The Workflow Type is set to main.YourWorkflowDefinition.
  • The Workflow isn't running.
  • The Workflow either started after "2021-06-07T16:46:34.236-08:00" or closed after "2021-06-07T16:46:34-08:00".

More List Filter examples have been provided below.

WorkflowId = '<workflow-id>'
WorkflowId = '<workflow-id>' or WorkflowId = '<another-workflow-id>'
WorkflowId IN ('<workflow-id>', '<another-workflow-id>')
WorkflowId = '<workflow-id>' order by StartTime desc
WorkflowId = '<workflow-id>' and ExecutionStatus = 'Running'
WorkflowId = '<workflow-id>' or ExecutionStatus = 'Running'
WorkflowId = '<workflow-id>' and StartTime > '2021-08-22T15:04:05+00:00'
ExecutionTime between '2021-08-22T15:04:05+00:00' and '2021-08-28T15:04:05+00:00'
ExecutionTime < '2021-08-28T15:04:05+00:00' or ExecutionTime > '2021-08-22T15:04:05+00:00'
order by ExecutionTime
order by StartTime desc, CloseTime asc
order by CustomIntField asc

Search Attribute​

A Search Attribute is an indexed field used in a List FilterLink preview iconWhat 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 to filter a list of Workflow Executions that have the Search Attribute in their metadata.

Each Search Attribute is a key-value pair metadata object and is part of the Workflow Execution visibility information, stored in the Visibility store. Use Search Attributes for metadata and search purposes only, not business logic.

Temporal provides some default Search Attributes, such as ExecutionStatus of your Workflow Execution. You can also create custom Search Attribute keys in your Visibility store and assign values in a Workflow Execution.

Search Attribute values are assigned to a specific Workflow Execution and are available for that execution only for the duration of the specified Namespace Retention PeriodLink preview iconWhat is a Retention Period?

A Retention Period is the amount of time a Workflow Execution Event History remains in the Cluster's persistence store.

Learn more.

Note that Search Attribute values are not encrypted because the Temporal Server must be able to read these values from the Visibility store when retrieving Workflow Execution details.

When using Continue-As-NewLink preview iconWhat is Continue-As-New?

Continue-As-New is the mechanism by which all relevant state is passed to a new Workflow Execution with a fresh Event History.

Learn more or a Temporal Cron JobLink preview iconWhat is a Temporal Cron Job?

A Temporal Cron Job is the series of Workflow Executions that occur when a Cron Schedule is provided in the call to spawn a Workflow Execution.

Learn more, Search Attributes are carried over to the new Workflow Run by default.

Default Search Attributes​

A Temporal Cluster has a set of default Search Attributes already available. Default Search Attributes are set globally in any Namespace. These Search Attributes are created when the initial index is created.

NAMETYPEDEFINITION
WorkflowTypeKeywordThe type of Workflow.
WorkflowIdKeywordIdentifies the Workflow Execution.
ExecutionStatusKeywordThe current state of the Workflow Execution.
StartTimeDatetimeThe time at which the Workflow Execution started.
CloseTimeDatetimeThe time at which the Workflow Execution completed.
ExecutionTimeDatetimeSame 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.
RunIdKeywordIdentifies the current Workflow Execution Run.
ExecutionDurationIntThe time needed to run the Workflow Execution. Available only for closed Workflows.
HistoryLengthIntThe number of events in the history of Workflow Execution. Available only for closed Workflows.
StateTransitionCountIntThe number of times that Workflow Execution has persisted its state. Available only for closed Workflows.
TaskQueueKeywordTask Queue used by Workflow Execution.
TemporalChangeVersionKeywordIf Workflow versioning is enabled, list of change/version pairs will be stored here.
BinaryChecksumsKeywordList of binary Ids of Workers that run the Workflow Execution.
BatcherNamespaceKeywordUsed by internal batcher to indicate the Namespace where batch operation was applied to.
BatcherUserKeywordUsed 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.

You can use the default Search Attributes in a List Filter, such as in the Temporal Web UI or with the tctl workflow list commands, under the following conditions:

  • Without Advanced Visibility, you can only use the = operator with a single default Search Attribute in your List Filter. For example: tctl workflow list -q "ExecutionStatus = 'Completed'" or tctl workflow list -q "WorkflowType = 'YourWorkflow'".
  • With Advanced Visibility, you can combine default Search Attributes in a List Filter to get a list of specific Workflow Executions. For example: tctl workflow list -q "WorkflowType = 'main.YourWorkflowDefinition' and ExecutionStatus != 'Running' and (StartTime > '2022-06-07T16:46:34.236-08:00' or CloseTime < '2022-06-08T16:46:34-08:00')"

Custom Search Attributes​

You can create custom Search AttributesLink preview iconHow to create custom Search Attributes

Add custom Search Attributes to your Visibility store using tctl for self-hosted Temporal Cluster, and tcld for Temporal Cloud.

Learn more with unique key names that are relevant to your business needs.

Use custom Search Attributes in a List Filter, such as in the Temporal Web UI or with the tctl workflow list commands, under the following conditions:

If you use Elasticsearch as your Visibility store, your custom Search Attributes apply globally and can be used across Namespaces. However, if using any of the supported SQL databases with Temporal Server v1.20 and later, your custom Search Attributes are associated with a specific Namespace and can be used for Workflow Executions in that Namespace.

See custom Search Attributes limits for limits on the number and size of custom Search Attributes you can create.

Supported types​

Custom Search Attributes must be one of the following types:

  • Bool
  • Datetime
  • Double
  • Int
  • Keyword
  • KeywordList
  • Text

Note:

  • Double is backed up by scaled_float Elasticsearch type with scale factor 10000 (4 decimal digits).
  • Datetime is backed up by date type with milliseconds precision in Elasticsearch 6 and date_nanos type with nanoseconds precision in Elasticsearch 7.
  • Int is 64-bit integer (long Elasticsearch 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 ProductId has the value of 2dd29ab7-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.
  • With Temporal Server v1.19 and earlier, the Keyword type can store a list of values.
  • With Temporal Server v1.20 and later, the Keyword type supports only a single value. To store a list of values, use KeywordList.
  • The Text type cannot be used in the "Order By" clause.

Custom Search Attributes limits​

The following table lists the maximum number of custom Search Attributes you can create per Namespace by supported Visibility database.

Search Attribute typeMySQL (v8.0.17 and later)PostgreSQL (v12 and later)SQLite (v3.31.0 and later)Temporal Cloud
Bool33320
Datetime33320
Double33320
Int33320
Keyword10101020
KeywordList33320
Text3335

Temporal does not impose a limit on the number of custom Search Attributes you can create with Elasticsearch. However, Elasticsearch sets a default mapping limit that may apply. Custom Search Attributes are an Advanced Visibility feature and are not supported on Cassandra.

Size limits for a custom Search Attribute:

  • The default single Search Attribute value size limit is 2 KB.
  • The maximum total Search Attribute size is 40 KB.

Usage​

Search Attributes available in your Visibility store can be used with Workflow Executions for that Cluster. To actually have results from the use of a List FilterLink preview iconWhat 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, Search Attributes must be added to a Workflow Execution as metadata.

With Workflows you can do the following:

After you add and set your Search Attributes, use your default or custom Search Attributes in a List Filter.