Skip to main content

List Filter

This page discusses List Filter.

What is a List Filter?​

The Visibility List API requires you to provide a List Filter as an SQL-like string parameter.

A List Filter includes Search Attribute names, Search Attribute values, and operators so that it can 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.

A List Filter using a time range provides a resolution of 1 ns on Elasticsearch and 1 µs for SQL databases.

Supported operators​

List Filters support the following operators:

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

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​

There are different options for partial string matching when the type of the Search Attribute is Text versus Keyword.

Text​

Search Attributes of type Text are broken up into words that match with the = operator.

For example, if you have a custom Text Search Attribute named Description with either of the following values—

my-business-id-foobar
my business id foobar

—then the following List Filter matches—

Description = 'foobar'

—but a partial word does not:

// Doesn't match
Description = 'foo'

Keyword​

For Search Attributes of type Keyword like WorkflowId, perform partial string matching using STARTS_WITH for prefixes and BETWEEN for suffixes.

  • WorkflowId STARTS_WITH "order-" matches Workflow Ids with the "order-" prefix, regardless of the following text.

    order-
    order-1234
    order-abracadabra
    order-~~~abracadabra

  • WorkflowId BETWEEN "order-" AND "order-~" matches Workflow Ids that have characters after order- with ASCII values lower than ~ (126, the highest-value printable character), such as the following:

    order-
    order-1234
    order-abracadabra

    It does not match order-~~.

Filter Composition Quick Reference

Composition

  • Data types:
    • String literals with single or double quotes
    • Numbers (Integer and Floating Point)
    • Booleans
  • Comparison: =, !=, >, >=, <, <=
  • Expressions/Operators:
    • IN array
    • BETWEEN value AND value
    • STARTS_WITH string
    • IS NULL, IS NOT NULL
    • expr AND expr, expr OR expr, ( expr )
  • Array: ( comma-separated-values )

Please note

  • Wrap attributes with backticks if it contains characters not in [a-zA-Z0-9].
  • STARTS_WITH is only available for Keyword search attributes.

Efficient API usage​

If the Advanced List Filter API retrieves a substantial number of Workflow Executions (more than 10,000), the response time might be longer.

Beginning with Temporal Server v1.20, you can employ the CountWorkflow API to efficiently count the number of Workflow Executions.

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.

List Filter examples​

Here are examples of List Filters set with the Temporal CLI:

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 you use the preceding example, you receive a list of Workflows fulfilling the following criteria:

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

The following are additional examples of List Filters.

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>'