How to create a DocumentDB collection and database using the Azure portal

To use Microsoft Azure DocumentDB, you must have a DocumentDB account, a database, a collection, and documents. This topic describes how to create a DocumentDB collection in the Azure portal.

Not sure what a collection is? See What is a DocumentDB collection?.

There are two ways to create a colletion in the portal, by using the Add Collection button, or by using Data Explorer (preview).

Create a colletion using Add Collection button

  1. In the Azure portal, in the Jumpbar, click DocumentDB (NoSQL), and then in the DocumentDB (NoSQL) blade, select the account in which to add a collection. If you don't have any accounts listed, you'll need to create a DocumentDB account.

    Screen shot highlighting the DocumentDB Accounts in the Jumpbar, the account in the DocumentDB Accounts blade, and the database in the DocumentDB account blade, in the Databases lens

    If DocumentDB (NoSQL) is not visible in the Jumpbar, click More Services and then click DocumentDB (NoSQL). If you don't have any accounts listed, you'll need to create a DocumentDB account.

  2. In the DocumentDB account blade for the selected account, click Add Collection.

    Screen shot highlighting the DocumentDB Accounts in the Jumpbar, the account in the DocumentDB Accounts blade, and the database in the DocumentDB account blade, in the Databases lens

  3. In the Add Collection blade, in the Collection Id box, enter the ID for your new collection. Collection names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space. When the name is validated, a green check mark appears in the ID box.

    Screen shot highlighting the Add Collection button on the Database blade, the settings on the Add Collection blade, and the OK button - Azure portal for DocumentDB - Cloud based database creator for NoSQL JSON databases

  4. By default, Storage Capacity is set to 250 GB to handle partitioned collections.

    Set storage capcity to 10 GB if you want a single partition collection with throughput levels from 400-10,000 request units/second (RU/s). One RU corresponds to the throughput of a read of a 1KB document. For more information about request units, see Request units.

    Set storage capacity to 250 GB if you want a partitioned collection that can scale to handle an unlimited amount of storage over multiple partitions, and can have throughput levels starting at 2,500 RU/s.

    Set storage capacity to Custom if you want to provision an amount other than 10 GB or 250 GB. DocumentDB has virtually limitless scale, so please include your requested storage size and throughput value in the support request.

  5. In the Partition Key box, enter a partition key for the collection. This is required for partitioned collections and optional for single partition collections. Selecting the correct partition key is important in creating a performant collection. For more information on selecting a partition key, see Designing for partitioning.

  6. In the Database blade, either create a new database or use an existing one. Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space. To validate the name, click outside the text box. When the name is validated, a green check mark appears in the box.
  7. Click OK at the bottom of the screen to create the new collection.
  8. The new collection now appears in the Collections lens on the Overview blade.

    Screen shot of the new collection in the Database blade - Azure portal for DocumentDB - Cloud based database creator for NoSQL JSON databases

  9. Optional: To modify the throughput of collection in the portal, click Scale on the Resource menu.

    Screen shot of the resource menu, with Scale selected

Create a collection by using Data Explorer (preview)

The other method for creating a collection in the portal is to use the Data Explorer. To open Data Explorer, click Data Explorer (preview) on the navigation bar in the portal, then click the New Collection button, as shown in the following screencap.

Screen shot showing the New Collection button in the portal

What is a DocumentDB collection?

A collection is a container of JSON documents and the associated JavaScript application logic. A collection is a billable entity, where the cost is determined by the provisioned throughput of the collection. Collections can span one or more partitions/servers and can scale to handle practically unlimited volumes of storage or throughput.

Collections are automatically partitioned into one or more physical servers by DocumentDB. When you create a collection, you can specify the provisioned throughput in terms of request units per second and a partition key property. The value of this property will be used by DocumentDB to distribute documents among partitions and route requests like queries. The partition key value also acts as the transaction boundary for stored procedures and triggers. Each collection has a reserved amount of throughput specific to that collection, which is not shared with other collections in the same account. Therefore, you can scale out your application both in terms of storage and throughput.

Collections are not the same as tables in relational databases. Collections do not enforce schema, in fact DocumentDB does not enforce any schemas, it's a schema-free database. Therefore you can store different types of documents with diverse schemas in the same collection. You can choose to use collections to store objects of a single type like you would with tables. The best model depends only on how the data appears together in queries and transactions.

Other ways to create a DocumentDB collection

Collections do not have to be created using the portal, you can also create them using the DocumentDB SDKs and the REST API.

Troubleshooting

If Add Collection is disabled in the Azure portal, that means your account is currently disabled, which normally occurs when all the benefits credits for the month are used.

Next steps

Now that you have a collection, the next step is to add documents or import documents into the collection. When it comes to adding documents to a collection, you have a few choices:

  • You can add documents by using the Document Explorer in the portal.
  • You can import documents and data by using the DocumentDB Data Migration Tool, which enables you to import JSON and CSV files, as well as data from SQL Server, MongoDB, Azure Table storage, and other DocumentDB collections.
  • Or you can add documents by using one of the DocumentDB SDKs. DocumentDB has .NET, Java, Python, Node.js, and JavaScript API SDKs. For C# code samples showing how to work with documents by using the DocumentDB .NET SDK, see the C# document samples. For Node.js code samples showing how to work with documents by using the DocumentDB Node.js SDK, see the Node.js document samples.

After you have documents in a collection, you can use DocumentDB SQL to execute queries against your documents by using the Query Explorer in the portal, the REST API, or one of the SDKs.