Merge pull request #266277 from seesharprun/cosmos-data-explorer-query-cancellation

Cosmos DB | Revise data explorer article

Author: JamesJBarnett

articles/cosmos-db/data-explorer.md

@@ -1,52 +1,111 @@
 ---
-title: Use Azure Cosmos DB Explorer to manage your data
-description: Learn about Azure Cosmos DB Explorer, a standalone web-based interface that allows you to view and manage the data stored in Azure Cosmos DB.
+title: Use the Explorer to manage your data
+titleSuffix: Azure Cosmos DB
+description: Learn about the Azure Cosmos DB Explorer, a standalone web-based interface that allows you to view and manage the data stored in Azure Cosmos DB.
+author: seesharprun
+ms.author: sidandrews
+ms.reviewer: esarroyo
 ms.service: cosmos-db
 ms.topic: how-to
-ms.date: 03/02/2023
-ms.author: esarroyo
-author: StefArroyo
+ms.date: 02/14/2024
+# CustomerIntent: As a database developer, I want to access the Explorer so that I can observe my data and make queries against my data.
 ---
 
-# Work with data using Azure Cosmos DB Explorer
+# Use the Azure Cosmos DB Explorer to manage your data
+
 [!INCLUDE[NoSQL, MongoDB, Cassandra, Gremlin, Table](includes/appliesto-nosql-mongodb-cassandra-gremlin-table.md)]
 
-Azure Cosmos DB Explorer is a standalone web-based interface that allows you to view and manage the data stored in Azure Cosmos DB. Azure Cosmos DB Explorer is equivalent to the existing **Data Explorer** tab that is available in Azure portal when you create an Azure Cosmos DB account. The key advantages of Azure Cosmos DB Explorer over the existing Data explorer are:
+Azure Cosmos DB Explorer is a standalone web-based interface that allows you to view and manage the data stored in Azure Cosmos DB. Azure Cosmos DB Explorer is equivalent to the existing **Data Explorer** section that is available in Azure portal for Azure Cosmos DB accounts.
 
-- You have a full screen real-estate to view your data, run queries, stored procedures, triggers, and view their results.  
-- You can provide read or read-write access to your database account and its collections to other users who don't have access to Azure portal or subscription.  
-- You can share the query results with other users who don't have access to Azure portal or subscription.  
+The Azure Cosmos DB Explorer has a few key advantages when compared to the Data explorer, including:
 
-## Access Azure Cosmos DB Explorer
+- Full screen real-estate to browse data, run queries, and observe query results
+- Ability to provide users without access to the Azure portal or an Azure subscription read or read-write capabilities over data in containers
+- Ability to share query results with users who don't have an Azure subscription or Azure portal access
 
-1. Sign in to [Azure portal](https://portal.azure.com/).
+## Prerequisites
+
+- An existing Azure Cosmos DB account.
+  - If you don't have an Azure subscription, [Try Azure Cosmos DB free](https://cosmos.azure.com/try/).
+
+## Access the Explorer directly using your Azure subscription
 
-1. From **All resources**, find and navigate to your Azure Cosmos DB account, select **Keys**, and copy the **Primary Connection String**. You can select either:
+You can use access the Explorer directly and use your existing credentials to quickly get started with the tool.
 
-   - **Read-write Keys**. When you share the Read-write primary connection string other users, they can view and modify the databases, collections, queries, and other resources associated with that specific account.
-   - **Read-only Keys**. When you share the read-only primary connection string with other users, they can view the databases, collections, queries, and other resources associated with that specific account. For example, if you want to share results of a query with your teammates who don't have access to Azure portal or your Azure Cosmos DB account, you can provide them with this value.
+1. Navigate to <https://cosmos.azure.com>.
 
-1. Go to [https://cosmos.azure.com/](https://cosmos.azure.com/).
+1. Select **Sign In**. Sign in using your existing credentials that have access to the Azure Cosmos DB account.
 
-1. Select **Connect to your account with connection string**, paste the connection string, and select **Connect**.
+1. Next, select your Azure subscription and target account from the **Select a Database Account** menu.
 
-To open Azure Cosmos DB Explorer from the Azure portal:
+    ![Screenshot of the 'Select a Database Account' menu in the Explorer.](media/data-explorer/select-database-account.png)
+
+## Access the Explorer from the Azure portal using your Azure subscription
+
+If you're already comfortable with the Azure portal, you can navigate directly from the in-portal Data Explorer to the standalone Explorer.
+
+1. Sign in to [Azure portal](https://portal.azure.com/).
 
-1. Select the **Data Explorer** in the left menu, then select **Open Full Screen**.
+1. Navigate to your existing Azure Cosmos DB account.
 
-   :::image type="content" source="./media/data-explorer/open-data-explorer.png" alt-text="Screenshot shows Data Explorer page with Open Full Screen highlighted." lightbox="./media/data-explorer/open-data-explorer.png":::
+1. In the resource menu, select **Data Explorer**.
+
+1. Next, select the **Open Full Screen** menu option.
+
+    ![Screenshot of the Data Explorer page with the 'Open Full Screen' option highlighted.](media/data-explorer/open-full-screen.png)
 
 1. In the **Open Full Screen** dialog, select **Open**.
 
+## Grant someone else access to the Explorer using a connection string
+
+Use either the **read-write** or **read-only** key to give another user access to your Azure Cosmos DB account. This method works even if the user doesn't have access to an Azure subscription or the Azure portal.
+
+1. Sign in to [Azure portal](https://portal.azure.com/).
+
+1. Navigate to your existing Azure Cosmos DB account.
+
+1. In the resource menu, select **Keys**.
+
+1. On the **keys** page, select either the **Read-write Keys** or **Read-only Keys** option. Then, copy the value of the **Primary Connection String** field. You use this value in a later step.
+
+    | | Description |
+    | --- | --- |
+    | **Read-write key** | Provides access to view and modify the databases, containers, queries, and other resources associated with that specific account |
+    | **Read-only key** | Provides access to view databases, containers, queries, and other resources associated with that specific account |
+
+    > [!TIP]
+    > If you want to share results of a query with your teammates who don't have access to an Azure Subscription or the Azure portal, you can provide them with the read-only .
+
+1. Now, have the other user navigate to <https://cosmos.azure.com>.
+
+1. Select **Connect to your account with connection string**. Then, have the user enter the connection string copied earlier and select **Connect**.
+
+## Configure request unit threshold
+
+In the Explorer, you can configure a limit to the request units per second (RU/s) that queries use. Use this functionality to control the cost and performance in request units (RU) of your queries. This functionality can also cancel high-cost queries automatically.
+
+1. Start in the Explorer for the target Azure Cosmos DB account.
+
+1. Select the **Settings** menu option.
+
+    ![Screenshot of an Data Explorer page with the 'Open Settings' option highlighted.](media/data-explorer/open-settings.png)
+
+1. In the **Settings** dialog, configure whether you want to **Enable RU threshold** and the actual **RU threshold** value.
+
+    ![Screenshot of the individual settings to configure the request unit threshold](media/data-explorer/configure-ru-threshold.png)
+
+    > [!TIP]
+    > The RU threshold is enabled automatically with a default value of **5,000** RUs.
+
 ## Known issues
 
-Currently, viewing documents that contain a UUID isn't supported in Data Explorer. This limitation doesn't affect loading collections, only viewing individual documents or queries that include these documents. To view and manage these documents, users should continue to use the tool that was originally used to create these documents.
+Here are a few currently known issues:
 
-Customers receiving HTTP-401 errors may be due to insufficient Azure RBAC permissions for your Azure account, particularly if the account has a custom role. Any custom roles must have `Microsoft.DocumentDB/databaseAccounts/listKeys/*` action to use Data Explorer if signing in using their Microsoft Entra credentials.
+- Browsing items that contain a UUID isn't supported in Data Explorer. This limitation doesn't affect loading containers, only viewing individual items or queries that include these items. To view and manage these items, users should continue to use the same tooling/SDKs that was originally used to create these items.
 
-## Next steps
+- HTTP 401 errors could occur due to insufficient role-based access control permissions for your Microsoft Entra ID account. This condition can be true particularly if the account has a custom role. Any custom roles must have the `Microsoft.DocumentDB/databaseAccounts/listKeys/*` action included to use the Explorer.
 
-Now that you've learned how to get started with Azure Cosmos DB Explorer to manage your data, next you can:
+## Next step
 
-- [Getting started with queries](nosql/query/getting-started.md)
-- [Stored procedures, triggers, and user-defined functions](stored-procedures-triggers-udfs.md)
+> [!div class="nextstepaction"]
+> [Getting started with queries](nosql/query/getting-started.md)