Armazenar arquivos grandes

Visão geral

Neste guia, você pode aprender como armazenar e recuperar arquivos grandes no MongoDB usando GridFS. O GridFS é uma especificação implementada pelo driver C++ que descreve como divisão os arquivos em blocos ao armazená-los e remontá-los ao recuperá-los. A implementação do driver do GridFS é uma abstração que gerencia as operações e a organização do armazenamento de arquivos.

Use GridFS if the size of your files exceeds the BSON document size limit of 16MB. For more detailed information about whether GridFS is suitable for your use case, see GridFS in the MongoDB Server manual.

Como funciona o GridFS

O GridFS organiza os arquivos em um bucket, um grupo de coleções do MongoDB que contém os blocos de arquivos e as informações que os descrevem. O bloco contém as seguintes coleções, nomeadas usando a convenção definida na especificação do GridFS:

• chunks collection, que armazena os chunks de arquivos binários

• files coleção, que armazena os metadados do arquivo

O driver cria o bucket GridFS , se ele não existir, quando você grava dados pela primeira vez. O bucket contém as collections anteriores prefixadas com o nome de bucket padrão fs, a menos que você especifique um nome diferente. Para garantir a recuperação eficiente dos arquivos e de seus respectivos metadados, o driver cria um índice em cada collection. O driver garante que esses índices existam antes de realizar operações de leitura e gravação no bucket GridFS .

For more information about GridFS indexes, see GridFS Indexes in the MongoDB Server manual.

Ao usar o GridFS para armazenar arquivos, o driver divide os arquivos em partes menores, cada um representado por um documento separado na coleção chunks. Ele também cria um documento na coleção files que contém um ID de arquivo, nome de arquivo e outros metadados de arquivo. Você pode carregar o arquivo passando um fluxo para o driver C++ para consumir ou criando um novo fluxo e gravando diretamente nele.

O diagrama a seguir mostra como o GridFS divide os arquivos quando eles são carregados em um bucket:

Ao recuperar arquivos, o GridFS obtém os metadados da coleção files no bloco especificado e utiliza as informações para reconstruir o arquivo a partir de documentos na coleção chunks. Você pode ler o arquivo gravando seu conteúdo em um fluxo existente ou criando um novo fluxo que aponte para o arquivo.

Crie um intervalo GridFS

Para começar a armazenar ou recuperar arquivos do GridFS, chame o método gridfs_bucket() no seu banco de dados de dados. Este método acessa um bucket existente ou cria um novo bucket se não existir.

O exemplo seguinte chama o método gridfs_bucket() no banco de dados de dados do db :

auto bucket = db.gridfs_bucket();

mongocxx::options::gridfs::bucket opts;
opts.bucket_name("myCustomBucket");
auto bucket = db.gridfs_bucket(opts);

Fazer upload de arquivos

Você pode fazer upload de arquivos para um bucket GridFS usando os seguintes métodos:

• open_upload_stream(): abre um novo fluxo de upload para o qual você pode escrever conteúdo de arquivo

• upload_from_stream(): Uploads the contents of an existing stream to a GridFS file

mongocxx::options::gridfs::upload opts;
opts.chunk_size_bytes(1048576);
auto uploader = bucket.open_upload_stream("my_file", opts);
// ASCII for "HelloWorld"
std::uint8_t bytes[10] = {72, 101, 108, 108, 111, 87, 111, 114, 108, 100};
for (auto i = 0; i < 5; ++i) {
    uploader.write(bytes, 10);
}
uploader.close();

std::ifstream file("/path/to/input_file", std::ios::binary);
bucket.upload_from_stream("new_file", &file);

Recuperar informações do arquivo

Nesta seção, você pode aprender como recuperar metadados de arquivo armazenados na coleção files do contêiner GridFS. Os metadados contêm informações sobre o arquivo a que se refere, incluindo:

• O _id do arquivo

• O nome do arquivo

• O tamanho/comprimento do arquivo

• A data e a hora do carregamento

• Um documento metadata no qual você pode armazenar outras informações

Para recuperar arquivos de um GridFS , chame o método mongocxx::gridfs::bucket::find() no seu contêiner. O método retorna uma instância do mongocxx::cursor da qual você pode acessar os resultados. Para saber mais sobre cursores, consulte o guia Acessar dados de um cursor.

auto cursor = bucket.find({});
for (auto&& doc : cursor) {
    std::cout << bsoncxx::to_json(doc) << std::endl;
}

{ "_id" : { "$oid" : "..." }, "length" : 13, "chunkSize" : 261120, "uploadDate" :
{ "$date" : ... }, "filename" : "new_file" }
{ "_id" : { "$oid" : "..." }, "length" : 50, "chunkSize" : 1048576, "uploadDate" :
{ "$date" : ... }, "filename" : "my_file" }

Baixar arquivos

Você pode baixar arquivos de um bucket GridFS usando os seguintes métodos:

• open_download_stream(): Opens a new download stream from which you can read the file contents

• download_to_stream(): Writes the entire file to an existing download stream

auto doc = db["fs.files"].find_one(make_document(kvp("filename", "new_file")));
auto id = doc->view()["_id"].get_value();
auto downloader = bucket.open_download_stream(id);
std::vector<uint8_t> buffer(downloader.file_length());
downloader.read(buffer.data(), buffer.size());

std::ofstream output_file("/path/to/output_file", std::ios::binary);
auto doc = db["fs.files"].find_one(make_document(kvp("filename", "new_file")));
auto id = doc->view()["_id"].get_value();
bucket.download_to_stream(id, &output_file);

Excluir arquivos

Use o método delete_file() para remover o documento de collection de um arquivo e os chunks associados do seu bucket. Isso exclui efetivamente o arquivo. Você deve especificar o arquivo pelo campo _id em vez do nome do arquivo.

O exemplo a seguir mostra como excluir um arquivo chamado "my_file" passando seu valor _id para delete_file():

auto doc = db["fs.files"].find_one(make_document(kvp("filename", "my_file")));
auto id = doc->view()["_id"].get_value();
bucket.delete_file(id);

Documentação da API

Para saber mais sobre como usar o driver C++ para armazenar e recuperar arquivos grandes, consulte a seguinte documentação da API:

• gridfs_bucket()

• mongocxx::options::gridfs::bucket

• open_upload_stream()

• upload_from_stream()

• find()

• open_download_stream()

• download_to_stream()

• delete_file()