Question: does the azure_data_cosmos client manage the session token

[kate-goldenring]

I am having a hard time understanding whether i need to self manage the session token and set it on each request's ItemOptions or whether it is managed by the underlying client. Can you help me understand what the best practice is here and what versions of the SDK ST management is available (if any)?

[github-actions]

🎯 Agentic Issue Triage

Thank you for your feedback. Tagging and routing to the team members best able to assist. cc @Azure/azure-cosmos-rust-sdk

Summary: This is a question about whether the azure_data_cosmos client automatically manages Cosmos DB session tokens, or whether callers must manually propagate them via ItemOptions::with_session_token().

Current State of Session Token Handling

azure_data_cosmos (current SDK)

Session tokens are not automatically managed by the client. Users must manually:

1. Capture the session token from a response:

   let token = response.session_token(); // Returns Option<SessionToken>

2. Pass it on subsequent requests if session consistency is needed:

   let options = ItemOptions::default().with_session_token(token.unwrap());
   container_client.read_item(partition_key, id, Some(options)).await?;

The same applies to BatchOptions::with_session_token() and QueryOptions::with_session_token().

The client does handle retries when a "session token not available" (404/1002 sub-status) error occurs — the ClientRetryPolicy will retry the request on a different regional endpoint — but this is distinct from maintaining a session token cache across calls.

azure_data_cosmos_driver (new driver, in development)

The new driver also exposes session tokens via CosmosResponseHeaders::session_token and OperationOptions::with_session_token(), with the same manual propagation model.

References in source:

• sdk/cosmos/azure_data_cosmos/src/options/mod.rs — ItemOptions, QueryOptions, BatchOptions all have with_session_token()
• sdk/cosmos/azure_data_cosmos/src/models/cosmos_response.rs — CosmosResponse::session_token() to read from responses
• sdk/cosmos/azure_data_cosmos/src/retry_policies/client_retry_policy.rs — session_token_retry_count for retry-on-session-unavailable logic

Useful Resources

• [Azure Cosmos DB session consistency docs]((learn.microsoft.com/redacted)
• [How to manage session tokens]((learn.microsoft.com/redacted)

Potential Follow-up Tasks

• Confirm whether automatic session token management is planned for a future SDK version or the new driver
• If auto-management is not planned, improve documentation in ItemOptions, QueryOptions, and BatchOptions to make the manual propagation pattern clearer
• Consider adding a guide/example demonstrating session token best practices in the azure_data_cosmos crate

Generated by Agentic Triage for issue #4038 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5

[Pilchie]

Hi @kate-goldenring - the client doesn't yet automatically handle session tokens, but it is on our roadmap as part of #3523. @simorenoh - do you want to comment on the current state of that?

[simorenoh]

Hi @kate-goldenring - like @Pilchie pointed out, this is definitely in our roadmap and is currently being developed.

As of right now, we have made some internal changes for the underlying session token cache/ manager that will take care of this logic (#3902), so most of the heavy work is there. We are hashing out some more internal changes in regard to the way requests are handled within the SDK/transport, and as a part of that work we will also be linking the session token manager to the relevant data requests. These updates should be out soon - I can update here once they are released if you'd like.