GridFS

Overview

En esta guía, puedes aprender cómo almacenar y recuperar archivos grandes en MongoDB utilizando la especificación GridFS. GridFS divide los archivos grandes en fragmentos y almacena cada fragmento como un documento separado. Cuando usted query GridFS por un archivo, el driver ensambla los fragmentos según sea necesario. La implementación del driver de GridFS es una abstracción que gestiona las operaciones y la organización del almacenamiento de archivos.

Utiliza GridFS si el tamaño de tus archivos supera el límite de tamaño de documento BSON de 16 MB. GridFS también te ayuda a acceder a archivos sin cargar el archivo completo en la memoria. Para obtener más información sobre si GridFS es adecuado para su caso de uso, consulte GridFS en el manual del servidor.

Cómo funciona GridFS

GridFS organiza los archivos en un bucket, un grupo de colecciones de MongoDB que contienen los fragmentos de archivos e información que los describe. El bucket contiene las siguientes colecciones:

chunksque almacena los fragmentos del archivo binario
filesy almacena los metadatos del archivo

Cuando creas un nuevo bucket GridFS, el driver crea las colecciones anteriores. El nombre de bucket por defecto fs antepone los nombres de las colecciones, a menos que se especifique un nombre de bucket diferente. El driver crea el nuevo contenedor GridFS durante la primera operación de guardar.

El controlador también crea un índice en cada colección para garantizar la recuperación eficiente de los archivos y los metadatos relacionados. El controlador crea índices si aún no existen y cuando el depósito está vacío. Para obtener más información sobre los índices GridFS, consulta Índices GridFS en el manual del servidor.

Al almacenar archivos con GridFS, el driver divide los archivos en fragmentos más pequeños, cada uno representado por un documento aparte en la colección chunks. También crea un documento en la colección files que contiene un ID de archivo, el nombre del archivo y otros metadatos del archivo. El siguiente diagrama muestra cómo GridFS divide los archivos cargados:

Un diagrama que muestra cómo GridFS sube un archivo a un bucket

Al recuperar archivos, GridFS obtiene los metadatos de la colección files en el bucket especificado y luego utiliza esa información para reconstruir el archivo a partir de los documentos en la colección chunks. Puede leer el archivo en la memoria o enviarlo a un flujo de salida.

Operaciones GridFS

Las siguientes secciones describen cómo realizar operaciones GridFS:

Crear un bucket de GridFS
Cargar archivos
Recuperar información de archivos
Descargar archivos
Renombrar archivos
Borrar archivos
Borrar un bucket de GridFS

Crear un bucket de GridFS

Para almacenar o recuperar archivos de GridFS, crea un bucket de almacenamiento o consigue una referencia a un bucket de almacenamiento existente en una base de datos MongoDB. Para crear una instancia de GridFSBucket, llama al método GridFSBucket() en una instancia de Database, como se muestra en el siguiente código:

db := client.Database("myDB")
bucket := db.GridFSBucket()

Nota

Si ya existe un cubo de GridFS, el método GridFSBucket() devuelve una referencia al cubo en lugar de crear una nueva instancia.

Por defecto, el driver establece el nombre del bucket en fs. Para crear un bucket con un nombre personalizado, llama al método SetName() en una instancia BucketOptions, como se muestra en el siguiente código:

db := client.Database("myDB")
bucketOpts := options.GridFSBucket().SetName("myCustomBucket")
bucket := db.GridFSBucket(bucketOpts)

Cargar archivos

Puede cargar un archivo a un bucket de GridFS utilizando uno de los siguientes métodos:

UploadFromStream()que se lee desde un flujo de entrada
OpenUploadStream()que escribe en una secuencia de salida

Para cualquiera de los procesos de carga, puedes especificar información de configuración creando una instancia UploadOptions. Para ver una lista completa de opciones, consulta la documentación de la API de opciones de carga.

Carga con una secuencia de entrada

Para cargar un archivo con un flujo de entrada, utilice el método UploadFromStream() e incluya los siguientes parámetros:

Nombre de archivo
io.Reader instancia, incluyendo tu archivo abierto como parámetro
opts parámetro para modificar el comportamiento de UploadFromStream()

El siguiente ejemplo de código lee de un archivo llamado file.txt, crea un parámetro opts para establecer los metadatos del archivo y carga el contenido en un bucket de GridFS:

file, err := os.Open("home/documents/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)

New file uploaded with ID ...

Carga con un flujo de salida

Para cargar un archivo con un flujo de salida, utiliza el método OpenUploadStream() e incluye los siguientes parámetros:

Nombre de archivo
opts parámetro para modificar el comportamiento de OpenUploadStream()

El siguiente ejemplo de código abre un flujo de carga en un bucket de GridFS y configura la cantidad de bytes en cada fragmento en el parámetro de opciones. A continuación, llama al método Write() en el contenido de file.txt para guardar su contenido en la transmisión:

file, err := os.Open("home/documents/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)
//  Calls the Close() method to write file metadata
if err := uploadStream.Close(); err != nil {
	panic(err)
}

Recuperar información de archivos

Puede recuperar los metadatos del archivo almacenados en la colección files del bucket GridFS. Cada documento de la colección files contiene la siguiente información:

ID de archivo
Longitud del archivo
Tamaño máximo de fragmento
Fecha y hora de carga
Nombre de archivo
metadata documento que almacena cualquier otra información

Para recuperar los datos de un archivo, invoca el método Find() en una instancia de GridFSBucket. Puedes pasar un filtro de query como argumento a Find() para que solo coincida con ciertos documentos de archivos.

Nota

Debes pasar un filtro de query al método Find(). Para recuperar todos los documentos en la colección files, pasa un filtro de query vacío a Find().

El siguiente ejemplo recupera el nombre y el tamaño del archivo de documentos en los que el valor length es mayor 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)
}

Descargar archivos

Puedes descargar un archivo GridFS utilizando uno de los siguientes métodos:

DownloadToStream(), que descarga un archivo en un flujo de salida
OpenDownloadStream()lo que abre un flujo de entrada

Descargar un archivo a un flujo de salida

Puedes descargar un archivo en un bucket GridFS directamente a un flujo de salida utilizando el método DownloadToStream(). El método DownloadToStream() toma un ID de archivo y una instancia io.Writer como parámetros. El método descarga el archivo con el ID de archivo especificado y lo escribe en la instancia io.Writer.

El siguiente ejemplo descarga un archivo y guarda en un búfer de archivos:

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

Descargar un archivo en un flujo de entrada

Puedes descargar un archivo de un bucket GridFS a la memoria usando un flujo de entrada mediante el método OpenDownloadStream(). El método OpenDownloadStream() toma un ID de archivo como parámetro y retorna un flujo de entrada desde el cual se puede leer el archivo.

El siguiente ejemplo descarga un archivo en la memoria y lee su contenido:

id, err := bson.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)
}

Renombrar archivos

Puedes actualizar el nombre de un archivo de GridFS en tu bucket usando el método Rename(). Pasa un valor de ID de archivo y un nuevo valor de filename como argumentos a Rename().

El siguiente ejemplo renombra un archivo a "mongodbTutorial.zip":

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

Borrar archivos

Puedes remover un archivo de tu bucket de GridFS usando el método Delete(). Pase un valor de ID de archivo como argumento a Delete().

El siguiente ejemplo elimina un archivo:

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

Borrar un bucket de GridFS

Puede borrar un bucket GridFS utilizando el método Drop().

El siguiente ejemplo de código elimina un bucket de GridFS:

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

Recursos adicionales

Para obtener más información sobre GridFS y el almacenamiento, consulta las siguientes páginas en el manual del Servidor:

Documentación de la API

Para obtener más información sobre los métodos y tipos mencionados en esta guía, vea la siguiente documentación de la API:

Volver

Configurar las operaciones CRUD

Tutorial: Compila una aplicación web