Edit

Share via

Connect to Azure DocumentDB using the DocumentDB extension for Visual Studio Code

Visual Studio Code is a versatile code editor for Linux, macOS, and Windows, supporting numerous extensions. This quickstart shows you how to connect to an Azure DocumentDB cluster using the DocumentDB extension in Visual Studio Code. It covers performing core database operations, including querying, inserting, updating, and deleting data.

Prerequisites

  • An Azure subscription

    • If you don't have an Azure subscription, create a free account

  • An existing Azure DocumentDB cluster

Install the extension

Start by installing the DocumentDB extension in Visual Studio Code. This extension is used to connect to both Azure DocumentDB and native DocumentDB clusters.

  1. Open Visual Studio Code.

  2. Navigate to the Extensions view by selecting the corresponding icon in the Activity Bar, or use the Ctrl+Shift+X keyboard shortcut.

  3. Search for the term DocumentDB and locate the DocumentDB for VS Code extension.

  4. Select the Install button for the extension.

    Tip

    You can also select the Install button in the extension's details view.

  5. Wait for the installation to complete. Reload Visual Studio Code if prompted.

Connect to cluster

Now, connect to your existing cluster using Service Discovery. Azure Service Discovery can find DocumentDB instances either running on Azure Virtual Machines or Azure DocumentDB. At this step, use Service Discovery to find your existing Azure DocumentDB cluster.

  1. Navigate to the DocumentDB extension by selecting the corresponding icon in the Activity Bar.

  2. In the DocumentDB Connections pane, select + New Connection....

  3. In the first dialog, select Service Discovery.

  4. In the next dialog, select Azure DocumentDB - Azure Service Discovery.

  5. Select your Azure subscription.

    Important

    If you aren't signed in to any Azure subscriptions, you're prompted at this point to manage the subscriptions associated with Visual Studio Code. You must at least have one associated subscription to proceed with the next steps.

  6. Select your existing Azure DocumentDB cluster to connect to the cluster.

    Tip

    In many corporate environments, developer machine IP addresses are hidden due to a VPN or other corporate network settings. In these cases, you can temporarily allow access to all IP addresses by adding the 0.0.0.0 - 255.255.255.255 IP address range as a firewall rule. Use this firewall rule only temporarily as a part of connection testing and development. For more information, see configure firewall.

  7. Observe the new node in the DocumentDB Connections pane for your existing cluster.

Manage cluster resources

First, use the extension to manage databases and collections within the cluster.

  1. In the DocumentDB Connections pane, expand the node for your cluster.

  2. Select + Create Database....

  3. Enter a unique name for your new database. For example, you can use the name store.

  4. Expand the database node, and then select + Create Collection....

  5. Enter a unique name for your new collection. For example, you can use the name products.

  6. Open the context menu for the database node. Then, select Create Collection... again.

  7. Enter another unique name for the second new collection. For example, use the name employees.

  8. Open the context menu for one of the collection nodes. Then, select Delete Collection....

    Tip

    Alternatively, use the context menu for a database node to delete the corresponding database.

Migrate and modify documents

Next, use the built-in tools to edit an existing document, import multiple documents, or export documents as JSON files.

  1. In Visual Studio Code, create a new JSON file with a unique name. For example, use the name inventory.json.

  2. Enter the following six products into the JSON file as an array.

    Name Category Quantity Price Sale
    00000000-0000-0000-0000-000000004001 Raiot Jacket gear-paddle-safety-gear 909 42.00 ❌ No
    00000000-0000-0000-0000-000000004007 Xenmon Mountain Bike gear-cycle-mountain-bikes 12 1399.00 ✅ Yes
    00000000-0000-0000-0000-000000004018 Windry Mittens apparel-accessories-gloves-and-mittens 121 35 ❌ No
    00000000-0000-0000-0000-000000004025 Metix Sleeping Bag gear-camp-sleeping-bags 118 150.00 ✅ Yes
    00000000-0000-0000-0000-000000004058 Complete Camp Cookware Set gear-camp-cookware 170 88.00 ✅ Yes
    00000000-0000-0000-0000-000000004318* Niborio Tent gear-camp-tents 140 420 ✅ Yes 
    [
  {
    "_id": "00000000-0000-0000-0000-000000004001",
    "name": "Raiot Jacket",
    "category": "gear-paddle-safety-gear",
    "quantity": 909,
    "price": 42.00,
    "sale": false
  },
  {
    "_id": "00000000-0000-0000-0000-000000004007",
    "name": "Xenmon Mountain Bike",
    "category": "gear-cycle-mountain-bikes",
    "quantity": 12,
    "price": 1399.00,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004018",
    "name": "Windry Mittens",
    "category": "apparel-accessories-gloves-and-mittens",
    "quantity": 121,
    "price": 35.00,
    "sale": false
  },
  {
    "_id": "00000000-0000-0000-0000-000000004025",
    "name": "Metix Sleeping Bag",
    "category": "gear-camp-sleeping-bags",
    "quantity": 118,
    "price": 150.00,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004058",
    "name": "Complete Camp Cookware Set",
    "category": "gear-camp-cookware",
    "quantity": 170,
    "price": 88.00,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004318",
    "name": "Niborio Tent",
    "category": "gear-camp-tents",
    "quantity": 140,
    "price": 420.00,
    "sale": true
  }
]

  3. Save the modified file.

  4. Open the context menu for one of the collections in your cluster. Then, select Import Documents into Collection....

  5. Wait for the import process to complete.

  6. Expand the collections node and select Documents.

  7. Observe the newly imported documents in your collection.

  8. Select one of the documents. Then, select the Edit icon in the menu of the Documents view.

  9. Update the value of the price property for the document. For example, update the price of the Windry Mittens product from 35.00 to 45.00.

    {
  "_id": "00000000-0000-0000-0000-000000004018",
  "name": "Windry Mittens",
  "category": "apparel-accessories-gloves-and-mittens",
  "quantity": 121,
  "price": 45.00,
  "sale": false
}

  10. Select Save to persist the changes to the document.

  11. Open the context menu again for the same collection. Now, select Export Documents from Collection....

  12. Give the newly exported JSON file a unique name. For example, name the file inventory-modified.json.

  13. Open the new JSON file in the Visual Studio Code editor. Observe the documents represented in the JSON array.

    [
  {
    "_id": "00000000-0000-0000-0000-000000004001",
    "name": "Raiot Jacket",
    "category": "gear-paddle-safety-gear",
    "quantity": 909,
    "price": 42,
    "sale": false
  },
  {
    "_id": "00000000-0000-0000-0000-000000004007",
    "name": "Xenmon Mountain Bike",
    "category": "gear-cycle-mountain-bikes",
    "quantity": 12,
    "price": 1399,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004025",
    "name": "Metix Sleeping Bag",
    "category": "gear-camp-sleeping-bags",
    "quantity": 118,
    "price": 150,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004058",
    "name": "Complete Camp Cookware Set",
    "category": "gear-camp-cookware",
    "quantity": 170,
    "price": 88,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004318",
    "name": "Niborio Tent",
    "category": "gear-camp-tents",
    "quantity": 140,
    "price": 420,
    "sale": true
  },
  {
    "_id": "00000000-0000-0000-0000-000000004018",
    "name": "Windry Mittens",
    "category": "apparel-accessories-gloves-and-mittens",
    "quantity": 121,
    "price": 45,
    "sale": false
  }
]

    Note

    Numeric precision might vary between the imported and exported documents. This variation is because JavaScript Object Notation (JSON) and Binary JSON (BSON) use different data types for numbers.

Query and visualize data

Use the find filter to perform queries against your data using the MongoDB Query Language (MQL) and output the results in JSON. Then, contextualize the data using the extension as tabular information or a tree view.

  1. In the Documents view, update the query from the default { } value to the following query:

    {
  "sale": true,
  "price": {
    "$gt": 100
  }
}

  2. Select Find Query.

  3. Observe the three documents that match the query in the results.

Name Category Quantity Price Sale
00000000-0000-0000-0000-000000004007 Xenmon Mountain Bike gear-cycle-mountain-bikes 12 1399.00 ✅ Yes
00000000-0000-0000-0000-000000004025 Metix Sleeping Bag gear-camp-sleeping-bags 118 150.00 ✅ Yes
00000000-0000-0000-0000-000000004318* Niborio Tent gear-camp-tents 140 420 ✅ Yes

  1. In the results pane, open the drop-down list for the view and select JSON View to observe the results as separate JSON documents.

    {
  "_id": "00000000-0000-0000-0000-000000004007",
  "name": "Xenmon Mountain Bike",
  "category": "gear-cycle-mountain-bikes",
  "quantity": 12,
  "price": 1399,
  "sale": true
}

    {
  "_id": "00000000-0000-0000-0000-000000004025",
  "name": "Metix Sleeping Bag",
  "category": "gear-camp-sleeping-bags",
  "quantity": 118,
  "price": 150,
  "sale": true
}

    {
  "_id": "00000000-0000-0000-0000-000000004318",
  "name": "Niborio Tent",
  "category": "gear-camp-tents",
  "quantity": 140,
  "price": 420,
  "sale": true
}

  2. Finally, select Tree View to review the results in a hierarchical format.

    • 00000000-0000-0000-0000-000000004007 - Document

      • gear-cycle-mountain-bikes - String

      • Xenmon Mountain Bike - String

      • 1399 - Double

      • 12 - Double

      • true - Boolean

    • 00000000-0000-0000-0000-000000004025 - Document

      • gear-camp-sleeping-bags - String

      • Metix Sleeping Bag - String

      • 150 - Double

      • 118 - Double

      • true - Boolean

    • 00000000-0000-0000-0000-000000004318 - Document

      • gear-camp-tents - String

      • Niborio Tent - String

      • 420 - Double

      • 140 - Double

      • true - Boolean

Launch MongoDB Shell

Now, launch the MongoDB Shell (mongosh) with the extension connected directly to your cluster. Use the same syntax and commands you would typically use with the shell.

  1. Open the context menu for the cluster. Next, select Launch Shell.

  2. The shell launches in the default terminal for Visual Studio Code.

  3. After you're successfully authenticated, observe the warning that appears.

    ------
   Warning: Non-Genuine MongoDB Detected
   This server or service appears to be an emulation of MongoDB rather than an official MongoDB product.
------

    Tip

    You can safely ignore this warning. This warning is generated because the connection string contains cosmos.azure. Azure DocumentDB is a native Azure platform as a service (PaaS) offering.

Perform test queries

Verify that you're successfully connected to your cluster by performing a series of test commands and queries.

  1. Check your connection status by running the connectionStatus command.

    db.runCommand({connectionStatus: 1})

    {
  ...
  ok: 1
}

  2. List the databases in your cluster.

    show dbs

  3. Switch to a specific database. Replace the <database-name> placeholder with the name of any database in your cluster.

    use <database-name>

    Tip

    For example, if the database name is inventory, then the command would be use inventory.

  4. List the collections within the database.

    show collections

  5. Find the first five items within a specific collection. Replace the <collection-name> placeholder with the name of any collection in your cluster.

    db.<collection-name>.find().limit(5)

    Tip

    For example, if the collection name is equipment, then the command would be db.equipment.find().limit(5).

Use MongoDB scrapbooks

Finally, open a scrapbook to run MQL commands directly against a collection in a manner similar to the shell.

  1. Open the context menu for the collection and then select DocumentDB Scrapbook > New DocumentDB Scrapbook.

  2. Enter the following MongoDB Query Language (MQL) commands to find products that are on sale, have a price between 100 and 1000, and a quantity greater than 50. The results only include the name, price, and quantity fields, and are sorted by price in descending order.

    db.products.aggregate([
  {
    $match: {
      sale: true,
      price: { $gte: 100, $lte: 1000 },
      quantity: { $gt: 50 }
    }
  },
  {
    $project: {
      _id: 0,
      name: 1,
      price: 1,
      quantity: 1
    }
  },
  {
    $sort: { price: -1 }
  }
])

  3. Select Run All to run the entire contents of the scrapbook against your current cluster.

  4. Observe the output from the command.

    [
  {
    "name": "Niborio Tent",
    "quantity": 140,
    "price": 420
  },
  {
    "name": "Metix Sleeping Bag",
    "quantity": 118,
    "price": 150
  }
]

  5. Save the scrapbook using a unique filename with the *.vscode-documentdb-scrapbook extension.

Related content

  • Last updated on