2.8. Blobs

Blobs are strings that are not automatically loaded into memory. It is a convenient feature to store large pieces of data, such as photos or other media. For each blob, only the position and size of the data are loaded into memory. The content of a blob can be loaded on demand with the read_blob method of the file object.

Here is an example database schema:

create_table person
add_field person name blob
add_field person city string

And the unit test that demonstrates how to use a blob:

#include "db/blob/Writable_Database.h"
#include "db/blob/Readonly_Database.h"
#include "joedb/journal/Memory_File.h"

#include "gtest/gtest.h"

/////////////////////////////////////////////////////////////////////////////
TEST(Compiler, blob)
/////////////////////////////////////////////////////////////////////////////
{
 joedb::Memory_File file;

 //
 // A blob is created with the write_blob function
 //
 {
  blob::Writable_Database db(file);
  const auto person = db.new_person();
  const joedb::Blob name_blob = db.write_blob("Jacques");
  db.set_name(person, name_blob);
  EXPECT_EQ("Jacques", db.read_blob(name_blob));
  db.set_city(person, "Paris");
  db.soft_checkpoint();
 }

 //
 // The content of a blob is not kept in RAM. In order to access it,
 // it must be explicitly read from the file.
 //
 {
  blob::Readonly_Database db(file);

  const auto person = db.get_person_table().first();
  EXPECT_EQ("Paris", db.get_city(person));
  const joedb::Blob name_blob = db.get_name(person);
  EXPECT_EQ("Jacques", file.read_blob(name_blob));
 }

 //
 // It is possible to read directly from the db when it is not read-only
 //
 {
  blob::Writable_Database db(file);

  const auto person = db.get_person_table().first();
  const joedb::Blob name_blob = db.get_name(person);
  EXPECT_EQ("Jacques", db.read_blob(name_blob));
 }
}

In order to get better performance when manipulating a large amount of blob data, blobs can be stored in a separate file. This way, non-blob data will be stored contiguously, and can be read much faster. It is particularly recommended to use a separate blob database in a distributed application, since blobs can then be obtained on demand, without having to download a replica of the whole database. See the Server_File class documentation for more details.