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
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.
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.
In the DocumentDB account blade for the selected account, click Add Collection.
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.
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.
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.
- 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.
- Click OK at the bottom of the screen to create the new collection.
The new collection now appears in the Collections lens on the Overview blade.
Optional: To modify the throughput of collection in the portal, click Scale on the Resource menu.
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.
What is a DocumentDB collection?
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.
- For a C# code sample, see the C# collection samples.
- For a Node.js code sample, see the Node.js collection samples.
- For a Python code sample, see Python collection samples.
- For a REST API sample, see Create a Collection.
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.
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.