Menu Docs
Página inicial do Docs
/
Línguas
/
Go
/
Driver GO
/
Fundamentos

GridFS

Nesta página

  • Visão geral
  • Como funciona o GridFS
  • Usar GridFS
  • Crie um intervalo GridFS
  • Fazer upload de arquivos
  • Recuperar informações do arquivo
  • Baixar arquivos
  • Renomear arquivos
  • Excluir arquivos
  • Excluir um bucket do GridFS
  • Recursos adicionais
  • Documentação da API

Visão geral

Neste guia, você aprenderá a armazenar e extrair arquivos grandes no MongoDB usando a especificação GridFS. O GridFS divide arquivos grandes em blocos e armazena cada bloco como um documento separado. Quando você consulta o GridFS para um arquivo, o driver monta os blocos conforme necessário. A implementação de 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 dos seus arquivos exceder o limite de tamanho de documento BSON de 16 MB. O GridFS também ajuda a acessar arquivos sem carregar todo o arquivo na memória. Para obter informações mais detalhadas sobre se o GridFS é adequado para seu caso de uso, consulte apágina de manual do servidor GridFS .

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:

  • A coleção chunks, que armazena os blocos de arquivos binários.

  • A collection files, que armazena os metadados do arquivo.

Quando você cria um novo bucket GridFS, o driver cria as coleções anteriores. O nome de bucket padrão fs pré-estabelece os nomes da coleção, a menos que você especifique um nome de bucket diferente. O driver cria o novo bucket GridFS durante a primeira operação de gravação.

O driver também cria um índice em cada coleção para garantir a recuperação eficiente de arquivos e metadados relacionados. O driver cria índices se eles ainda não existem e quando o bucket está vazio. Para obter mais informações sobre os índices do GridFS, consulte a página do manual do servidor sobre Índices do GridFS.

Ao armazenar arquivos com GridFS, o driver divide os arquivos em partes menores, cada um representado por um documento separado na coleção do 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 carregados:

Um diagrama que mostra como o GridFS carrega um arquivo em um bloco

Ao recuperar arquivos, o GridFS obtém os metadados da coleção files no bloco especificado, então utiliza estas informações para reconstruir o arquivo a partir de documentos na coleção chunks. Você pode ler o arquivo na memória ou enviá-lo para um stream.

Usar GridFS

Para saber mais sobre as operações GridFS e como executá-las, acesse as seções abaixo:

Crie um intervalo GridFS

Para armazenar ou recuperar arquivos do GridFS, crie um contêiner ou obtenha uma referência a um contêiner existente em um banco de dados MongoDB. Para criar uma instância GridFSBucket , chame o método NewBucket() com um parâmetro de banco de dados:

db := client.Database("db")
bucket, err := gridfs.NewBucket(db)
if err != nil {
   panic(err)
}

Observação

Se um contêiner GridFS já existir, o método NewBucket() retornará uma referência ao contêiner em vez de instanciar um novo.

Por padrão, o novo bucket é denominado fs. Para instanciar um bucket com um nome personalizado, chame o método SetName() em uma instância BucketOptions da seguinte forma:

db := client.Database("db")
opts := options.GridFSBucket().SetName("custom name")
bucket, err := gridfs.NewBucket(db, opts)
if err != nil {
   panic(err)
}

Fazer upload de arquivos

Você pode carregar um arquivo em um contêiner GridFS de uma das seguintes maneiras:

  • Utilize o método UploadFromStream(), que lê a partir de um fluxo de entrada.

  • Use o método OpenUploadStream(), que grava em um fluxo de saída.

Para qualquer processo de carregamento, você pode especificar informações de configuração em uma instância do UploadOptions. Para ver uma lista completa dos UploadOptions campos , acesse a documentação da API.

Fazer upload com um fluxo de entrada

Para carregar um arquivo com um fluxo de entrada, utilize o método UploadFromStream() com os seguintes parâmetros:

  • O nome do arquivo

  • Um io.Reader, com seu arquivo aberto como um parâmetro

  • Um parâmetro opts opcional para modificar o comportamento de UploadFromStream()

O exemplo de código a seguir lê de um arquivo chamado file.txt e carrega o conteúdo em um contêiner GridFS. Utiliza um parâmetro opts para definir metadados de arquivo:

file, err := os.Open("path/to/file.txt")
uploadOpts := options.GridFSUpload().SetMetadata(bson.D{{"metadata tag", "first"}})
objectID, err := bucket.UploadFromStream("file.txt", io.Reader(file),
   uploadOpts)
if err != nil {
   panic(err)
}
fmt.Printf("New file uploaded with ID %s", objectID)

Fazer upload com um fluxo de saída

Para carregar um arquivo com um fluxo de saída, utilize o método OpenUploadStream() com os seguintes parâmetros:

  • O nome do arquivo

  • Um parâmetro opts opcional para modificar o comportamento de OpenUploadStream()

O exemplo de código a seguir abre um fluxo de upload em um bucket do GridFS e define o número de bytes em cada bloco com um parâmetro opts. Em seguida, ele chama o método Write() no conteúdo de file.txt para escrever seu conteúdo no fluxo:

file, err := os.Open("path/to/file.txt")
if err != nil {
	panic(err)
}
// Defines options that specify configuration information for files
// uploaded to the bucket
uploadOpts := options.GridFSUpload().SetChunkSizeBytes(200000)
// Writes a file to an output stream
uploadStream, err := bucket.OpenUploadStream("file.txt", uploadOpts)
if err != nil {
	panic(err)
}
fileContent, err := io.ReadAll(file)
if err != nil {
	panic(err)
}
var bytes int
if bytes, err = uploadStream.Write(fileContent); err != nil {
	panic(err)
}
fmt.Printf("New file uploaded with %d bytes written", bytes)

Recuperar informações do arquivo

Você pode recuperar metadados de arquivo armazenados na coleção files do contêiner GridFS. Cada documento na coleção files contém as seguintes informações:

  • O ID do arquivo

  • O comprimento do arquivo

  • O tamanho máximo do chunk

  • A data e a hora do carregamento

  • O nome do arquivo

  • Um documento metadata no qual você pode armazenar qualquer outra informação

Para recuperar dados do arquivo, chame o método Find() em uma instância GridFSBucket. Você pode passar um filtro de query como argumento para Find() para corresponder somente a determinados documentos de arquivo.

Observação

O método Find() exige um filtro de query como um parâmetro. Para corresponder a todos os documentos na coleção files, passe um filtro de query vazio para Find().

O exemplo a seguir recupera o nome do arquivo e o tamanho dos documentos na coleção files com valores length maiores que 1500:

filter := bson.D{{"length", bson.D{{"$gt", 1500}}}}
cursor, err := bucket.Find(filter)
if err != nil {
   panic(err)
}
type gridfsFile struct {
   Name   string `bson:"filename"`
   Length int64  `bson:"length"`
}
var foundFiles []gridfsFile
if err = cursor.All(context.TODO(), &foundFiles); err != nil {
   panic(err)
}
for _, file := range foundFiles {
   fmt.Printf("filename: %s, length: %d\n", file.Name, file.Length)
}

Baixar arquivos

Você pode baixar um arquivo GridFS de uma das seguintes maneiras:

  • Utilize o método DownloadToStream() para baixar um arquivo para um fluxo de saída.

  • Utilize o método OpenDownloadStream() para abrir um fluxo de entrada.

Baixar um arquivo para um fluxo de saída

Você pode baixar um arquivo em um bucket GridFS diretamente para um fluxo de saída usando o método DownloadToStream(). DownloadToStream() usa um ID de arquivo e um io.Writer como parâmetro. O método baixa o arquivo com o ID de arquivo especificado e grava em io.Writer.

O exemplo a seguir baixa um arquivo e grava em um buffer de arquivo:

id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88")
fileBuffer := bytes.NewBuffer(nil)
if _, err := bucket.DownloadToStream(id, fileBuffer); err != nil {
   panic(err)
}

Baixar um arquivo para um fluxo de entrada

Você pode baixar um arquivo em um contêiner GridFS para memória com um fluxo de entrada utilizando o método OpenDownloadStream(). OpenDownloadStream() obtém um ID de arquivo como um parâmetro e retorna um fluxo de entrada do qual você pode ler o arquivo.

O exemplo a seguir baixa um arquivo na memória e lê seu conteúdo:

id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88")
downloadStream, err := bucket.OpenDownloadStream(id)
if err != nil {
   panic(err)
}
fileBytes := make([]byte, 1024)
if _, err := downloadStream.Read(fileBytes); err != nil {
   panic(err)
}

Renomear arquivos

Você pode atualizar o nome de um arquivo GridFS em seu bucket utilizando o método Rename(). Passe um valor de ID de arquivo e um novo valor de filename como argumentos para Rename().

O exemplo a seguir renomeia um arquivo para "mongodbTutorial.zip":

id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88")
if err := bucket.Rename(id, "mongodbTutorial.zip"); err != nil {
    panic(err)
}

Excluir arquivos

Você pode remover um arquivo do bucket GridFS usando o método Delete(). Passe um valor de ID de arquivo como argumento para Delete().

O exemplo a seguir exclui um arquivo:

id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88")
if err := bucket.Delete(id); err != nil {
   panic(err)
}

Excluir um bucket do GridFS

Você pode excluir um bucket GridFS usando o método Drop().

O seguinte exemplo de código exclui um bucket GridFS:

if err := bucket.Drop(); err != nil {
   panic(err)
}

Recursos adicionais

Para saber mais sobre o GridFS e suas operações, visite a página do manual do GridFS.

Documentação da API

Para saber mais sobre os métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

← Monitoramento de conexão
Coleções de Time Series →

Nesta página