A newer version of this documentation is available.

View Latest

Blobs

      +

      Introduction

      Couchbase Lite for C uses blobs to store the contents of images, other media files and similar format files as binary objects.

      The blob itself is not stored in the document. It is held in a separate content-addressable store indexed from the document and retrieved only on-demand.

      When a document is synchronized, the Couchbase Lite replicator adds an _attachments dictionary to the document’s properties if it contains a blob — see Figure 1.

      Blob Objects

      The blob as an object appears in a document as dictionary property — see, for example avatar in Figure 1.

      Other properties include length (the length in bytes), and optionally content_type (typically, its MIME type).

      The blob’s data (an image, audio or video content) is not stored in the document, but in a separate content-addressable store, indexed by the digest property — see Using Blobs.

      Constraints

      • Couchbase Lite
        Blobs can be arbitrarily large. They are only read on demand, not when you load a the document.

      • sync gateway
        The maximum content size is 20 MB per blob. If a document’s blob is over 20 MB, the document will be replicated but not the blob.

      Using Blobs

      The Blob API lets you access the blob’s data content as in-memory data (a Data object) or as an InputStream.

      The code in Example 1 shows how you might add a blob to a document and save it to the database. Here we use avatar as the property key and a jpeg file as the blob data.

      Example 1. Working with blobs
      // Note: Reading the data is implementation dependent, as with prebuilt databases
      // NOTE: No error handling, for brevity (see getting started)
      
      uint8_t buffer[128000];
      FILE* avatar_file = fopen("avatar.jpg", "rb");
      size_t read = fread(buffer, 1, 128000, avatar_file); (1)
      
      FLSliceResult avatar = FLSliceResult_CreateWith(buffer, read);
      CBLBlob* blob = CBLBlob_CreateWithData(FLSTR("image/jpeg"), FLSliceResult_AsSlice(avatar)); (2)
      FLSliceResult_Release(avatar);
      
      // TODO: Create shortcut blob method
      CBLError err;
      FLMutableDict properties = CBLDocument_MutableProperties(newTask);
      FLSlot_SetBlob(FLMutableDict_Set(properties, FLSTR("avatar")), blob);
      CBLDatabase_SaveDocument(db, newTask, &err); (3)
      1 Here we prepare a document to use for the example
      2 Create the blob using the retrieved image.
      Here we set image/jpg as the blob MIME type.
      3 Add the blob to a document, using avatar as the property key
      Saving the document generates a random access key for each blob stored in digest a SHA-1 encrypted property — see: Figure 1.
      We can use the avatar key to retrieve the blob object later. Note, this is the identity of the blob assigned by us; the replication auto-generates a blob for attachments and assigns its own name to it (for example, blob_1) — see Figure 1. The digest key will be the same as generated when we saved the blob document.

      Syncing

      When a document containing a blob object is synchronized, the Couchbase Lite replicator generates an _attachments dictionary with an auto-generated name for each blob attachment. This is different to the avatar key and is used internally to access the blob content.

      If you view a sync’d blob document in {cbs} Admin Console, you will see something similar to Figure 1, which shows the document with its generated _attachments dictionary, including the digest.

      attach replicated
      Figure 1. Sample Blob Document