Azure Cosmos DB is a globally distributed multi-model database that supports the document, graph, and key-value data models. The content in this section is for creating, querying, and managing document resources using the SQL API via REST.

The document resource is represented by docs in the Azure Cosmos DB resource model. A document consists of user-defined content in JSON format. Aside from the required ID property, users can define any arbitrary elements, structures, and hierarchies for the content. The ID element is a unique string that is user-settable and must not exceed 255 characters. You can insert, replace, delete, read, enumerate, and query arbitrary JSON documents in a collection.

Azure Cosmos DB does not require any schema or secondary indexes in order to support querying over documents in a collection. By default, documents are automatically and indexed in a consistent manner, thus making a document queryable as soon as it is created.

  • Documents are stored within collections. For more information on collections, see Collections.
  • A document can contain one or more attachments. For more information on attachments, see Attachments.
  • User access to documents can be managed via permissions. For more information on permissions, see Permissions.

This sample JSON document shows the entry for a volcano in a collection. The entry includes the volcano name, location information including geospatial data, and system defined elements such as _rid, _ts, _self, _etag, and _attachments.

  "Volcano Name": "Agua de Pau",  
  "Country": "Portugal",  
  "Region": "Azores",  
  "Location": {  
    "type": "Point",  
    "coordinates": [  
  "Elevation": 947,  
  "Type": "Stratovolcano",  
  "Status": "Historical",  
  "Last Known Eruption": "Last known eruption from 1500-1699, inclusive",  
  "id": "d44c94b6-81f8-4b27-4970-f79b149529d3",  
  "_rid": "Sl8fALN4sw4BAAAAAAAAAA==",  
  "_ts": 1448049512,  
  "_self": "dbs/Sl8fAA==/colls/Sl8fALN4sw4=/docs/Sl8fALN4sw4BAAAAAAAAAA==/",  
  "_etag": "\"0000443f-0000-0000-0000-564f7b680000\"",  
  "_attachments": "attachments/"  
Property Description
id Required. It is a user settable property. It is the unique name that identifies the document, that is, no two documents share the same ID within a logical partition. Partition and ID uniquely identifies an item in the database. The id field must not exceed 255 characters.
_rid It 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 It is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.
_self It is a system generated property. It is the unique addressable URI for the resource.
_etag It is a system generated property that specifies the resource etag required for optimistic concurrency control.
_attachments It is a system generated property that specifies the addressable path for the attachments resource.


You can do the following tasks with documents:

See Also