|
| 1 | +--- |
| 2 | +title: 'Azure Cosmos DB: Build an app with Node.js and the SQL API | Microsoft Docs' |
| 3 | +description: Presents a Node.js code sample you can use to connect to and query the Azure Cosmos DB SQL API |
| 4 | +services: cosmos-db |
| 5 | +author: deborahc |
| 6 | +manager: andrl |
| 7 | + |
| 8 | +ms.service: cosmos-db |
| 9 | +ms.component: cosmosdb-sql |
| 10 | +ms.custom: quick start connect, mvc |
| 11 | +ms.devlang: nodejs |
| 12 | +ms.topic: quickstart |
| 13 | +ms.date: 07/30/2018 |
| 14 | +ms.author: dech |
| 15 | + |
| 16 | +--- |
| 17 | +# Azure Cosmos DB: Build a Node.js app using SQL API, JavaScript SDK 2.0 (preview) and the Azure portal |
| 18 | + |
| 19 | +Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB. |
| 20 | + |
| 21 | +This quickstart demonstrates how to create an Azure Cosmos DB [SQL API](sql-api-introduction.md) account, document database, and container using the Azure portal. You then build and run a console app built on the [SQL JavaScript SDK](sql-api-sdk-node.md). This quickstart uses version 2.0 of the [JavaScript SDK](https://www.npmjs.com/package/@azure/cosmos), which is currently in preview. |
| 22 | + |
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)] |
| 26 | +[!INCLUDE [cosmos-db-emulator-docdb-api](../../includes/cosmos-db-emulator-docdb-api.md)] |
| 27 | + |
| 28 | +* In addition: |
| 29 | + * [Node.js](https://nodejs.org/en/) version v6.0.0 or higher |
| 30 | + * [Git](http://git-scm.com/) |
| 31 | + |
| 32 | +## Create a database account |
| 33 | + |
| 34 | +[!INCLUDE [cosmos-db-create-dbaccount](../../includes/cosmos-db-create-dbaccount.md)] |
| 35 | + |
| 36 | +## Add a collection |
| 37 | + |
| 38 | +[!INCLUDE [cosmos-db-create-collection](../../includes/cosmos-db-create-collection.md)] |
| 39 | + |
| 40 | +## Add sample data |
| 41 | + |
| 42 | +[!INCLUDE [cosmos-db-create-sql-api-add-sample-data](../../includes/cosmos-db-create-sql-api-add-sample-data.md)] |
| 43 | + |
| 44 | +## Query your data |
| 45 | + |
| 46 | +[!INCLUDE [cosmos-db-create-sql-api-query-data](../../includes/cosmos-db-create-sql-api-query-data.md)] |
| 47 | + |
| 48 | +## Clone the sample application |
| 49 | + |
| 50 | +Now let's clone a SQL API app from Github, set the connection string, and run it. You will see how easy it is to work with data programmatically. |
| 51 | + |
| 52 | +1. Open a command prompt, create a new folder named git-samples, then close the command prompt. |
| 53 | + |
| 54 | + ```bash |
| 55 | + md "C:\git-samples" |
| 56 | + ``` |
| 57 | + |
| 58 | +2. Open a git terminal window, such as git bash, and use the `cd` command to change to the new folder to install the sample app. |
| 59 | + |
| 60 | + ```bash |
| 61 | + cd "C:\git-samples" |
| 62 | + ``` |
| 63 | + |
| 64 | +3. Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer. |
| 65 | + |
| 66 | + ```bash |
| 67 | + git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git |
| 68 | + ``` |
| 69 | + |
| 70 | +## Review the code |
| 71 | + |
| 72 | +This step is optional. If you're interested in learning how the database resources are created in the code, you can review the following snippets. Otherwise, you can skip ahead to [Update your connection string](#update-your-connection-string). |
| 73 | +
|
| 74 | +Note, if you are familiar with the previous version of the JavaScript SDK, you may be used to seeing the terms 'collection' and 'document.' Because Azure Cosmos DB supports [multiple API models](https://docs.microsoft.com/azure/cosmos-db/introduction#key-capabilities), version 2.0+ of the JavaScript SDK uses the generic terms 'container', which may be a collection, graph, or table and 'item' to describe the content of the container. |
| 75 | +
|
| 76 | +The following snippets are all taken from the **app.js** file. |
| 77 | +
|
| 78 | +* The `CosmosClient` is initialized. |
| 79 | +
|
| 80 | + ```nodejs |
| 81 | + const client = new CosmosClient({ endpoint: endpoint, auth: { masterKey: masterKey } }); |
| 82 | + ``` |
| 83 | +
|
| 84 | +* A new database is created. |
| 85 | +
|
| 86 | + ```nodejs |
| 87 | + const { database } = await client.databases.createIfNotExists({ id: databaseId }); |
| 88 | + ``` |
| 89 | +
|
| 90 | +* A new container (collection) is created. |
| 91 | +
|
| 92 | + ```nodejs |
| 93 | + const { container } = await client.database(databaseId).containers.createIfNotExists({ id: containerId }); |
| 94 | + ``` |
| 95 | +
|
| 96 | +* An item (document) is created. |
| 97 | +
|
| 98 | + ```nodejs |
| 99 | + const { item } = await client.database(databaseId).container(containerId).items.create(itemBody); |
| 100 | + ``` |
| 101 | +
|
| 102 | +* A SQL query over JSON is performed. |
| 103 | +
|
| 104 | + ```nodejs |
| 105 | + const querySpec = { |
| 106 | + query: "SELECT VALUE r.children FROM root r WHERE r.lastName = @lastName", |
| 107 | + parameters: [ |
| 108 | + { |
| 109 | + name: "@lastName", |
| 110 | + value: "Andersen" |
| 111 | + } |
| 112 | + ] |
| 113 | + }; |
| 114 | +
|
| 115 | + const { result: results } = await client.database(databaseId).container(containerId).items.query(querySpec).toArray(); |
| 116 | + for (var queryResult of results) { |
| 117 | + let resultString = JSON.stringify(queryResult); |
| 118 | + console.log(`\tQuery returned ${resultString}\n`); |
| 119 | + } |
| 120 | + ``` |
| 121 | +
|
| 122 | +## Update your connection string |
| 123 | +
|
| 124 | +Now go back to the Azure portal to get your connection string information and copy it into the app. |
| 125 | +
|
| 126 | +1. In the [Azure portal](http://portal.azure.com/), in your Azure Cosmos DB account, in the left navigation click **Keys**, and then click **Read-write Keys**. You'll use the copy buttons on the right side of the screen to copy the URI and Primary Key into the `config.js` file in the next step. |
| 127 | + |
| 128 | +  |
| 129 | + |
| 130 | +2. In Open the `config.js` file. |
| 131 | + |
| 132 | +3. Copy your URI value from the portal (using the copy button) and make it the value of the endpoint key in `config.js`. |
| 133 | + |
| 134 | + `config.endpoint = "https://FILLME.documents.azure.com"` |
| 135 | + |
| 136 | +4. Then copy your PRIMARY KEY value from the portal and make it the value of the `config.primaryKey` in `config.js`. You've now updated your app with all the info it needs to communicate with Azure Cosmos DB. |
| 137 | +
|
| 138 | + `config.primaryKey = "FILLME"` |
| 139 | + |
| 140 | +## Run the app |
| 141 | +1. Run `npm install` in a terminal to install required npm modules |
| 142 | +
|
| 143 | +2. Run `node app.js` in a terminal to start your node application. |
| 144 | +
|
| 145 | +You can now go back to Data Explorer and see query, modify, and work with this new data. |
| 146 | +
|
| 147 | +## Review SLAs in the Azure portal |
| 148 | +
|
| 149 | +[!INCLUDE [cosmosdb-tutorial-review-slas](../../includes/cosmos-db-tutorial-review-slas.md)] |
| 150 | +
|
| 151 | +## Clean up resources |
| 152 | +
|
| 153 | +[!INCLUDE [cosmosdb-delete-resource-group](../../includes/cosmos-db-delete-resource-group.md)] |
| 154 | +
|
| 155 | +## Next steps |
| 156 | +
|
| 157 | +In this quickstart, you've learned how to create an Azure Cosmos DB account, create a collection using the Data Explorer, and run an app. You can now import additional data to your Cosmos DB account. |
| 158 | + |
| 159 | +> [!div class="nextstepaction"] |
| 160 | +> [Import data into Azure Cosmos DB](import-data.md) |
| 161 | + |
| 162 | + |
0 commit comments