Merge pull request #247145 from seesharprun/cosmos-issues-batch-1

Cosmos DB | Resolve public issues batch #1

Author: prmerger-automator[bot]

articles/cosmos-db/change-feed.md

@@ -65,7 +65,7 @@ Change feed is available for partition key ranges of an Azure Cosmos DB containe
 
 ### Sort order of items in change feed
 
-Change feed items come in the order of their modification time. This sort order is guaranteed per logical partition key, and there's no guaranteed order across the partition key values.
+Change feed items come in the order of their modification time. This sort order is guaranteed per physical partition, and there's no guaranteed order across the partition key values.
 
 ### Change feed in multi-region Azure Cosmos DB accounts
 

articles/cosmos-db/continuous-backup-restore-introduction.md

@@ -136,7 +136,7 @@ Currently the point in time restore functionality has the following limitations:
 
 * The restored account is created in the same region where your source account exists. You can't restore an account into a region where the source account didn't exist.
 
-* The restore window is only 30-day for continuous 30-day tier and it can't be changed. Similarly it's only 7-day for continuous 7-day tier and that also can't be changed.
+* The restore window is only 30 days for continuous 30-day tier and seven days for continuous 7-day tier. These tiers can be switched, but the actual quantities (``7`` or ``30``) can't be changed. Furthermore, if you switch from 30-day tier to 7-day tier, there's the potential for data loss on days beyond the seventh.
 
 * The backups aren't automatically geo-disaster resistant. You've to explicitly add another region to have resiliency for the account and the backup.
 

articles/cosmos-db/how-to-setup-customer-managed-keys.md

@@ -156,6 +156,17 @@ Here, create a new key using Azure Key Vault and retrieve the unique identifier.
 
    :::image type="content" source="media/how-to-setup-customer-managed-keys/new-customer-managed-key.png" lightbox="media/how-to-setup-customer-managed-keys/new-customer-managed-key.png" alt-text="Screenshot of the dialog to create a new key.":::
 
+  > [!TIP]
+  > Alternatively, you can use the Azure CLI to generate a key with:
+  >
+  > ```azurecli
+  > az keyvault key create \
+  >     --vault-name <name-of-key-vault> \
+  >     --name <name-of-key>
+  > ```
+  >
+  > For more information on managing a key vault with the Azure CLI, see [manage Azure Key Vault with the Azure CLI](../key-vault/general/manage-with-cli2.md).
+
 1. After the key is created, select the newly created key and then its current version.
 
 1. Copy the key's **Key Identifier**, except the part after the last forward slash:
@@ -555,9 +566,6 @@ Use the Azure CLI to restore a continuous account that is already configured usi
     # Variable for location
     location="<azure-region>"
 
-    # Variable for key URI in the key vault
-    keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"
-    
     # Variables for identities
     identityId="<identity-resource-id>"
     

articles/cosmos-db/how-to-setup-rbac.md

@@ -349,9 +349,9 @@ Assign a role to an identity:
 ```azurecli
 resourceGroupName='<myResourceGroup>'
 accountName='<myCosmosAccount>'
-readOnlyRoleDefinitionId = '<roleDefinitionId>' # as fetched above
+readOnlyRoleDefinitionId='<roleDefinitionId>' # as fetched above
 # For Service Principals make sure to use the Object ID as found in the Enterprise applications section of the Azure Active Directory portal blade.
-principalId = '<aadPrincipalId>'
+principalId='<aadPrincipalId>'
 az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroupName --scope "/" --principal-id $principalId --role-definition-id $readOnlyRoleDefinitionId
 ```
 

articles/cosmos-db/nosql/best-practice-dotnet.md

@@ -35,15 +35,15 @@ Watch the video below to learn more about using the .NET SDK from an Azure Cosmo
 |<input type="checkbox"/> |  Ephemeral Port Exhaustion      | For sparse or sporadic connections, we set the [`IdleConnectionTimeout`](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.idletcpconnectiontimeout?view=azure-dotnet&preserve-view=true) and [`PortReuseMode`](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.portreusemode?view=azure-dotnet&preserve-view=true) to `PrivatePortPool`. The `IdleConnectionTimeout` property helps control the time after which unused connections are closed. This reduces the number of unused connections. By default, idle connections are kept open indefinitely. The value set must be greater than or equal to 10 minutes. We recommended values between 20 minutes and 24 hours.  The `PortReuseMode` property allows the SDK to use a small pool of ephemeral ports for various Azure Cosmos DB destination endpoints.    |
 |<input type="checkbox"/> |  Use Async/Await     |  Avoid blocking calls: `Task.Result`, `Task.Wait`, and `Task.GetAwaiter().GetResult()`. The entire call stack is asynchronous in order to benefit from [async/await](/dotnet/csharp/programming-guide/concepts/async/) patterns. Many synchronous blocking calls lead to [Thread Pool starvation](/archive/blogs/vancem/diagnosing-net-core-threadpool-starvation-with-perfview-why-my-service-is-not-saturating-all-cores-or-seems-to-stall) and degraded response times. |
 |<input type="checkbox"/>  |   End-to-End Timeouts | To get end-to-end timeouts, you need to use both `RequestTimeout` and `CancellationToken` parameters. For more details [visit our timeout troubleshooting guide](troubleshoot-dotnet-sdk-request-timeout.md). |
-|<input type="checkbox"/>  |   Retry Logic      | For details on which errors to retry on and which ones are retried by SDKs [visit our design guide](conceptual-resilient-sdk-applications.md#should-my-application-retry-on-errors). For accounts configured with multiple regions, there are [some scenarios](troubleshoot-sdk-availability.md#transient-connectivity-issues-on-tcp-protocol) where the SDK will automatically retry on other regions. For .NET specific implementation details visit the [SDK source repository](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/docs/SdkDesign.md). |
+|<input type="checkbox"/>  |   Retry Logic      | For more information on which errors to retry on and which ones are retried by SDKs, see [design guide](conceptual-resilient-sdk-applications.md#should-my-application-retry-on-errors). For accounts configured with multiple regions, there are [some scenarios](troubleshoot-sdk-availability.md#transient-connectivity-issues-on-tcp-protocol) where the SDK will automatically retry on other regions. For .NET specific implementation details visit the [SDK source repository](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/docs/SdkDesign.md). |
 |<input type="checkbox"/>  |     Caching database/collection names    |    Retrieve the names of your databases and containers from configuration or cache them on start. Calls like `ReadDatabaseAsync` or `ReadDocumentCollectionAsync` and  `CreateDatabaseQuery` or `CreateDocumentCollectionQuery` will result in metadata calls to the service, which consume from the system-reserved RU limit. `CreateIfNotExist` should also only be used once for setting up the database. Overall, these operations should be performed infrequently.       |
 |<input type="checkbox"/> |     Bulk Support      |     In scenarios where you may not need to optimize for latency, we recommend enabling [Bulk support](https://devblogs.microsoft.com/cosmosdb/introducing-bulk-support-in-the-net-sdk/) for dumping large volumes of data.    |
 | <input type="checkbox"/>  |     Parallel Queries     |    The Azure Cosmos DB SDK supports [running queries in parallel](performance-tips-query-sdk.md?pivots=programming-language-csharp) for better latency and throughput on your queries.  We recommend setting the `MaxConcurrency` property within the `QueryRequestsOptions` to the number of partitions you have. If you aren't aware of the number of partitions, start by using `int.MaxValue`, which will give you the best latency. Then decrease the number until it fits the resource restrictions of the environment to avoid high CPU issues. Also, set the `MaxBufferedItemCount` to the expected number of results returned to limit the number of prefetched results. |
 | <input type="checkbox"/> |     Performance Testing Backoffs      |    When performing testing on your application,  you should implement backoffs at [`RetryAfter`](performance-tips-dotnet-sdk-v3.md#sdk-usage) intervals. Respecting the backoff helps ensure that you spend a minimal amount of time waiting between retries.   |
-|  <input type="checkbox"/>   |   Indexing     |   The Azure Cosmos DB indexing policy also allows you to specify which document paths to include or exclude from indexing by using indexing paths (IndexingPolicy.IncludedPaths and IndexingPolicy.ExcludedPaths).  Ensure that you exclude unused paths from indexing for faster writes.  For a sample on how to create indexes using the SDK [visit](performance-tips-dotnet-sdk-v3.md#indexing-policy)   |
+|  <input type="checkbox"/>   |   Indexing     |   The Azure Cosmos DB indexing policy also allows you to specify which document paths to include or exclude from indexing by using indexing paths (IndexingPolicy.IncludedPaths and IndexingPolicy.ExcludedPaths).  Ensure that you exclude unused paths from indexing for faster writes.  For more information on how to create indexes using the SDK, see [performance tips .NET SDK v3](performance-tips-dotnet-sdk-v3.md#indexing-policy).   |
 |  <input type="checkbox"/>   |    Document Size  |    The request charge of a specified operation correlates directly to the size of the document. We recommend reducing the size of your documents as operations on large documents cost more than operations on smaller documents.      |
 | <input type="checkbox"/>   |     Increase the number of threads/tasks    |    Because calls to Azure Cosmos DB are made over the network, you might need to vary the degree of concurrency of your requests so that the client application spends minimal time waiting between requests. For example, if you're using the [.NET Task Parallel Library](/dotnet/standard/parallel-programming/task-parallel-library-tpl), create on the order of hundreds of tasks that read from or write to Azure Cosmos DB.     |
-|  <input type="checkbox"/> |    Enabling Query Metrics     |  For more logging of your backend query executions, you can enable SQL Query Metrics using our .NET SDK. For instructions on how to collect SQL Query Metrics [visit](query-metrics-performance.md)    |
+|  <input type="checkbox"/> |    Enabling Query Metrics     |  For more logging of your backend query executions, you can enable SQL Query Metrics using our .NET SDK. For more information on how to collect SQL Query Metrics, see [query metrics and performance](query-metrics-performance.md).    |
 |  <input type="checkbox"/>    | SDK Logging   | Log [SDK diagnostics](#capture-diagnostics) for outstanding scenarios, such as exceptions or when requests go beyond an expected latency.
 |  <input type="checkbox"/>    | DefaultTraceListener   | The DefaultTraceListener poses performance issues on production environments causing high CPU and I/O bottlenecks. Make sure you're using the latest SDK versions or [remove the DefaultTraceListener from your application](performance-tips-dotnet-sdk-v3.md#logging-and-tracing)  |
 

articles/cosmos-db/nosql/how-to-dotnet-create-container.md

@@ -7,7 +7,7 @@ ms.service: cosmos-db
 ms.subservice: nosql
 ms.devlang: csharp
 ms.topic: how-to
-ms.date: 07/06/2022
+ms.date: 08/02/2023
 ms.custom: devx-track-csharp, devguide-csharp, cosmos-db-dev-journey, devx-track-dotnet
 ---
 
@@ -23,14 +23,16 @@ In Azure Cosmos DB, a container is analogous to a table in a relational database
 
 Here are some quick rules when naming a container:
 
-- Keep container names between 3 and 63 characters long
-- Container names can only contain lowercase letters, numbers, or the dash (-) character.
-- Container names must start with a lowercase letter or number.
+- Container names must not be empty.
+- Container names can't be longer than 256 characters.
 
 Once created, the URI for a container is in this format:
 
 ``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/colls/<container-name>``
 
+> [!TIP]
+> For more information on container name limits, see [service quotas and limits](../concepts-limits.md)
+
 ## Create a container
 
 To create a container, call one of the following methods:
@@ -44,15 +46,15 @@ The following example creates a container asynchronously:
 
 :::code language="csharp" source="~/cosmos-db-nosql-dotnet-samples/226-create-container-options/Program.cs" id="create_container" highlight="2":::
 
-The [``Database.CreateContainerAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerasync) method will throw an exception if a database with the same name already exists.
+The [``Database.CreateContainerAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerasync) method throws an exception if a database with the same name already exists.
 
 ### Create a container asynchronously if it doesn't already exist
 
 The following example creates a container asynchronously only if it doesn't already exist on the account:
 
 :::code language="csharp" source="~/cosmos-db-nosql-dotnet-samples/226-create-container-options/Program.cs" id="create_container_check" highlight="2":::
 
-The [``Database.CreateContainerIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerifnotexistsasync) method will only create a new container if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
+The [``Database.CreateContainerIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerifnotexistsasync) method only creates a new container if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
 
 ## Parsing the response
 

articles/cosmos-db/nosql/how-to-dotnet-create-database.md

@@ -7,7 +7,7 @@ ms.service: cosmos-db
 ms.subservice: nosql
 ms.devlang: csharp
 ms.topic: how-to
-ms.date: 07/06/2022
+ms.date: 08/02/2023
 ms.custom: devx-track-csharp, devguide-csharp, cosmos-db-dev-journey, devx-track-dotnet
 ---
 
@@ -23,14 +23,16 @@ In Azure Cosmos DB, a database is analogous to a namespace. When you create a da
 
 Here are some quick rules when naming a database:
 
-- Keep database names between 3 and 63 characters long
-- Database names can only contain lowercase letters, numbers, or the dash (-) character.
-- Database names must start with a lowercase letter or number.
+- Database names must not be empty.
+- Database names can't be longer than 256 characters.
 
 Once created, the URI for a database is in this format:
 
 ``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>``
 
+> [!TIP]
+> For more information on database name limits, see [service quotas and limits](../concepts-limits.md)
+
 ## Create a database
 
 To create a database, call one of the following methods:
@@ -44,15 +46,15 @@ The following example creates a database asynchronously:
 
 :::code language="csharp" source="~/cosmos-db-nosql-dotnet-samples/201-create-database-options/Program.cs" id="create_database" highlight="2":::
 
-The [``CosmosClient.CreateDatabaseAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseasync) method will throw an exception if a database with the same name already exists.
+The [``CosmosClient.CreateDatabaseAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseasync) method throws an exception if a database with the same name already exists.
 
 ### Create a database asynchronously if it doesn't already exist
 
 The following example creates a database asynchronously only if it doesn't already exist on the account:
 
 :::code language="csharp" source="~/cosmos-db-nosql-dotnet-samples/201-create-database-options/Program.cs" id="create_database_check" highlight="2":::
 
-The [``CosmosClient.CreateDatabaseIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseifnotexistsasync) method will only create a new database if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
+The [``CosmosClient.CreateDatabaseIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseifnotexistsasync) method only creates a new database if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
 
 ## Parsing the response
 

articles/cosmos-db/nosql/materialized-views.md

@@ -241,6 +241,12 @@ After your account and the materialized view builder are set up, you should be a
         databaseName="<database-that-contains-source-collection>"
         ```
 
+    1. If you haven't already, get the identifier of the account and store it in a shell variable named `$accountId`.
+
+        ```azurecli
+        accountId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"
+        ```
+
     1. Make a REST API call to create the materialized view:
 
         ```azurecli

articles/cosmos-db/rate-limiting-requests.md

@@ -149,12 +149,14 @@ For more information, see: [Cache-Aside pattern](/azure/architecture/patterns/ca
 
 ### Materialized View pattern
 
-You might pre-populate views into other collections after storing the data in Azure Cosmos DB when the data isn't ideally formatted for required query operations. This pattern can help support efficient querying and data extraction, and improve application performance.
+You might prepopulate views into other collections after storing the data in Azure Cosmos DB when the data isn't ideally formatted for required query operations. This pattern can help support efficient querying and data extraction, and improve application performance.
 
 For more information, see [Materialized View pattern](/azure/architecture/patterns/materialized-view).
 
 ## Next steps
 
+* Explore an example implemented in Go, available on [GitHub](https://github.com/mspnp/go-batcher).
+* Learn more about the [Rate Limiting pattern](/azure/architecture/patterns/rate-limiting-pattern) in the Azure Architecture Center.
 * Learn how to [troubleshoot TooManyRequests errors](troubleshoot-request-rate-too-large.md) in Azure Cosmos DB.
 * Learn how to [troubleshoot Timeout errors](troubleshoot-request-timeout.md) in Azure Cosmos DB.
 * Learn how to [troubleshoot ServiceUnavailable errors](troubleshoot-service-unavailable.md) in Azure Cosmos DB.
@@ -163,5 +165,5 @@ For more information, see [Materialized View pattern](/azure/architecture/patter
 * Learn about [Indexing policies](index-policy.md) in Azure Cosmos DB.
 * Learn about [Autoscaling](provision-throughput-autoscale.md) in Azure Cosmos DB.
 * Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
-    * If all you know is the number of vcores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](convert-vcore-to-request-unit.md) 
+    * If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](convert-vcore-to-request-unit.md) 
     * If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

articles/cosmos-db/set-throughput.md

@@ -103,11 +103,7 @@ The response of those methods also contains the [minimum provisioned throughput]
 * [ThroughputResponse.MinThroughput](/dotnet/api/microsoft.azure.cosmos.throughputresponse.minthroughput) on the .NET SDK.
 * [ThroughputResponse.getMinThroughput()](/java/api/com.azure.cosmos.models.throughputresponse.getminthroughput) on the Java SDK.
 
-The actual minimum RU/s may vary depending on your account configuration. But generally it's the maximum of:
-
-* 400 RU/s 
-* Current storage in GB * 1 RU/s
-* Highest RU/s ever provisioned on the database or container / 100
+The actual minimum RU/s may vary depending on your account configuration. For more information, see [the autoscale FAQ](autoscale-faq.yml).
 
 ### Changing the provisioned throughput