Use Visual Studio Code to connect and query Azure Cosmos DB instances

APPLIES TO: NoSQL MongoDB

Visual Studio Code is a versatile code editor for Linux, macOS, and Windows, supporting numerous extensions. This quickstart shows you how to connect to Azure Cosmos DB for NoSQL and Azure Cosmos DB for MongoDB (vCore) cluster using Visual Studio Code. It covers performing core database operations, including querying, inserting, updating, and deleting data.

Prerequisites

Before you begin, ensure you have the following:

• An Azure Cosmos DB account configured with a database and collection for NoSQL API. Use any of these quickstarts below to set up a resource:

  • Portal
  • Azure CLI

• To connect and manage data in Azure Cosmos DB within Visual Studio, first install the Azure Databases extension.

  1. Open Visual Studio Code.
  2. Access the Extensions pane by selecting View > Extensions or using the shortcut Ctrl + Shift + X on Windows and Command + Shift + X on MacOS.
  3. In the search bar, type Azure Databases extension and select the extension. Then, click Install.
  4. After installation, reload Visual Studio Code if prompted.

Connecting to an Azure Cosmos DB for NoSQL

1. In Visual Studio Code, go to the Azure pane (select the Azure icon in the Activity Bar).
2. Sign in to your Azure account via Entra ID: Note: It is recommended to always use Microsoft Entra ID RBAC when accessing your Azure Cosmos DB resources (instead of account keys) for the most secure authentication method.
3. Once you are signed in, in the Azure tree view, find your Azure Subscription and drill down to Azure Cosmos DB.
4. Select an existing account or right-click to create a new resource.

Query and display your data

The following steps will use the Query Editor to execute a query and view the results of the query:

1. In the menu for your collection, right-click on the collection to open the Query Editor in Preview.

   

2. Run the query provided in the query editor to display your data in Table View:

   

3. Explore your data in other supported views:

• JSON View: See the raw data structure.
• Tree View: Easily explore nested data.

View query and index metrics

Within the query editor, view additional query and index metrics to better help optimize your query performance.

1. Select the Stats tab next to the query Results.

2. For more information on the metric definitions, see the query metrics documentation.

Insert, Edit, and Delete documents

• Real-time document editing: Add, view, edit, and delete documents instantly, with changes reflected in real-time.
• Import from JSON: Load your data quickly from JSON files.

Export query results

• Download results: Download query results to CSV or JSON files.

Next steps

In this tutorial, you've learned how to query data in VS Code, export query results, view query and index metrics for tuning query performance and display data in the multiple supported views. You can now use the Azure Databases VS Code Extension to review real data in your database.

• Get started with the API for NoSQL
• Node.js Quickstart
• Python Quickstart
• Java Quickstart
• Go Quickstart

Prerequisites

Before you begin, ensure you have the following:

• An Azure Cosmos DB account configured with a database in Azure Cosmos DB for MongoDB. Use one of these quickstarts to set up a database:
  • Portal
  • Azure CLI
• To connect and manage data in Azure Cosmos DB, you need to install the Azure Databases extension for Visual Studio Code.
  1. Open Visual Studio Code.
  2. Access the Extensions pane by selecting View > Extensions or using the shortcut Ctrl + Shift + X on Windows and Command + Shift + X on MacOS.
  3. In the search bar, type Azure Databases extension and select the extension. Then, click Install.
  4. After installation, reload Visual Studio Code if prompted.
• MongoDB shell (mongosh) installed for command-line interactions (optional but recommended).

---

Connecting to a MongoDB workload

Connecting to Azure Cosmos DB for MongoDB (vCore) cluster

1. In the Azure Databases extension, expand the Azure Resources section.
2. Locate Subscription you have your MongoDB workload. Under the desired subscription, you will notice Azure Cosmos DB for MongoDB (vCore) branch. Expand the branch to view your clusters and databases.
3. Choose your Azure Cosmos DB for MongoDB (vCore) cluster from the expanded list.
4. When prompted, enter the admin password for your cluster.
5. Once authenticated, you will gain access to your cluster.

Note

Your password is only used for authentication and is not stored.

Note

In many corporate environments, developer machine IP addresses are hidden due to a VPN or other corporate network settings. In these cases, it is recommended to start with allowing access to all IP addresses by adding the 0.0.0.0 - 255.255.255.255 firewall rule for connection testing initially before refining the allow-list.

Connecting to any MongoDB cluster

1. In the Workspace panel, expand the MongoDB accounts section.
2. Here, you can view all your MongoDB accounts. To connect to a new MongoDB account using a connection string, click New Connection and enter the connection string when prompted.
   • Optionally, you may be asked to provide your username and password for authentication.

Note

All successfully connected MongoDB clusters will remain listed in the MongoDB accounts section, even after closing VS Code.

Intuitive Data Management

Easily manage your databases within Visual Studio Code:

• Create and Drop Databases/Collections: Right-click on your account, database, or collection in the resource panel to create or delete databases and collections.

• Import from JSON: Quickly import data from JSON files into your collection.

  • Initiate Import
    1. Right-click on the collection name in the resource view and select Import Documents into Collection.
    2. Alternatively, open the "Collection View" by clicking on the Documents entry of your collection, then click the Import button.
  • Select JSON File
    1. Browse to locate the *.json file containing your data.
    2. Confirm to start the import process.

• Export Data: Save collections or query results as JSON for backup or sharing.

  • Initiate Export:
    • Option 1
      1. Right-click on the collection name in the resource view and select Export Documents from Collection to export the entire collection.
    • Option 2
      1. Open the "Collection View" by clicking on the Documents entry of your collection, then click the Export button.
      2. Choose to export either the entire collection or the results of the current query.
  • Specify Destination File:
    1. Enter the name and location for the destination *.json file.
    2. Confirm export to start saving the data.

• Real-Time Document Editing: Instantly add, view, edit, and delete documents with real-time updates.

  • Open Document Editing:
    • Access document editing options directly within the "Collection View." These controls are conveniently located above the data view for easy access.
  • Available Actions:
    • Add: Create new documents within the collection.
    • View: View the content of the selected document.
    • Edit: Edit the content of selected documents.
    • Delete: Remove selected documents with changes reflected immediately.

Powerful Query Tools

Run and refine your queries seamlessly:

• Instant Results: Immediately view query results in your preferred format—Table, JSON, or Tree view.

  • Switch views easily using the View dropdown menu.

• Execute Queries Directly: Write and execute MongoDB queries with features like syntax highlighting and autocompletion.

  • To run your query, click the Find Query button or press Ctrl/Cmd+Enter in the query editor.

Note

Currently, only find filter queries are supported, with expanded query capabilities coming soon.

Flexible Data Views

Explore your data using multiple views for different perspectives:

• JSON View: See the raw JSON data structure.

• Tree View: Navigate and explore nested data effortlessly.

• Table View: Quickly scan data and drill down into nested documents.

  • To drill down: Find entries with the {} icon, which indicate embedded objects. Double-click to expand and view contents.
  • To go back: Use the navigation breadcrumbs below the Table View to return to previous levels.

Mongo Shell Integration

Command-line functionality is available:

• Launch mongosh: Execute advanced MongoDB commands directly from Visual Studio Code.

Note

The MongoDB shell (mongosh) is not included with the extension. It must be installed separately and configured manually.

Cluster Management

Stay on top of your resources:

• View Cluster Details: Check your cluster’s tier, server version, and resource usage.

• Manage Tags: Organize your clusters with tags that sync with the Azure Portal.

Next steps

Migrate your MongoDB workload to Azure Cosmos DB