Separate standard and advanced Visibility deprecated
Support for separate standard and advanced Visibility setups will be deprecated from Temporal Server v1.21 onwards.
Temporal · Concepts · all subjects
visibility
60 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Dual Visibility configuration keys
Primary Visibility store is set with the `visibilityStore` configuration key in your Temporal Service. Secondary Visibility store is set with the `secondaryVisibilityStore` configuration key in your Temporal Service.
Dual Visibility allowed primary and secondary store combinations
The following combinations are allowed in a Dual Visibility setting: (1) Primary: Standard (Cassandra or SQL), Secondary: Advanced (SQL or Elasticsearch); (2) Primary: Advanced (SQL), Secondary: Advanced (SQL); (3) Primary: Advanced (Elasticsearch), Secondary: Advanced (Elasticsearch).
Dual Visibility read and write behavior
With Dual Visibility, you can read from only one Visibility store at a time. You can configure your Temporal Service to write to primary only, secondary only, or to both primary and secondary Visibility stores.
Dual Visibility purpose and use cases
Dual Visibility is a feature that lets you set a secondary Visibility store in addition to a primary store in your Temporal Service. It can be used to migrate your Visibility database or create a backup Visibility store.
Dual Visibility migration strategy
When migrating from one Visibility store database to another, set up the database you want to migrate to as your secondary Visibility store. Dynamic configuration keys help you transition your read and write operations from the primary to the secondary Visibility store.
Text Search Attribute search matching behavior
The = operator on Text Search Attributes uses OR matching: the query string is tokenized using the same rules as the indexed values, and a result is returned if any query token matches any indexed token. For example, a query like = "processing-v2" is split into processing and v2, matching any workflow that contains either token.
Text Search Attribute partial matching limitation
Text Search Attributes only match complete tokens. Partial word matches do not work. For example, if the value is my-business-id-foobar, the query Description = 'foobar' matches because foobar is a complete token, but Description = 'foo' does not match because foo is only a partial token.
Keyword Search Attribute for structured strings
If you need exact matching on identifiers, UUIDs, or other structured strings, use Keyword type instead of Text. Text Search Attributes support word-level search, not exact matching.
Keyword Search Attribute partial matching with STARTS_WITH
For Search Attributes of type Keyword like WorkflowId, use STARTS_WITH to match prefixes. Example: WorkflowId STARTS_WITH "order-" matches Workflow Ids with the "order-" prefix regardless of following text.
Keyword Search Attribute partial matching with BETWEEN
For Search Attributes of type Keyword, use BETWEEN to match suffixes. Example: WorkflowId BETWEEN "order-" AND "order-~" matches Workflow Ids that have characters after "order-" with ASCII values lower than ~ (126). This matches "order-1234" and "order-abracadabra" but not "order-~~".
List Filter composition syntax
List Filters support the following data types: String literals with single or double quotes, Numbers (Integer and Floating Point), and Booleans. Comparison operators are =, !=, >, >=, <, <=. Expressions/Operators include IN array, BETWEEN value AND value, STARTS_WITH string, IS NULL, IS NOT NULL, and logical operators expr AND expr, expr OR expr, and (expr). Arrays are defined as (comma-separated-values). Wrap attributes with backticks if they contain characters not in [a-zA-Z0-9].
CountWorkflow API for large result sets
Beginning with Temporal Server v1.20, the CountWorkflow API can be employed to efficiently count the number of Workflow Executions. If the Advanced List Filter API retrieves a substantial number of Workflow Executions (more than 10,000), the response time might be longer.
ListWorkflow API pagination
To paginate the results using the ListWorkflow API, use the page token to retrieve the next page. Continue until the page token becomes null/nil.
Search Attribute aliasing for default attributes
Temporal prefixes most default Search Attributes with "Temporal" to avoid naming conflicts with custom Search Attributes. Temporal supports aliasing which lets you use the non-prefixed name of a default Search Attribute. For example, the default Search Attribute TemporalWorkflowVersioningBehavior has the alias WorkflowVersioningBehavior. If you haven't defined a custom Search Attribute with that name, you can use either name in a List Filter.
Search Attribute aliasing requires Temporal Server v1.30+
Search Attribute aliasing requires Temporal Server version 1.30 and greater.
Search Attribute resolution order with aliasing
When resolving a Search Attribute in a List Filter, Temporal Server checks for matches in the following order: 1) Custom Search Attributes defined in the current Namespace, 2) Default Search Attributes. If you define a custom Search Attribute with the same name as the alias of a default Search Attribute, the non-Temporal prefixed name will refer to your custom attribute. You can still search with the default Search Attribute by using the Temporal prefix.
List Filter example with multiple conditions
Example: 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") retrieves workflows where the Workflow Type is main.YourWorkflowDefinition, the workflow isn't in a running state, and the workflow either started after the specified time or closed after the specified time.
List Filter examples with various operators
Examples of List Filter syntax: WorkflowId = '<workflow-id>', WorkflowId = '<workflow-id>' or WorkflowId = '<another-workflow-id>', WorkflowId IN ('<workflow-id>', '<another-workflow-id>'), 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', WorkflowType STARTS_WITH '<workflow-type-prefix>'.
List Filter definition and purpose
The Visibility List API requires a List Filter as an SQL-like string parameter. A List Filter includes Search Attribute names, Search Attribute values, and operators to retrieve a filtered list of Workflow Executions from the Visibility Store. List Filter Search Attribute names are case sensitive. A single Namespace scopes each List Filter.
List Filter time range resolution
A List Filter using a time range provides a resolution of 1 nanosecond on Elasticsearch and 1 microsecond for SQL databases.
Supported List Filter operators
List Filters support the following operators: =, !=, >, >=, <, <=, AND, OR, (), BETWEEN ... AND, IN, and STARTS_WITH.
ORDER BY operator support and default ordering
The ORDER BY operator is currently not supported in Temporal Cloud. The default ordering is ClosedTime DESC NULL FIRST, StartTime DESC. Custom Search Attributes of the Text type cannot be used in ORDER BY clauses.
Text Search Attribute tokenization rules
Text Search Attributes use the Elasticsearch standard analyzer which applies Unicode word boundary rules to split values into tokens. All tokens are lowercased. Most punctuation and whitespace act as delimiters. Underscores, dots, colons, and apostrophes do not split when they appear between two letters or between two digits. Dots and colons between digits also stay connected (e.g., v1.2.3 is one token). However, a dot or colon between a digit and a letter does split (e.g., v1.ProcessOrder produces v1 and processorder).
Default Search Attributes ExecutionStatus values
ExecutionStatus Search Attribute values correspond to Workflow Execution statuses: Running, Completed, Failed, Canceled, Terminated, ContinuedAsNew, TimedOut.
Search Attribute definition and purpose
A Search Attribute is an indexed field used in a List Filter to filter Workflow Executions based on metadata. Each Search Attribute is a key-value pair metadata object included in a Workflow Execution's Visibility information, stored in the Visibility store.
Search Attributes security warning: no encryption, no PII
Search Attribute values are stored unencrypted in the Visibility store and are not processed by custom Payload Codec. Do not include sensitive data, secrets, or personally identifiable information (PII) in Search Attribute names or values. The Temporal Server must read these values in plain text to support filtering and ordering, making encryption impossible without breaking search functionality. Attribute names are visible in Namespace configuration, query expressions, and Temporal UI.
Search Attributes with Continue-As-New and Cron Jobs
When using Continue-As-New or a Temporal Cron Job, Search Attribute keys are carried over to the new Workflow Run by default. Search Attribute values are only available for as long as the Workflow is.
Default Search Attributes table
Default Search Attributes include: BatcherUser (Keyword), CloseTime (Datetime), ExecutionDuration (Int, nanoseconds), ExecutionStatus (Keyword), ExecutionTime (Datetime), HistoryLength (Int), HistorySizeBytes (Long), RunId (Keyword), StartTime (Datetime), StateTransitionCount (Int), TaskQueue (Keyword), TemporalChangeVersion (Keyword List), TemporalReportedProblems (Keyword List), TemporalScheduledStartTime (Datetime), TemporalScheduledById (Keyword), TemporalSchedulePaused (Boolean), TemporalUsedWorkerDeploymentVersions (Keyword List), TemporalWorkerDeployment (Keyword), TemporalWorkerDeploymentVersion (Keyword), TemporalWorkflowVersioningBehavior (Keyword), WorkflowId (Keyword), WorkflowType (Keyword). All are reserved and read-only. BinaryChecksums and BuildIds are deprecated since server 1.21 and 1.31 respectively.
Default Search Attributes time formats
StartTime, CloseTime, and ExecutionTime are stored as dates but are supported by queries using 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 using integers in nanoseconds, Golang duration format, or 'hh:mm:ss' format.
Default Search Attributes only available on closed Workflows
CloseTime, HistoryLength, StateTransitionCount, and ExecutionDuration are present only in a closed Workflow Execution.
Default Search Attributes usage with and without advanced Visibility
Without advanced Visibility, you can only use the '=' operator with a single default Search Attribute in a List Filter, for example: temporal workflow list --query "ExecutionStatus = 'Completed'". With advanced Visibility, you can combine default Search Attributes using logical operators and comparisons like !=, >, <, for example: temporal workflow list --query "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 availability by Visibility store
Without advanced Visibility, custom Search Attributes cannot be used in List Filters. With advanced Visibility and Temporal Server v1.19 and earlier, Elasticsearch integration is required. With Temporal Server v1.20 and later, custom Search Attribute capabilities are available on MySQL (v8.0.17 or later), PostgreSQL (v12 and later), SQLite (v3.31.0 and later), and Elasticsearch.
Custom Search Attributes namespace scope
If using Elasticsearch, custom Search Attributes apply globally and can be used across Namespaces. If using any supported SQL database with Temporal Server v1.20 and later, custom Search Attributes are associated with a specific Namespace and can be used only for Workflow Executions in that Namespace.
Custom Search Attributes supported types
Custom Search Attributes must be one of the following types: Bool, Datetime, Double, Int, Keyword, KeywordList, or Text. Double is backed by scaled_float Elasticsearch type with scale factor 10000 (4 decimal digits). Datetime is backed by date type with milliseconds precision in Elasticsearch 6 or date_nanos type with nanoseconds precision in Elasticsearch 7. Int is 64-bit integer (long Elasticsearch type). With Temporal Server v1.19 and earlier, Keyword can store a list of values. With Temporal Server v1.20 and later, Keyword supports only a single value; use KeywordList to store multiple values.
List-of-values deprecation for non-list Search Attribute types
Storing a list of values in any single-value Search Attribute type — for example, multiple strings in a Keyword or Text attribute, or multiple integers in an Int attribute — is deprecated. KeywordList is the only type designed to store a list of values. New namespaces on Temporal Cloud are blocked from using this pattern. Existing Namespaces must migrate before Sep. 30, 2026. After that date, Workflow Executions with invalid Search Attribute values will fail. For Keyword, migrate to KeywordList. For Int, migrate to KeywordList (storing integers as strings) or split into multiple individual Int attributes. For Text, concatenate list values into a single space-delimited string or migrate to KeywordList.
Search Attribute string types: Keyword vs KeywordList vs Text
Use Keyword for exact matching on a single value — workflow type names, UUIDs, hyphenated IDs, dotted class names, file paths, enum values. Keyword stores the value as-is and supports =, !=, IN, STARTS_WITH, BETWEEN, and ORDER BY. Use KeywordList when storing multiple values on a single attribute — tags, labels, categories. KeywordList supports =, !=, and IN. Use Text only for free-form, human-readable content with word-level search — descriptions, notes, error messages. Text tokenizes values into individual words and uses OR matching with the = operator. Most custom Search Attributes store structured identifiers, so Keyword is the right default choice.
Text Search Attribute limitation
The Text type cannot be used in the Order By clause.
Custom Search Attributes limits by database type
Maximum number of custom Search Attributes per Namespace: MySQL (v8.0.17+), PostgreSQL (v12+), and SQLite (v3.31.0+) support 3 Bool, 3 Datetime, 3 Double, 3 Int, 10 Keyword, 3 KeywordList, 3 Text. Temporal Cloud supports 20 Bool, 20 Datetime, 20 Double, 20 Int, 40 Keyword, 5 KeywordList, 5 Text. Temporal does not impose a limit with Elasticsearch, but Elasticsearch sets a default mapping limit. Custom Search Attributes are not supported on Cassandra.
Custom Search Attributes size limits
The default single Search Attribute value size limit is 2 KB. The maximum total Search Attribute size is 40 KB. The maximum total characters per Search Attribute value is 255.
DescribeWorkflowExecution vs Visibility queries
Visibility is built for finding and filtering across many executions, not for reading the current state of one execution. When you need the authoritative, up-to-date state of a specific Workflow Execution, use DescribeWorkflowExecution instead of a Visibility query.
List Filter and Search Attributes in Visibility
Visibility enables the listing, filtering, and sorting of Workflow Executions through a custom SQL-like List Filter. Visibility supports custom Search Attributes for user-defined filtering beyond the default system attributes.
Count API with GROUP BY support
The Count API feature lets you count the number of Workflows that match a given query. The GROUP BY clause is only supported in the Count API and currently only grouping by ExecutionStatus is supported. The Count API returns approximate counts.
Operations that use Visibility index
Operations that use Visibility include: Workflow search and count via ListWorkflowExecutions, ScanWorkflowExecutions, and CountWorkflowExecutions; Schedule list and count via ListSchedules and CountSchedules; Batch operations via ListBatchOperations; Worker task-queue reachability via GetWorkerTaskReachability and DescribeTaskQueue with reachability requested. These operations share the Visibility rate limit and eventual-consistency behavior. Operations that look up a single entity by ID, such as DescribeWorkflowExecution and DescribeSchedule, do not use Visibility.
Visibility eventual consistency and data freshness
Visibility is a search index that Temporal updates asynchronously. After a change is recorded, it takes some time to propagate to the index, so a List or Count query can briefly return stale results. The propagation delay is variable and usually fast but can be several seconds or longer. Temporal Cloud does not publish an SLA for how quickly changes become visible. Treat Visibility as eventually consistent and avoid depending on a fixed or guaranteed delay.
When to use Visibility
Visibility is intended for operational discovery and search: finding, filtering, and counting executions for monitoring, tooling, dashboards, and investigation. Use it when you want to search or filter executions by Search Attribute in the UI, CLI, or an operational tool, or when you want to count or sample executions for reporting.
Visibility definition and purpose
Visibility within the Temporal Platform refers to the subsystems and APIs that enable an operator to view, filter, and search for Workflow Executions that currently exist within a Temporal Service.
When not to use Visibility
Do not use Visibility to check whether a specific workflow exists (instead start it and handle the already-started result, or look it up by ID with DescribeWorkflowExecution). Do not use it to react to a workflow's progress or completion (instead follow its Event History or model dependent work as child workflows). Do not use it to coordinate between workflows from inside workflow or activity code (instead use signals, updates, or child workflows).
Legacy standard Visibility deprecation
Prior to Temporal Server v1.20, Temporal had two Visibility modes: standard and advanced. Standard Visibility supported only predefined filters such as Workflow Type, Workflow Id, Run Id, and Execution Status, without custom Search Attributes. Advanced Visibility required Elasticsearch. Starting with Temporal Server v1.20, advanced Visibility became available on SQL databases. Standard Visibility was deprecated in v1.21 and removed in v1.24. All current deployments use what was formerly called advanced Visibility.
Visibility store role in persistence
The Visibility store in a Temporal Service stores persisted Workflow Execution Event History data and is set up as part of the Persistence store to enable listing and filtering details about Workflow Executions.
Dual Visibility migration support
Starting with Temporal Server v1.21, Dual Visibility can be set up to migrate the Visibility store from one database to another.
Visibility database support versions
Visibility is available on SQL databases (MySQL v8.0.17+, PostgreSQL v12+) with Temporal Server v1.20 and later. It is available on Elasticsearch (v7+ with Temporal Server v1.7+, v8 with Temporal Server v1.18+) and OpenSearch (2+ with Temporal Server v1.30.1+). On Temporal Cloud, Visibility is enabled by default for all users.
Build ID reachability check command
The Temporal CLI command `temporal task-queue get-build-id-reachability` determines, for each Task Queue, whether a Build ID is unreachable, only reachable by closed Workflows, or reachable by open and new Workflows. For example: `temporal task-queue get-build-id-reachability --build-id "2.0"` shows if Build ID 2.0 is reachable by new Workflows and existing Workflows.
Build ID reachability via SDK API
The API `GetWorkerTaskReachability` can be used directly from within language SDKs to determine whether a Build ID is still in use by open or closed Workflows.
ListSchedules and CountSchedules visibility properties
ListSchedules and CountSchedules are served by the Visibility subsystem. They share the Visibility API rate limit and are eventually consistent, so a newly created or deleted schedule may not appear in the list right away.
Paused Workflow observability with ExecutionStatus
Paused Workflow Executions have ExecutionStatus="Paused". You can find Paused Workflow Executions with the List Filter: ExecutionStatus = "Paused".
ActivityClient.listExecutions() for Standalone Activities
Use client.listExecutions(listFilterQuery) to list Standalone Activity Executions that match a List Filter query. The result is a Stream<ActivityExecutionMetadata> that fetches pages from the server on demand as the stream is consumed. These APIs return only Standalone Activity Executions; Activities running inside Workflows are not included. The query parameter accepts the same List Filter syntax used for Workflow Visibility.
ActivityClient.countExecutions() for Standalone Activities
Use client.countExecutions(listFilterQuery) to count Standalone Activity Executions that match a List Filter query. This returns the total count of executions (running, completed, failed, etc.) — not the number of queued tasks. It works the same way as counting Workflow Executions.
Standalone Activities example with listExecutions
client .listExecutions("TaskQueue = '" + TASK_QUEUE + "'") .forEach( info -> System.out.printf( "ActivityID: %s, Type: %s, Status: %s%n", info.getActivityId(), info.getActivityType(), info.getStatus())); This example shows how to list Standalone Activity Executions matching a List Filter query.
Standalone Activities example with countExecutions
ActivityExecutionCount resp = client.countExecutions("TaskQueue = '" + TASK_QUEUE + "'"); System.out.println("Total activities: " + resp.getCount()); resp.getGroups() .forEach( group -> System.out.println("Group " + group.getGroupValues() + ": " + group.getCount())); This example shows how to count Standalone Activity Executions matching a List Filter query and group the results.