azure.cosmos.cosmos_client.CosmosClient.yml

### YamlMime:PythonClass
uid: azure.cosmos.cosmos_client.CosmosClient
name: CosmosClient
fullName: azure.cosmos.cosmos_client.CosmosClient
module: azure.cosmos.cosmos_client
inheritances:
- builtins.object
summary: "A client-side logical representation of an Azure Cosmos DB account.\n\n\
  Use this client to configure and execute requests to the Azure Cosmos DB service.\n\
  \nIt's recommended to maintain a single instance of CosmosClient per lifetime of\
  \ the application which enables\n   efficient connection management and performance.\n\
  \nCosmosClient initialization is a heavy operation - don't use initialization CosmosClient\
  \ instances as\n   credentials or network connectivity validations.\n\nInstantiate\
  \ a new CosmosClient."
constructor:
  syntax: 'CosmosClient(url: str, credential: TokenCredential | str | Dict[str, Any],
    consistency_level: str | None = None, **kwargs)'
  parameters:
  - name: url
    description: The URL of the Cosmos DB account.
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: Can be the account key, or a dictionary of resource tokens.
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:str>, <xref:typing.Dict>[<xref:str>, <xref:str>],
      <xref:azure.core.credentials.TokenCredential>]
  - name: consistency_level
    description: 'Consistency level to use for the session. The default value is None
      (Account level).

      More on consistency levels and possible values: [https://aka.ms/cosmos-consistency-levels](https://aka.ms/cosmos-consistency-levels)'
    defaultValue: None
    types:
    - <xref:str>
  keywordOnlyParameters:
  - name: timeout
    description: An absolute timeout in seconds, for the combined HTTP request and
      response processing.
    types:
    - <xref:int>
  - name: connection_timeout
    description: The HTTP request timeout in seconds.
    types:
    - <xref:int>
  - name: connection_mode
    description: The connection mode for the client - currently only supports 'Gateway'.
    types:
    - <xref:str>
  - name: proxy_config
    description: Connection proxy configuration.
    types:
    - <xref:azure.cosmos.ProxyConfiguration>
  - name: ssl_config
    description: Connection SSL configuration.
    types:
    - <xref:azure.cosmos.SSLConfiguration>
  - name: connection_verify
    description: Whether to verify the connection, default value is True.
    types:
    - <xref:bool>
  - name: connection_cert
    description: An alternative certificate to verify the connection.
    types:
    - <xref:str>
  - name: retry_total
    description: Maximum retry attempts.
    types:
    - <xref:int>
  - name: retry_backoff_max
    description: Maximum retry wait time in seconds.
    types:
    - <xref:int>
  - name: retry_fixed_interval
    description: Fixed retry interval in milliseconds.
    types:
    - <xref:int>
  - name: retry_read
    description: Maximum number of socket read retry attempts.
    types:
    - <xref:int>
  - name: retry_connect
    description: Maximum number of connection error retry attempts.
    types:
    - <xref:int>
  - name: retry_status
    description: Maximum number of retry attempts on error status codes.
    types:
    - <xref:int>
  - name: retry_on_status_codes
    description: A list of specific status codes to retry on.
    types:
    - <xref:list>[<xref:int>]
  - name: retry_backoff_factor
    description: Factor to calculate wait time between retry attempts.
    types:
    - <xref:float>
  - name: enable_endpoint_discovery
    description: 'Enable endpoint discovery for

      geo-replicated database accounts. (Default: True)'
    types:
    - <xref:bool>
  - name: preferred_locations
    description: The preferred locations for geo-replicated database accounts.
    types:
    - <xref:list>[<xref:str>]
  - name: enable_diagnostics_logging
    description: 'Enable the CosmosHttpLogging policy.

      Must be used along with a logger to work.'
    types:
    - <xref:bool>
  - name: logger
    description: 'Logger to be used for collecting request diagnostics. Can be passed
      in at client

      level (to log all requests) or at a single request level. Requests will be logged
      at INFO level.'
    types:
    - <xref:logging.Logger>
  - name: no_response_on_write
    description: 'Indicates whether service should be instructed to skip sending

      response payloads on rite operations for items.'
    types:
    - <xref:bool>
examples:
- "Create a new instance of the Cosmos DB client:<!--[!code-python[Main](les\\examples.py\
  \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
  : [], \"backrefs\": [], \"source\": \"C:\\\\hostedtoolcache\\\\windows\\\\Python\\\
  \\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\34\\\\azure_cosmos-4.9.0\\\
  \\samples\\\\examples.py\", \"xml:space\": \"preserve\", \"force\": false, \"language\"\
  : \"python\", \"highlight_args\": {\"linenostart\": 1}, \"linenos\": false} -->\n\
  \n````python\n\n   from azure.cosmos import exceptions, CosmosClient, PartitionKey\n\
  \   from typing import Dict, Any\n\n   import os\n\n   url = os.environ[\"ACCOUNT_URI\"\
  ]\n   key = os.environ[\"ACCOUNT_KEY\"]\n   client = CosmosClient(url, key)\n\n\
  \   ````\n"
methods:
- uid: azure.cosmos.cosmos_client.CosmosClient.create_database
  name: create_database
  summary: Create a new database with the given ID (name).
  signature: 'create_database(id: str, populate_query_metrics: bool | None = None,
    offer_throughput: int | ThroughputProperties | None = None, *, session_token:
    str | None = None, initial_headers: Dict[str, str] | None = None, etag: str |
    None = None, match_condition: MatchConditions | None = None, **kwargs: Any) ->
    DatabaseProxy'
  parameters:
  - name: id
    description: ID (name) of the database to create.
    isRequired: true
    types:
    - <xref:str>
  - name: offer_throughput
    description: The provisioned throughput for this offer.
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:int>, <xref:azure.cosmos.ThroughputProperties>]
  keywordOnlyParameters:
  - name: session_token
    description: Token for use with Session consistency.
    types:
    - <xref:str>
  - name: initial_headers
    description: Initial headers to be sent as part of the request.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: etag
    description: 'An ETag value, or the wildcard character (*). Used to check if the
      resource

      has changed, and act according to the condition specified by the *match_condition*
      parameter.'
    types:
    - <xref:str>
  - name: match_condition
    description: The match condition to use upon the etag.
    types:
    - <xref:azure.core.MatchConditions>
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    description: A DatabaseProxy instance representing the new database.
    types:
    - <xref:azure.cosmos.DatabaseProxy>
  exceptions:
  - type: azure.cosmos.exceptions.CosmosResourceExistsError
    description: Database with the given ID already exists.
  examples:
  - "Create a database in the Cosmos DB account:<!--[!code-python[Main](les\\examples.py\
    \ )]-->\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
    dupnames\": [], \"backrefs\": [], \"source\": \"C:\\\\hostedtoolcache\\\\windows\\\
    \\Python\\\\3.11.9\\\\x64\\\\Lib\\\\site-packages\\\\py2docfx\\\\dist_temp\\\\\
    34\\\\azure_cosmos-4.9.0\\\\samples\\\\examples.py\", \"xml:space\": \"preserve\"\
    , \"force\": false, \"language\": \"python\", \"highlight_args\": {\"linenostart\"\
    : 1}, \"linenos\": false} -->\n\n````python\n\n   database_name = \"testDatabase\"\
    \n   try:\n       database = client.create_database(id=database_name)\n   except\
    \ exceptions.CosmosResourceExistsError:\n       database = client.get_database_client(database=database_name)\n\
    \n   ````\n"
- uid: azure.cosmos.cosmos_client.CosmosClient.create_database_if_not_exists
  name: create_database_if_not_exists
  summary: "Create the database if it does not exist already.\nIf the database already\
    \ exists, the existing settings are returned.\n\n..note::\n   This function does\
    \ not check or update existing database settings or\n   offer throughput if they\
    \ differ from what is passed in."
  signature: 'create_database_if_not_exists(id: str, populate_query_metrics: bool
    | None = None, offer_throughput: int | ThroughputProperties | None = None, *,
    session_token: str | None = None, initial_headers: Dict[str, str] | None = None,
    etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs:
    Any) -> DatabaseProxy'
  parameters:
  - name: id
    description: ID (name) of the database to read or create.
    isRequired: true
    types:
    - <xref:str>
  - name: populate_query_metrics
    description: Enable returning query metrics in response headers.
    isRequired: true
    types:
    - <xref:bool>
  - name: offer_throughput
    description: The provisioned throughput for this offer.
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:int>, <xref:azure.cosmos.ThroughputProperties>]
  keywordOnlyParameters:
  - name: session_token
    description: Token for use with Session consistency.
    types:
    - <xref:str>
  - name: initial_headers
    description: Initial headers to be sent as part of the request.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: etag
    description: 'An ETag value, or the wildcard character (*). Used to check if the
      resource

      has changed, and act according to the condition specified by the *match_condition*
      parameter.'
    types:
    - <xref:str>
  - name: match_condition
    description: The match condition to use upon the etag.
    types:
    - <xref:azure.core.MatchConditions>
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    description: A DatabaseProxy instance representing the database.
    types:
    - <xref:azure.cosmos.DatabaseProxy>
  exceptions:
  - type: azure.cosmos.exceptions.CosmosHttpResponseError
    description: The database read or creation failed.
- uid: azure.cosmos.cosmos_client.CosmosClient.delete_database
  name: delete_database
  summary: Delete the database with the given ID (name).
  signature: 'delete_database(database: str | DatabaseProxy | Mapping[str, Any], populate_query_metrics:
    bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str,
    str] | None = None, etag: str | None = None, match_condition: MatchConditions
    | None = None, **kwargs: Any) -> None'
  parameters:
  - name: database
    description: 'The ID (name), dict representing the properties or <xref:azure.cosmos.cosmos_client.DatabaseProxy>

      instance of the database to delete.'
    isRequired: true
    types:
    - <xref:typing.Union>[<xref:str>, <xref:typing.Dict>[<xref:str>, <xref:str>],
      <xref:azure.cosmos.DatabaseProxy>]
  keywordOnlyParameters:
  - name: session_token
    description: Token for use with Session consistency.
    types:
    - <xref:str>
  - name: initial_headers
    description: Initial headers to be sent as part of the request.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: etag
    description: 'An ETag value, or the wildcard character (*). Used to check if the
      resource

      has changed, and act according to the condition specified by the *match_condition*
      parameter.'
    types:
    - <xref:str>
  - name: match_condition
    description: The match condition to use upon the etag.
    types:
    - <xref:azure.core.MatchConditions>
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    types:
    - <xref:None>
  exceptions:
  - type: azure.cosmos.exceptions.CosmosHttpResponseError
    description: If the database couldn't be deleted.
- uid: azure.cosmos.cosmos_client.CosmosClient.from_connection_string
  name: from_connection_string
  summary: 'Create a CosmosClient instance from a connection string.


    This can be retrieved from the Azure portal.For full list of optional

    keyword arguments, see the CosmosClient constructor.'
  signature: 'from_connection_string(conn_str: str, credential: TokenCredential |
    str | Dict[str, Any] | None = None, consistency_level: str | None = None, **kwargs)
    -> CosmosClient'
  parameters:
  - name: conn_str
    description: The connection string.
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: 'Alternative credentials to use instead of the key

      provided in the connection string.'
    defaultValue: None
    types:
    - <xref:typing.Union>[<xref:str>, <xref:typing.Dict>[<xref:str>, <xref:str>]]
  - name: consistency_level
    description: Consistency level to use for the session. The default value is None
      (Account level).
    defaultValue: None
    types:
    - <xref:str>
  return:
    description: A CosmosClient instance representing the new client.
    types:
    - <xref:azure.cosmos.CosmosClient>
- uid: azure.cosmos.cosmos_client.CosmosClient.get_database_account
  name: get_database_account
  summary: Retrieve the database account information.
  signature: get_database_account(**kwargs) -> DatabaseAccount
  keywordOnlyParameters:
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    description: A *DatabaseAccount* instance representing the Cosmos DB Database
      Account.
    types:
    - <xref:azure.cosmos.DatabaseAccount>
- uid: azure.cosmos.cosmos_client.CosmosClient.get_database_client
  name: get_database_client
  summary: Retrieve an existing database with the ID (name) *id*.
  signature: 'get_database_client(database: str | DatabaseProxy | Mapping[str, Any])
    -> DatabaseProxy'
  parameters:
  - name: database
    description: 'The ID (name), dict representing the properties or

      *DatabaseProxy* instance of the database to read.'
    isRequired: true
    types:
    - <xref:str>
    - <xref:dict>(<xref:str>, <xref:str>)
    - <xref:azure.cosmos.DatabaseProxy>
  return:
    description: A *DatabaseProxy* instance representing the retrieved database.
    types:
    - <xref:azure.cosmos.DatabaseProxy>
- uid: azure.cosmos.cosmos_client.CosmosClient.list_databases
  name: list_databases
  summary: List the databases in a Cosmos DB SQL database account.
  signature: 'list_databases(max_item_count: int | None = None, populate_query_metrics:
    bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str,
    str] | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]'
  parameters:
  - name: max_item_count
    description: Max number of items to be returned in the enumeration operation.
    isRequired: true
    types:
    - <xref:int>
  keywordOnlyParameters:
  - name: session_token
    description: Token for use with Session consistency.
    types:
    - <xref:str>
  - name: initial_headers
    description: Initial headers to be sent as part of the request.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    description: An Iterable of database properties (dicts).
    types:
    - <xref:typing.Iterable>[<xref:typing.Dict>[<xref:str>, <xref:str>]]
- uid: azure.cosmos.cosmos_client.CosmosClient.query_databases
  name: query_databases
  summary: Query the databases in a Cosmos DB SQL database account.
  signature: 'query_databases(query: str | None = None, parameters: List[Dict[str,
    Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count:
    int | None = None, populate_query_metrics: bool | None = None, *, session_token:
    str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any)
    -> ItemPaged[Dict[str, Any]]'
  parameters:
  - name: query
    description: The Azure Cosmos DB SQL query to execute.
    isRequired: true
    types:
    - <xref:str>
  - name: parameters
    description: 'Optional array of parameters to the query.

      Ignored if no query is provided.'
    isRequired: true
    types:
    - <xref:typing.List>[<xref:typing.Dict>[<xref:str>, <xref:typing.Any>]]
  - name: enable_cross_partition_query
    description: 'Allow scan on the queries which couldn''t be

      served as indexing was opted out on the requested paths.'
    isRequired: true
    types:
    - <xref:bool>
  - name: max_item_count
    description: Max number of items to be returned in the enumeration operation.
    isRequired: true
    types:
    - <xref:int>
  keywordOnlyParameters:
  - name: session_token
    description: Token for use with Session consistency.
    types:
    - <xref:str>
  - name: initial_headers
    description: Initial headers to be sent as part of the request.
    types:
    - <xref:typing.Dict>[<xref:str>, <xref:str>]
  - name: response_hook
    description: A callable invoked with the response metadata.
    types:
    - <xref:typing.Callable>
  return:
    description: An Iterable of database properties (dicts).
    types:
    - <xref:typing.Iterable>[<xref:typing.Dict>[<xref:str>, <xref:str>]]