MSDN Documentation

Introduction to the NoSQL API Tutorial

Welcome to this hands-on tutorial for Azure Cosmos DB's NoSQL API. This guide will walk you through the essential steps of creating, managing, and querying data within an Azure Cosmos DB NoSQL container.

Azure Cosmos DB is a globally distributed, multi-model database service. The NoSQL API, also known as the Core (SQL) API, provides a powerful, document-oriented database experience with a familiar SQL-like query language.

What You'll Learn

• How to provision an Azure Cosmos DB account.
• How to create a database and container for your NoSQL data.
• How to insert, retrieve, update, and delete documents.
• How to perform basic queries using the SQL API.

Prerequisites

Before you begin, ensure you have the following:

• An active Azure subscription. If you don't have one, you can create a free account.
• A modern web browser.

Step 1: Create an Azure Cosmos DB Account

First, you need to create an Azure Cosmos DB account. This account will serve as the top-level resource for your database services.

1. Sign in to the Azure portal.
2. In the Azure portal search bar, type Azure Cosmos DB and select it.
3. Click Create.
4. On the Create Azure Cosmos DB account page, select your subscription and resource group, or create a new one.
5. Enter a globally unique name for your account.
6. Select Core (SQL) for the API.
7. Choose a region for your account.
8. Review the other settings and click Review + create, then Create.

Step 2: Create a Database and Container

Once your Azure Cosmos DB account is provisioned, you'll create a database and a container. A database is a logical grouping of containers, and a container holds your items (documents).

1. Navigate to your newly created Azure Cosmos DB account in the Azure portal.
2. In the left-hand menu, select Data Explorer.
3. In Data Explorer, click New Container.
4. Configure the following:
   • Database id: Enter a name for your database (e.g., ToDoList).
   • Container id: Enter a name for your container (e.g., Items).
   • Partition key: Enter /category (this is important for performance and scalability).
5. Click OK to create the database and container.

Step 3: Add Items to the Container

Now, let's add some sample JSON documents (items) to your container.

1. In Data Explorer, expand your database (ToDoList) and select your container (Items).
2. Click New Item.
3. Paste the following JSON into the editor:

   {
       "id": "1",
       "category": "personal",
       "name": "groceries",
       "description": "Buy milk and eggs",
       "isComplete": false
   }

4. Click Save.
5. Repeat steps 2-4 to add another item:

   {
       "id": "2",
       "category": "work",
       "name": "project proposal",
       "description": "Draft proposal for new client",
       "isComplete": false
   }

6. Add a third item:

   {
       "id": "3",
       "category": "personal",
       "name": "appointments",
       "description": "Doctor's appointment",
       "isComplete": true
   }

Step 4: Query Items

Azure Cosmos DB's NoSQL API allows you to query your data using SQL-like syntax. Let's retrieve items based on different criteria.

1. In Data Explorer, with your Items container selected, click New SQL Query.
2. To select all items:

   SELECT * FROM c

   Click Execute. You should see the three items you added.
3. To find items in the 'personal' category:

   SELECT * FROM c WHERE c.category = "personal"

   Click Execute.
4. To find incomplete tasks:

   SELECT * FROM c WHERE c.isComplete = false

   Click Execute.

Step 5: Update an Item

You can update an item by retrieving it, modifying its properties, and then saving it.

1. Execute the query SELECT * FROM c WHERE c.id = "1" to find the first item.
2. Click the Edit button next to the item.
3. Change the description to Buy milk, eggs, and bread and set isComplete to true.
4. Click Update.
5. Query all items again to see the changes.

Step 6: Delete an Item

Deleting an item is straightforward.

1. Execute the query SELECT * FROM c WHERE c.id = "2" to find the second item.
2. Click the Delete button next to the item.
3. Confirm the deletion.
4. Query all items again to verify it has been removed.

Next Steps

Congratulations! You've completed the basic operations for Azure Cosmos DB's NoSQL API. Here are some ideas for continuing your learning:

• Explore more complex SQL queries, including joins and aggregations.
• Learn about different consistency levels and their implications.
• Integrate Azure Cosmos DB with your applications using SDKs for various programming languages.
• Discover advanced features like stored procedures, triggers, and user-defined functions.

For more in-depth information, please refer to the official Azure Cosmos DB NoSQL API documentation.