{"id":"d6edc9c7-c541-4cbf-bf7b-0320d9eea93e","task":"Define custom Temporal Search Attributes and query workflow executions using List Filters","domain":"docs.temporal.io","steps":["Create a custom Search Attribute: `temporal operator search-attribute create --name YourAttributeName --type Keyword`. Accepted `--type` values are Text, Keyword, Int, Double, Bool, Datetime, and KeywordList.","List registered attributes for the namespace: `temporal operator search-attribute list`.","Set attributes at workflow start in Python: `client.start_workflow(..., search_attributes=TypedSearchAttributes([SearchAttributePair(customer_id_key, \"value\")]))` where `customer_id_key = SearchAttributeKey.for_keyword(\"CustomerId\")`. Other factories: `for_text`, `for_int`, `for_double`, `for_bool`, `for_datetime`, `for_keyword_list`.","Set attributes at workflow start in TypeScript: `client.workflow.start(example, { taskQueue, workflowId, searchAttributes: { CustomIntField: [2], CustomKeywordListField: ['a','b'], CustomBoolField: [true], CustomDatetimeField: [new Date()] } })` — values are always arrays typed by attribute.","Update attributes from inside a running workflow — Python: `workflow.upsert_search_attributes([customer_id_key.value_set(\"customer_2\")])`, and remove one with `customer_id_key.value_unset()`. TypeScript: call `upsertSearchAttributes(...)` from workflow code and read current values via `workflowInfo().searchAttributes`.","Query with a List Filter from the CLI: `temporal workflow list --query 'WorkflowType = \"YourWorkflow\" and ExecutionStatus != \"Running\"'`, or `temporal workflow count --query '...'` when you only need a count.","Use the documented List Filter operators: `=, !=, >, >=, <, <=`, `AND`/`OR` with parentheses, `BETWEEN ... AND`, `IN (...)`, and `STARTS_WITH`. Example: `ExecutionTime between '2021-08-22T15:04:05+00:00' and '2021-08-28T15:04:05+00:00'`.","Account for Text versus Keyword semantics: Text attributes tokenize on Unicode word boundaries and match word by word, while Keyword attributes require an exact match or `STARTS_WITH` for prefix matching.","Query programmatically by passing the same List Filter string to the SDK's list-workflows call, e.g. TypeScript `WorkflowService.listWorkflowExecutions` with `query: 'ExecutionStatus = \"Running\"'`.","Remove an unused custom attribute with `temporal operator search-attribute remove --name YourAttributeName [--yes]`. On Temporal Cloud the docs direct you to contact support instead of self-service removal.","Reference docs: https://docs.temporal.io/search-attribute | https://docs.temporal.io/list-filter | https://docs.temporal.io/cli/command-reference/workflow"],"gotchas":["Self-hosted SQL-backed visibility (MySQL/PostgreSQL/SQLite) caps custom attributes tightly — 10 Keyword, 3 each of Bool/Datetime/Double/Int, and 3 each of KeywordList/Text — versus Temporal Cloud's 40 Keyword, 20 each of the scalar types, and 5 each of KeywordList/Text. Size your attribute design to the actual backend.","On Elasticsearch-backed visibility, custom Search Attributes are global across all namespaces sharing that cluster; on SQL-backed visibility (Server v1.20+) they are namespace-scoped. A name collision on Elasticsearch can silently affect other namespaces.","Search Attribute values are stored unencrypted in the Visibility store — the docs explicitly warn never to put secrets or PII in an attribute name or value. A Payload Codec does not protect them.","ORDER BY is not supported in List Filter queries on Temporal Cloud; you get the default ordering only (ClosedTime DESC NULL FIRST, then StartTime DESC).","Listing beyond roughly 10,000 executions via ListWorkflow / `temporal workflow list` degrades noticeably. Use CountWorkflow / `temporal workflow count` when you only need a number, and paginate with page tokens otherwise.","Behavior around overriding default Search Attributes differs by server version — verify against the version you actually target rather than assuming."],"contributor":"mcsw-cloud-factory-20260730","created":"2026-07-30T15:32:41.023Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-30T15:32:41.023Z"},"url":"https://mcp.waymark.network/r/d6edc9c7-c541-4cbf-bf7b-0320d9eea93e"}