EDU-3817: Use value_set/unset to update search attributes

[EddieWhi]

What does this PR do?

Update the docs for updating python search attributes.

Notes to reviewers

Stumbled across this issue when trying this out for the first time and deprecated method didn't cleanly validate through pyright. Assume this is the official mechanism for updating search attributes in python now?

[CLAassistant]

All committers have signed the CLA.

[EddieWhi]

Thanks for picking this up and tidying @fairlydurable :)

[kevinawoo]

@EddieWhi workflow.upsert_search_attributes doc says:

The dictionary form of attributes is DEPRECATED and if used, result in invalid key types on the typed_search_attributes property in the info. 🔗python-sdk

So that means doing something like this is deprecated:

workflow.upsert_search_attributes({"CustomKeywordField": ["new-value"]})

However these methods aren't deprecated:

• TypedSearchAttributes
• SearchAttributePair

I wonder if pyright is incorrectly reporting this? I couldn't reproduce the deprecation warning with pyright 0.8.0 installed in PyCharm.

[EddieWhi]

@EddieWhi workflow.upsert_search_attributes doc says:

The dictionary form of attributes is DEPRECATED and if used, result in invalid key types on the typed_search_attributes property in the info. 🔗python-sdk

So that means doing something like this is deprecated:

workflow.upsert_search_attributes({"CustomKeywordField": ["new-value"]})

However these methods aren't deprecated:

* [TypedSearchAttributes](https://github.com/temporalio/sdk-python/blob/acde42cc15e153a6e4eeff0ef347a58622d49d6a/temporalio/common.py#L439-L440)

* [SearchAttributePair](https://github.com/temporalio/sdk-python/blob/acde42cc15e153a6e4eeff0ef347a58622d49d6a/temporalio/common.py#L401-L402)

I wonder if pyright is incorrectly reporting this? I couldn't reproduce the deprecation warning with pyright 0.8.0 installed in PyCharm.

For reference, I ran the test using pyright v1.1.393 and python 3.12.3

Sorry if my original message wasn't clear. Explicitly, if I copy paste the example from the existing docs i.e. :

        customer_id_key = SearchAttributeKey.for_keyword("CustomerId")
        workflow.upsert_search_attributes(TypedSearchAttributes([
            SearchAttributePair(customer_id_key, "customer_2")
        ]))

I get the following from pyright:

error: Argument of type "TypedSearchAttributes" cannot be assigned to parameter "attributes" of type "SearchAttributes | Sequence[SearchAttributeUpdate[Unknown]]" in function "upsert_search_attributes"
    Type "TypedSearchAttributes" is not assignable to type "SearchAttributes | Sequence[SearchAttributeUpdate[Unknown]]"
      "TypedSearchAttributes" is not assignable to "Mapping[str, SearchAttributeValues]"
      "TypedSearchAttributes" is not assignable to "Sequence[SearchAttributeUpdate[Unknown]]" (reportArgumentType)

Although (from memory as I haven't taken the time to test again) it does actually work when run.

For completeness, I tried the deprecated dictionary form you mentioned above (workflow.upsert_search_attributes({"CustomKeywordField": ["new-value"]})) and that validates just fine for me too.

Hope that helps in some way.

[fairlydurable]

Hi all! Just checking in for a status check on this ticket...

[AlmogBaku]

arrrghhh took me 2h until I landed on this!

LGTM

[AlmogBaku]

Im still not sure how to set attributes with the new notation when start_child_workflow or start_workflows... the code in the documentation seems broken

@fairlydurable

[vercel]

@fairlydurable is attempting to deploy a commit to the Temporal Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
temporal-documentation	Ready	Preview	Comment	Nov 24, 2025 8:39pm

[jsundai]

Thank you, @EddieWhi - looks great! 🎉The code example given seems to use the correct typed pattern (value_set() / value_unset()), which is the preferred approach.

Perhaps the dict-style call still type-checks and runs because it’s not programmatically marked as deprecated, but the Temporal Python SDK mark it as such in favor of the typed approach. Might need to do a docs sweep for any other non-typed forms in a separate PR.