Create a Document

Article
01/07/2016

A new document can be created by executing an HTTPS POST request against the docs URI resource path.

Documents are automatically indexed. If automatic indexing is turned off at the collection level, documents can be manually included or excluded from being indexed by using the x-ms-indexing-directive header during the POST operation .Documents must adhere to size limits, as specified in DocumentDB Limits.

Request

Request Syntax

Method	Request URI	HTTP Version
POST	https://{databaseaccount}.documents.azure.com/dbs/{_rid-db}/colls/{_rid-col}/docs	HTTP/1.1

Note that the {databaseaccount} is the name of the DocumentDB account created under your subscription. The {_rid-db} value is the resource ID of the database. The {_rid-col} value is the resource ID of the collection that contains the document.

Request Headers

Standard Header	Description
Authorization	Required. The authentication type and signature token. Both master key and resource tokens are allowed for this operation. For more information, see Access Control on DocumentDB Resources.
Content-Type	Optional. The Content-Type header must be application/json.
User-Agent	Optional. The client user agent performing the request. The recommended format is {user agent name}/{version}. For example, the DocumentDB .NET SDK sets the User-Agent string to Microsoft.Document.Client/1.0.0.0.

Custom Header	Description
x-ms-date	Required. The date of the request, per RFC 1123. The date is expressed in Coordinated Universal Time format, e.g. Fri, 08 Apr 2015 03:52:31 GMT.
x-ms-version	Optional. The version of DocumentDB REST service. The latest version is used when the header is not provided. For more information, see Versioning for DocumentDB REST API.
x-ms-indexing-directive	Optional. The acceptable value is Include or Exclude. Include adds the document to the index. Exclude omits the document from indexing. The default for indexing behavior is determined by the automatic property’s value in the indexing policy for the collection.

Request Body

Property	Description
id	Required. This is a user settable property. It is the unique name that identifies the document, i.e. no two documents should share the same id. The id must not exceed 255 characters.
Custom	Any user defined JSON. For document size limit, see DocumentDB Limits.

Request Example

This sample show a JSON document for a book catalog entry.

POST https://contosomarketing.documents.azure.com/dbs/ehszAA==/colls/ehszALxRRgA=/docs HTTP/1.1
x-ms-date: Mon, 18 Apr 2015 05:44:01 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dANqs1FAethG7z%2btzpuJzdIpWJCeEmXPiFSGaoCuB3Lw%3d
x-ms-version: 2015-04-08
Host: contosomarketing.documents.azure.com
Content-Length: 311
Expect: 100-continue

{  
   "id":"Book2",
   "Title":"About Seattle",
   "Language":{  
      "id":"English"
   },
   "Author":{  
      "id":"Fred",
      "Location":{  
         "City":"Seattle",
         "Country":"United States"
      }
   },
   "Synopsis":"Seattle, the largest city in the U.S. Pacific Northwest...",
   "Pages":400,
   "Topics":[  
      {  
         "Title":"History of Seattle"
      },
      {  
         "Title":"Places to see in in Seattle"
      }
   ]
}

Response

Response Headers

This operation returns the following common headers. There may be additional standard and common headers returned.

Standard Header	Description
Content-Type	The Content-Type is application/json. DocumentDB always returns the response body in standard JSON format.
etag	This etag carries the same value as the etag value returned as part of the response body.
Date	The date-time of the response operation. This date time format conforms to the RFC 1123 date time format expressed in Coordinated Universal Time.

Custom Header	Description
x-ms-resource-quota	For this operation, the header shows the total allotted document size in kilobytes (KB). For more information on limits and quotas, see DocumentDB limits.
x-ms-resource-usage	For this operation, the header shows the current document size used in kilobytes (KB).
x-ms-request-charge	This is the number of request units (RU) consumed by the operation. For more information about request units, see Manage DocumentDB capacity and performance.
x-ms-activity-id	This is a unique identifier for the operation. It is used for trouble-shooting purposes.

Response Body

Property	Description
id	This is the unique name that identifies the document, i.e. no two documents can share the same id. The id must not exceed 255 characters.
custom	Any user-defined JSON.
_rid	This is a system generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the document resource.
_ts	This is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.
_self	This is a system generated property. It is the unique addressable URI for the resource.
_etag	This is a system generated property that specifies the resource etag required for optimistic concurrency control.
_attachments	This is a system generated property that specifies the addressable path for the attachments resource.

Response Status Codes

The following table lists common status codes returned by this operation. For information related to error status codes, see HTTP Status Codes.

Code	Description
201 Created	The operation was successful.
400 Bad Request	The JSON body is invalid. Check for missing curly brackets or quotes.
401 Unauthorized	The Authorization or x-ms-date header is not set. 401 is also returned when the Authorization header is set to an invalid authorization token. For more information on authorization tokens, see Access Control on DocumentDB Resources.
403 Forbidden	The authorization token has expired. 403 is also returned by this operation when the number of permissions in the account has reached its allowable quota. For more information on limits and quota, see DocumentDB limits.
409 Conflict	The id provided for the new document has been taken by an existing document.
413 Entity Too Large	The document size in the request exceeded the allowable document size. For more information about document size limits, see DocumentDB Limits.

Response Example

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
x-ms-last-state-change-utc: Mon, 18 Apr 2015 04:46:59.610 GMT
etag: 00002500-0000-0000-0000-53f192a00000
x-ms-resource-quota: documentsSize=10475520;
x-ms-resource-usage: documentsSize=0;
x-ms-schemaversion: 1.1
x-ms-request-charge: 7.96
x-ms-indexing-directive: Default
x-ms-serviceversion: version=1.0.240.1
x-ms-activity-id: 0bbad043-533f-4be5-a811-f10d4849c3cf
x-ms-session-token: 20
x-ms-gatewayversion: version=1.0.240.1
Date: Mon, 18 Apr 2015 05:44:00 GMT


{  
   "id":"Book2",
   "Title":"About Seattle",
   "Language":{  
      "id":"English"
   },
   "Author":{  
      "id":"Fred",
      "Location":{  
         "City":"Seattle",
         "Country":"United States"
      }
   },
   "Synopsis":"Seattle, the largest city in the U.S. Pacific Northwest...",
   "Pages":400,
   "Topics":[  
      {  
         "Title":"History of Seattle"
      },
      {  
         "Title":"Places to see in in Seattle"
      }
   ],
   "_rid":"ehszALxRRgACAAAAAAAAAA==",
   "_ts":1408340640,
   "_self":"dbs\/ehszAA==\/colls\/ehszALxRRgA=\/docs\/ehszALxRRgACAAAAAAAAAA==\/",
   "_etag":"00002500-0000-0000-0000-53f192a00000",
   "_attachments":"attachments\/"
}

Share via