Azure Cosmos DB is a a globally distributed multi-model databases that supports the document, graph, cassandra, and table data models. The content in this section is for managing attachment resources using the SQL API via REST.

Attachments are special documents that contain references and associated metadata with an external blob or media file.

Developers can choose to have:

  • The attachment media/blob managed by Azure Cosmos DB or
  • Store it with an external blob service provider such as OneDrive, Dropbox, etc. and store the reference metadata for attachment in Azure Cosmos DB.

The attachment resource is represented by attachments in the Azure Cosmos DB REST resource model. The attachment resource has a fixed schema. Regardless of where the raw media is stored, the following properties are required.

The following example illustrates the JSON construct of a document attachment.

Property Description
id Required. This is a user settable property. It is the unique name that identifies the attachment, i.e. no two attachments share the same id for the same document. The id must not exceed 255 characters.
contentType Required. This is a user settable property. It specifies the content type of the attachment. When submitting the attachment bits as the body, Cosmos DB sets the contentType to the type set in the Content-Type header.
Media Required. This is the URL link or file path where the attachment resides.
_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 attachment 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.

Common response headers

The following information is common to all responses related to attachments:

Header Description
x-ms-max-media-storage-usage-mb When using Cosmos DB attachment storage to store raw media, this header shows the total allotted attachment storage quota for the account.
x-ms-media-storage-usage-mb When using Cosmos DB attachment storage to store raw media, this header shows the current attachment storage consumed.


You can do the following with attachments:

  • Create an Attachment

  • Replace an Attachment

  • List Attachments

  • Delete Attachments

    Note that the attachment content is not indexed or searchable; the attachment resource properties are indexed and searchable.

    These operations are similar to the ones for Documents. Instead of performing the operations against the docs, they are preformed against the attachments resource path under a particular document. Hence, we will skip elaborating each of the operations. Instead, in the next section, we will discuss how to create an attachment with raw media posting and with metadata-only posting.

See Also