What is GridFS in MongoDB: Explanation and Usage

GridFS is a specification in MongoDB for storing and retrieving large files that exceed the BSON document size limit of 16MB. It splits files into smaller chunks and stores them across multiple documents, allowing efficient storage and access of large files like images, videos, or backups.

How It Works

Imagine you want to store a very large photo album, but your storage boxes can only hold a few photos each. GridFS works like dividing that album into smaller boxes (chunks) and labeling each box so you can find and put the album back together easily.

In MongoDB, files larger than 16MB are split into chunks of a default size (usually 255KB). Each chunk is stored as a separate document in a chunks collection, while file metadata like filename and size is stored in a files collection. When you want to read the file, MongoDB fetches all chunks and reassembles them in order.

This method lets MongoDB handle files of any size efficiently without hitting document size limits.

Example

This example shows how to upload and download a file using GridFS with the MongoDB Node.js driver.

javascript

const { MongoClient, GridFSBucket } = require('mongodb');
const fs = require('fs');

async function run() {
  const client = new MongoClient('mongodb://localhost:27017');
  await client.connect();
  const db = client.db('myfilesdb');

  // Create GridFS bucket
  const bucket = new GridFSBucket(db);

  // Upload a file
  const uploadStream = bucket.openUploadStream('example.txt');
  fs.createReadStream('example.txt').pipe(uploadStream)
    .on('error', (error) => console.error('Upload error:', error))
    .on('finish', () => {
      console.log('File uploaded with id:', uploadStream.id);

      // Download the file
      const downloadStream = bucket.openDownloadStream(uploadStream.id);
      downloadStream.pipe(fs.createWriteStream('downloaded_example.txt'))
        .on('error', (error) => console.error('Download error:', error))
        .on('finish', () => {
          console.log('File downloaded successfully');
          client.close();
        });
    });
}

run().catch(console.error);

Output

File uploaded with id: <ObjectId>
File downloaded successfully

When to Use

Use GridFS when you need to store files larger than 16MB in MongoDB or want to keep files and their metadata together in the same database. It is ideal for applications that manage large media files like videos, audio, images, or backups.

For example, a photo-sharing app can store user images in GridFS to handle large uploads seamlessly. Similarly, a document management system can store PDFs or other large files without relying on external file storage.

Key Points

• GridFS splits large files into smaller chunks for storage.
• It stores file metadata separately for easy management.
• Files can be efficiently retrieved and reassembled.
• Useful for files exceeding MongoDB's 16MB document size limit.
• Supports streaming upload and download of files.

Key Takeaways

GridFS stores large files by splitting them into smaller chunks in MongoDB.

It helps manage files larger than 16MB, the BSON document size limit.

GridFS keeps file data and metadata in separate collections for easy access.

Use GridFS for large media files like videos, images, or backups.

MongoDB drivers provide built-in support for streaming files with GridFS.