What are Attachments

In RavenDB, attachments are binary streams which can be bound to an existing document. Each attachment has a name, and you can specify the content type (image/png or application/pdf for example).

A document can have any number of attachments.

Each attachment is bound to an existing document. In order to get a document, you'll need to specify the document ID and the attachment name. What's great in this approach is that you can specify the attachment's metadata in the document itself, and this document can be queried as any other document.

Example I

In order to store an album of pictures in RavenDB, you can create the following "albums/1" document:

{
    "UserId": "users/1",
    "Name": "Holidays",
    "Description": "Holidays travel pictures of the all family",
    "Tags": ["Holidays Travel", "All Family"],
    "@metadata": {
        "@collection": "Albums"
    }
}

This document can have the following attachments:

Example II

You can store a users/1 document and attach to it to a profile picture. When requesting the document from the server the results would be:

{
  "Name": "Hibernating Rhinos",
  "@metadata": {
    "@attachments": [
      {
        "ContentType": "image/png",
        "Hash": "iFg0o6D38pUcWGVlP71ddDp8SCcoEal47kG3LtWx0+Y=",
        "Name": "profile.png",
        "Size": 33241
      }
    ],
    "@collection": "Users",
    "@change-vector": "A:1061-D11EJRPTVEGKpMaH2BUl9Q",
    "@flags": "HasAttachments",
    "@id": "users/1",
    "@last-modified": "2017-12-05T12:36:24.0504021Z"
  }
}

Note that this document has an HasAttachments flag and an @attachments array with the attachment's info.

You can see the attachment's name, content type, hash and size.

Transaction Support

In RavenDB, attachment and documents are stored as ACID transaction: You either get all of them saved to disk or none.

Revisions and Attachments

When the revisions feature is turned on in your database, each attachment addition to a document (or deletion from a document) will create a new revision of the document, as there will be a change to the document's metadata, as shown in example #2.