Skip to content

[cosmos] Add docs on transport configuration for CosmosClient #26757

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

[cosmos] Add docs on transport configuration for CosmosClient #26757

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9c52521
Add docs on transport configuration for CosmosClient
inirudebwoy Oct 11, 2022
8c9d9c9
Update sdk/cosmos/azure-cosmos/README.md
inirudebwoy Oct 12, 2022
d5f5e7d
fixup! Add docs on transport configuration for CosmosClient
inirudebwoy Oct 12, 2022
49537c1
Merge branch 'main' of github.com:inirudebwoy/azure-sdk-for-python
inirudebwoy Oct 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions sdk/cosmos/azure-cosmos/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -581,6 +581,26 @@ def integrated_cache_snippet():
```
For more information on Integrated Cache, see [Azure Cosmos DB integrated cache - Overview][cosmos_integrated_cache].

### Configuring network transport

CosmosDB SDK under the hood is using `requests` library as a network transport. In case you would like to change it's settings you may pass it into `CosmosClient` constructor or `from_connection_string` class method.

For example if you would like to alter connection pool you can initialise `RequestsTransport` with an instance of `requests.Session`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be specified that this is the case for the synchronous client.
The async client by default uses the AiohttpTransport.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could add a note here that if one takes this approach, they are forfeiting any default configuration of the Session that the SDK might be doing (for example, the current Core implementation will disable the requests retry policy in favour of the Azure SDK retry policy, otherwise both retry policies will come into play and may change the error behaviour)

Another note to make is that by default, passing a Session into the Transport like this means that the user forfeits ownership of that session, in other words, the transport will decide when that connection should be closed. There is an additional flag that can be set to disable that and return responsibility for closing the Session to the user:
RequestsTransport(session=session, session_owner=False)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you so much @annatisch for reviewing my PR. Cool, I hope I have done a good job applying your comments.
Do you think this is a good sync client example, or should I add something more?
Do you want me to add async example as well here? or maybe add something to /sample dir?

This questions is a bit longer but since SDK gives a lot of goodies for free, why isn't there an easier/safer way to modify the connection pool? Reason I'm going through all of this is that 10 connections is not enough for my use case. I'd like to change only that but keep all the good stuff. Is it a wrong approach I have taken? or is it the only approach?


```Python
from azure.cosmos import CosmosClient
import requests
session = requests.Session()
adapter = requests.adapters.HTTPAdapter(pool_connections=42, pool_maxsize=42)
session.mount('https://', adapter)
cosmos_client = CosmosClient.from_connection_string(
COSMOS_CONNECTION_STRING,
transport=RequestsTransport(session=session)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we include the import statement for RequestsTransport? Not sure how many people would find it azure.core

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, sure we can.

)
# or
cosmos_client = CosmosClient(uri, key, transport=RequestsTransport(session=session))
```

## Troubleshooting

### General
Expand Down