Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

GridFS

Nesta página

  • Quando usar o GridFS
  • Usar GridFS
  • Collections do GridFS
  • Índices do GridFS
  • Fragmentação do GridFS

GridFS é uma especificação para armazenar e recuperar arquivos que excedem o limite de tamanhodo documento BSON de 16 MB.

Observação

O GridFS não é compatível com transações multidocumento.

Em vez de armazenar um arquivo em um único documento, o GridFS divide o arquivo em partes, ou chunks [1], e armazena cada chunk como um documento separado. Por padrão, o GridFS usa um tamanho de bloco padrão de 255 kB; ou seja, o GridFS divide um arquivo em blocos de 255 kB com exceção do último bloco. O último pedaço é tão grande quanto necessário. Da mesma forma, os arquivos que não são maiores do que o tamanho do bloco têm apenas um bloco final, usando apenas o espaço necessário mais alguns metadados adicionais.

GridFS usa duas collections para armazenar arquivos. Uma coleta armazena os blocos de arquivo e os outros armazenam metadados de arquivo. A seção Collections GridFS descreve cada collection em detalhes.

Ao queryr o GridFS para um arquivo, o driver reagrupará os blocos conforme necessário. Você pode realizar queries de intervalo em arquivos armazenados por meio do GridFS. Também é possível acessar informações de seções arbitrárias de arquivos, como para "pular" para o meio de um arquivo de vídeo ou áudio.

O GridFS é útil não apenas para armazenar arquivos que excedem 16 MB, mas também para armazenar quaisquer arquivos aos quais você deseja acesso sem precisar carregar o arquivo inteiro na memória. Consulte também Quando usar o GridFS.

Quando usar o GridFS

No MongoDB, use GridFS para armazenar arquivos maiores que 16 MB.

Em algumas situações, o armazenamento de arquivos grandes pode ser mais eficiente em um Banco de dados MongoDB do que em um sistema de arquivos no nível do sistema.

Não use o GridFS se precisar atualizar o conteúdo do arquivo inteiro atomicamente. Como alternativa, você pode armazenar múltiplas versões de cada arquivo e especificar a versão atual do arquivo nos metadados. Você pode atualizar o campo de metadados que indica o status "mais recente" em uma Atualização atômica após carregar a nova versão do arquivo e posterior remova versões anteriores, se necessário.

Além disso, se todos os seus arquivos forem menores do que o limite de tamanho do documento BSON de 16 MB, considere armazenar cada arquivo em um único documento em vez de usar o GridFS. Você pode utilizar o tipo de dados BinData para armazenar os dados binários. Consulte a documentação de seus drivers para obter detalhes sobre o uso do BinData.

Usar GridFS

Para armazenar e recuperar arquivos usando o GridFS, use uma das seguintes opções:

  • Um driver do MongoDB. Consulte a documentação do driver para obter informações sobre como usar o GridFS com seu driver.

  • A ferramenta de linha de comando mongofiles . Consulte a referência do mongofiles para documentação.

Collections do GridFS

O GridFS armazena arquivos em duas collections:

O GridFS coloca as collections em um bucket comum, prefixando cada uma com o nome do bucket. Por padrão, o GridFS usa duas coleções com um bucket chamado fs:

  • fs.files

  • fs.chunks

Você pode escolher um nome de contêiner diferente, como também, criar múltiplos blocos em um único banco de dados. O nome completo da collection, que inclui o nome do bucket, está sujeito ao limite de comprimento do namespace.

A collection chunks

Cada documento na collection chunks [1] representa um chunk distinto de um arquivo como representado no GridFS. Os documentos nesta collection têm o seguinte formulário:

{
  "_id" : <ObjectId>,
  "files_id" : <ObjectId>,
  "n" : <num>,
  "data" : <binary>
}

Um documento da collection chunks contém os seguintes campos:

chunks._id

O ObjectId exclusivo do chunk.

chunks.files_id

O _id do documento "pai", conforme especificado na collection files.

chunks.n

O número de sequência do chunk. GridFS numera todos os pedaços, começando com 0.

chunks.data

A carga útil do chunk como um tipo BSON Binary.

A collection files

Cada documento na collection files representa um arquivo no GridFS.

{
  "_id" : <ObjectId>,
  "length" : <num>,
  "chunkSize" : <num>,
  "uploadDate" : <timestamp>,
  "md5" : <hash>,
  "filename" : <string>,
  "contentType" : <string>,
  "aliases" : <string array>,
  "metadata" : <any>,
}

Os documentos na collection files contêm alguns ou todos os seguintes campos:

files._id

O identificador exclusivo deste documento. O _id é do tipo de dados que você escolheu para o documento original. O tipo padrão para documentos MongoDB é BSON ObjectId.

files.length

O tamanho do documento em bytes.

files.chunkSize

O tamanho de cada chunk em bytes. GridFS divide o documento em blocos de tamanho chunkSize, exceto o último, que é tão grande quanto necessário. O tamanho padrão é de 255 kilobytes (kB).

files.uploadDate

A data em que o documento foi armazenado pela primeira vez pelo GridFS. Este valor tem o tipo Date.

files.md5

Obsoleto(a)

O algoritmo MD5 é proibido por FIPS 140-2. Os drivers do MongoDB descontinuarão o suporte ao MD5 e removerão a geração do MD5 em versões futuras. Os aplicativos que exigem um resumo de arquivo devem implementá-lo fora do GridFS e armazená-lo em files.metadata.

Um hash MD5 do arquivo completo retornado pelo comando filemd5. Este valor tem o tipo String.

files.filename

Opcional. Um nome legível pelo ser humano para o arquivo GridFS.

files.contentType

Obsoleto(a)

Opcional. Um tipo de MIME válido para o arquivo GridFS. Somente para uso do aplicativo.

Utilize o files.metadata para armazenar informações relacionadas ao tipo MIME do arquivo GridFS.

files.aliases

Obsoleto(a)

Opcional. Uma array de strings de alias. Apenas para uso do aplicativo.

Utilize o files.metadata para armazenar informações relacionadas ao tipo MIME do arquivo GridFS.

files.metadata

Opcional. O campo de metadados pode ser de qualquer tipo de dados e pode conter qualquer informação adicional que você queira armazenar. Se você deseja adicionar campos arbitrários adicionais aos documentos na collection files, adicione-os a um objeto no campo de metadados.

Índices do GridFS

O GridFS usa índices em cada uma das coletas chunks e files para maior eficiência. Drivers que estão em conformidade com a especificação do GridFS crie automaticamente esses índices por conveniência. Você também pode criar quaisquer índices adicionais, conforme desejado, para atender às necessidades do seu aplicativo.

O índice chunks

O GridFS usa um índice composto exclusivo na collection chunks usando os campos files_id e n. Isso permite a recuperação eficiente de chunks, conforme demonstrado no exemplo a seguir:

db.fs.chunks.find( { files_id: myFileID } ).sort( { n: 1 } )

Drivers que estão em conformidade com a especificação do GridFS garantirá automaticamente que esse índice exista antes das operações de leitura e gravação. Consulte a documentação relevante do driver para saber o comportamento específico do seu aplicativo GridFS.

Se esse índice não existir, você poderá executar a seguinte operação para criá-lo usando o mongosh:

db.fs.chunks.createIndex( { files_id: 1, n: 1 }, { unique: true } );

O índice files

O GridFS utiliza um índice na collection files utilizando os campos filename e uploadDate. Esse índice permite a recuperação eficiente de arquivos, como mostrado neste exemplo:

db.fs.files.find( { filename: myFileName } ).sort( { uploadDate: 1 } )

Drivers que estão em conformidade com a especificação do GridFS garantirá automaticamente que esse índice exista antes das operações de leitura e gravação. Consulte a documentação relevante do driver para saber o comportamento específico do seu aplicativo GridFS.

Se esse índice não existir, você poderá executar a seguinte operação para criá-lo usando o mongosh:

db.fs.files.createIndex( { filename: 1, uploadDate: 1 } );
[1](1, 2) O uso do termo chunk no contexto do GridFS não está relacionado ao uso do termo chunk no contexto da fragmentação.

Fragmentação do GridFS

Existem duas collections a considerar com o GridFS - files e chunks.

chunks collection

Para fragmentar a coleta chunks, utilize { files_id : 1, n : 1 } ou { files_id : 1 } como o índice da chave de fragmento. files_id é um ObjectId e altera monotonicamente.

Para drivers do MongoDB que não executam filemd5 para verificar o carregamento bem-sucedido (por exemplo, drivers do MongoDB com suporte ao MongoDB 4.0 ou superior), você pode usar a fragmentação hasheada para a collection chunks.

Se o driver do MongoDB executar filemd5, você não poderá usar o Hashed Sharding. Para obter detalhes, consulte SERVER-9888.

files collection

A coleta files é pequena e contém somente metadados. Nenhuma das chaves necessárias para o GridFS se emprestam a uma distribuição uniforme em um ambiente fragmentado. Deixar files sem fragmentação permite que todos os documentos de metadados de arquivos residam no fragmento primário.

Se você necessita fragmentar a collection files, use o campo _id, possivelmente em combinação com um campo do aplicativo.

← Gerenciar o registro no diário
Perguntas frequentes: Armazenamento MongoDB →

Nesta página