Armazenar arquivos grandes

Visão geral

Neste guia, você pode aprender como armazenar e recuperar arquivos grandes no MongoDB usando GridFS. O sistema de armazenamento GridFS divide os arquivos em chunks ao armazená-los e reagrupa esses arquivos 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 o GridFS se o tamanho de qualquer um dos seus arquivos exceder o limite de tamanho de documento BSON de 16 MB. Para obter informações mais detalhadas sobre se o GridFS é adequado para seu caso de uso, consulte GridFS no manual do MongoDB Server .

Como funciona o GridFS

O GridFS organiza 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 bucket contém as seguintes coleções:

• chunks: Armazena os blocos de arquivos binários

• files: armazena os metadados do arquivo

O driver cria o bucket GridFS , se ele ainda não existir, quando você grava dados pela primeira vez. O bucket contém as collections chunks e files 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 .

Para obter mais informações sobre os índices do GridFS , consulte Índices do GridFS no manual do MongoDB Server .

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.

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 contêiner especificado e utiliza as informações para reconstruir o arquivo a partir de documentos na coleção chunks.

Crie um intervalo GridFS

Para começar a usar o GridFS para armazenar ou recuperar arquivos, crie uma nova instância da classe GridFSBucket , passando um objeto IMongoDatabase que representa seu banco de dados. Este método acessa um bucket existente ou cria um novo bucket se não existir.

O exemplo seguinte cria uma nova instância da classe GridFSBucket para o banco de dados db :

var client = new MongoClient("<connection string>");
var database = client.GetDatabase("db");
// Creates a GridFS bucket or references an existing one
var bucket = new GridFSBucket(database);

var options = new GridFSBucketOptions { BucketName = "myCustomBucket" };
var customBucket = new GridFSBucket(database, options);

Fazer upload de arquivos

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

• OpenUploadStream() ou OpenUploadStreamAsync(): abre um novo fluxo de upload para o qual você pode gravar o conteúdo do arquivo

• UploadFromStream() ou UploadFromStreamAsync(): faz o upload do conteúdo de um stream existente para um arquivo GridFS

As seções a seguir descrevem como usar esses métodos.

using (var uploader = bucket.OpenUploadStream("my_file"))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    uploader.Write(bytes, 0, bytes.Length);
    uploader.Close();
}

using (var uploader = await bucket.OpenUploadStreamAsync("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    await uploader.WriteAsync(bytes, 0, bytes.Length);
    await uploader.CloseAsync();
}

var options = new GridFSUploadOptions
{
    ChunkSizeBytes = 1048576 // 1 MB
};
using (var uploader = bucket.OpenUploadStream("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    uploader.Write(bytes, 0, bytes.Length);
    uploader.Close();
}

var options = new GridFSUploadOptions
{
    ChunkSizeBytes = 1048576 // 1 MB
};
using (var uploader = await bucket.OpenUploadStreamAsync("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    await uploader.WriteAsync(bytes, 0, bytes.Length);
    await uploader.CloseAsync();
}

using (var fileStream = new FileStream("/path/to/input_file", FileMode.Open, FileAccess.Read))
{
    bucket.UploadFromStream("new_file", fileStream);
}

using (var fileStream = new FileStream("/path/to/input_file", FileMode.Open, FileAccess.Read))
{
    await bucket.UploadFromStreamAsync("new_file", fileStream);
}

Baixar arquivos

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

• OpenDownloadStream() ou OpenDownloadStreamAsync(): abre um novo fluxo de downloads do qual você pode ler o conteúdo do arquivo

• DownloadToStream() ou DownloadToStreamAsync(): grava o conteúdo de um arquivo GridFS em um fluxo existente

As seções a seguir descrevem esses métodos em mais detalhes.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    using (var downloader = bucket.OpenDownloadStream(doc.Id))
    {
        var buffer = new byte[downloader.Length];
        downloader.Read(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    using (var downloader = await bucket.OpenDownloadStreamAsync(doc.Id))
    {
        var buffer = new byte[downloader.Length];
        await downloader.ReadAsync(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    var options = new GridFSDownloadOptions
    {
        Seekable = true
    };
    using (var downloader = bucket.OpenDownloadStream(id, options))
    {
        var buffer = new byte[downloader.Length];
        downloader.Read(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    var options = new GridFSDownloadOptions
    {
        Seekable = true
    };
    using (var downloader = await bucket.OpenDownloadStreamAsync(doc.Id, options))
    {
        var buffer = new byte[downloader.Length];
        await downloader.ReadAsync(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    using (var outputFile = new FileStream("/path/to/output_file", FileMode.Create, FileAccess.Write))
    {
        bucket.DownloadToStream(doc.Id, outputFile);
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    using (var outputFile = new FileStream("/path/to/output_file", FileMode.Create, FileAccess.Write))
    {
        await bucket.DownloadToStreamAsync(doc.Id, outputFile);
    }
}

Encontrar arquivos

Para localizar arquivos em um contêiner GridFS , chame o método Find() ou FindAsync() em sua instância do GridFSBucket. Esses métodos aceitam os seguintes parâmetros:

O seguinte exemplo de código mostra como recuperar e imprimir metadados de arquivo de arquivos em um bucket GridFS . O método Find() retorna uma instância IAsyncCursor<GridFSFileInfo> da qual você pode acessar os resultados. Ela usa um foreach loop para iterar pelo cursor retornado e exibir o conteúdo dos arquivos carregados nos exemplos de Carregar arquivos.

Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

var filter = Builders<GridFSFileInfo>.Filter.Empty;
var files = bucket.Find(filter);
foreach (var file in files.ToEnumerable())
{
    Console.WriteLine(file.ToJson());
}

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

var filter = Builders<GridFSFileInfo>.Filter.Empty;
var files = await bucket.FindAsync(filter);
await files.ForEachAsync(file => Console.Out.WriteLineAsync(file.ToJson()))

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

Para personalizar a operação de localizar, passe uma instância da classe GridFSFindOptions para o método Find() ou FindAsync(). A classe GridFSFindOptions contém as seguintes propriedades:

Excluir arquivos

Para excluir arquivos de um contêiner GridFS , chame o método Delete() ou DeleteAsync() na sua instância do GridFSBucket. Esse método remove a coleção de metadados de um arquivo e seus blocos associados do seu bloco.

Os métodos Delete e DeleteAsync() aceitam os seguintes parâmetros:

O seguinte exemplo de código mostra como excluir um arquivo denominado "my_file" passando seu valor _id para delete_file():

• Utiliza a classe Builders para criar um filtro que corresponda ao arquivo denominado "my_file"

• Utiliza o método Find() para localizar o arquivo denominado "my_file"

• Passa o valor _id do arquivo para o método Delete() para excluir o arquivo

Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    bucket.Delete(doc.Id);
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    await bucket.DeleteAsync(doc.Id);
}

Documentação da API

Para saber mais sobre as classes usadas nesta página, consulte a seguinte documentação da API:

• GridFSBucket

• GridFSBucketOptions

• GridFSDownloadOptions

• GridFSFindOptions

• GridFSUploadOptions

• GridFSFileInfo

Para saber mais sobre os métodos da classe GridFSBucket usados nesta página, consulte a seguinte documentação da API:

• OpenUploadStream()

• OpenUploadStreamAsync()

• UploadFromStream()

• UploadFromStreamAsync()

• OpenDownloadStream()

• OpenDownloadStreamAsync()

• DownloadToStream()

• DownloadToStreamAsync()

• Find()

• FindAsync()

• Delete()

• DeleteAsync()