Blog

Adding Attachments to a Document in CouchDB

July 10, 2009

To start off, here are the links to my previous posts about CouchDB:

  1. Relaxing on the Couch(DB)
  2. Installing the Couch(DB)
  3. PUTting the Couch(DB) in Your Living Room
  4. GETting Documents From CouchDB
  5. DELETE Documents From CouchDB

Today, I want to talk about how to create attachments for a document. Documents in CouchDB can have attachments just like an email. CouchDB has two ways for dealing with attachments:

  1. Inline Attachments
  2. Standalone Attachments

Inline Attachments

Inline attachments can be added to a document by using the dedicated _attachments attribute while PUTting the document into CouchDB.

For creating an attachment, we need to provide a file name, the MIME type and the base64 encoded binary data. Its even possible to have multiple attachments for a single document.

Standalone Attachments

Standalone attachments are a fairly recent feature of CouchDB that has been added to version 0.9. As it name implies, it involves adding, updating and removing attachments without the document itself being involved. 

The major difference and advantage of this approach is that the binary data is sent directly to CouchDB without the need for a base64 conversion on both the client and server. This implies a significant performance improvement when storing attachments in CouchDB. Notice that you still need to provide a MIME type using the Content-Type header.

GETting Documents with Attachments

When retrieving a document with either an inline or standalone attachment, the actual binary data is not returned. Instead, CouchDB returns a stub to inform that the requested document has an attachment associated with it. 

In order to retrieve the binary data of the attachment itself (yes please!), we have to issue a second GET but now using both the document identifier and the file name of the attachment.

PUT /documentstore/4f754d4b-540d-4b77-8507-6b7243ef8325 HTTP/1.1

{
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"}],
"_attachments":
{
  "The Universe in a Nutshell.pdf": 
  {
    "content_type": "application/pdf",
    "data": "JVBERi0xLjUNCiW1tbW1DQox ... "
  }
}}

CouchDB responds to this request by returning the binary data of the attachment. When an inline attachment is used, the binary data automatically gets decoded.   

For my next post, I will talk about MapReduce functions providing a simple example of a Map function in particular. 

Till next time.

If you and your team want to learn more about how to write maintainable unit tests and get the most out of TDD practices, make sure to have look at our trainings and workshops or check out the books section. Feel free to reach out at infonull@nullprincipal-itnull.be.

Profile picture of Jan Van Ryswyck

Jan Van Ryswyck

Thank you for visiting my blog. I’m a professional software developer since Y2K. A blogger since Y2K+5. Provider of training and coaching in XP practices. Curator of the Awesome Talks list. Past organizer of the European Virtual ALT.NET meetings. Thinking and learning about all kinds of technologies since forever.

Comments

About

Thank you for visiting my website. I’m a professional software developer since Y2K. A blogger since Y2K+5. Author of Writing Maintainable Unit Tests. Provider of training and coaching in XP practices. Curator of the Awesome Talks list. Thinking and learning about all kinds of technologies since forever.

Contact information

(+32) 496 38 00 82

infonull@nullprincipal-itnull.be