GridFS

On this page

Prerequisites

Connect to a MongoDB Deployment
Create a GridFS Bucket
Upload to GridFS
Find Files Stored in GridFS
Download from GridFS
Rename Files
Delete Files

GridFS is a specification for storing and retrieving files that exceed the BSON document size limit of 16 MB. Instead of storing a large file in a single document, GridFS divides a file into parts, or chunks, and stores each of those chunks as separate documents.

When you query a GridFS store for a file, the driver reassembles the chunks as needed.

The code examples in this guide come from the GridFSTour.java file in the driver source code GitHub repository.

Prerequisites

You must include the following import statements in your program to run the code examples in this guide:

import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoDatabase;
import com.mongodb.client.gridfs.model.*;
import com.mongodb.reactivestreams.client.gridfs.*;
import org.bson.Document;
import org.bson.types.ObjectId;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.nio.Buffer;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import static com.mongodb.client.model.Filters.eq;
import static reactivestreams.helpers.PublisherHelpers.toPublisher;

Important

This guide uses custom Subscriber implementations, which are described in the Sample Custom Subscriber Implementations guide.

Connect to a MongoDB Deployment

First, connect to a MongoDB deployment and declare and define a MongoDatabase instance.

The following code connects to a standalone MongoDB deployment running on localhost on port 27017:

MongoClient mongoClient = MongoClients.create();

To learn more about connecting to MongoDB deployments, see the Connect to MongoDB tutorial.

Create a GridFS Bucket

GridFS stores files in two collections:

chunks: stores the file chunks
files: stores file metadata

The two collections are in a common bucket and the collection names are prefixed with the bucket name.

The driver provides the GridFSBuckets.create() method to create GridFSBucket instances:

MongoDatabase myDatabase = mongoClient.getDatabase("mydb");
// Create a gridFSBucket using the default bucket name "fs"
GridFSBucket gridFSBucket = GridFSBuckets.create(myDatabase);

You can pass a bucket name to the GridFSBuckets.create() method:

// Create a gridFSBucket with a custom bucket name "files"
GridFSBucket gridFSFilesBucket = GridFSBuckets.create(myDatabase, "files");

Note

GridFS automatically creates indexes on the files and chunks collections when you upload data to the GridFS bucket.

Upload to GridFS

The GridFSBucket.uploadFromPublisher() method reads the contents of Publisher<ByteBuffer> and saves it to the GridFSBucket instance.

You can use the GridFSUploadOptions type to configure the chunk size or include additional metadata.

The following example uploads the contents of a Publisher<ByteBuffer> into GridFSBucket:

// Get the input publisher
Publisher<ByteBuffer> publisherToUploadFrom = toPublisher(
    ByteBuffer
        .wrap("MongoDB Tutorial..".getBytes(StandardCharsets.UTF_8))
);
// Create some custom options
GridFSUploadOptions options = new GridFSUploadOptions()
    .chunkSizeBytes(1024)
    .metadata(new Document("type", "presentation"));
ObservableSubscriber<ObjectId> uploadSubscriber = new OperationSubscriber<>();
gridFSBucket.uploadFromPublisher("mongodb-tutorial", publisherToUploadFrom, options).subscribe(uploadSubscriber);
ObjectId fileId = uploadSubscriber.get().get(0);

Find Files Stored in GridFS

To find the files stored in the GridFSBucket, use the find() method.

The following example prints out the filename of each file stored:

ConsumerSubscriber<GridFSFile> filesSubscriber = new ConsumerSubscriber<>(gridFSFile ->
    System.out.println(" - " + gridFSFile.getFilename()));
gridFSBucket.find().subscribe(filesSubscriber);
filesSubscriber.await();

You can also provide a custom filter to limit the results returned. The following example prints out the filenames of all files in which the contentType value is an image/png value in the user-defined metadata document:

filesSubscriber = new ConsumerSubscriber<>(gridFSFile -> System.out.println("Found: " + gridFSFile.getFilename()));
gridFSBucket.find(eq("metadata.contentType", "image/png")).subscribe(filesSubscriber);
filesSubscriber.await();

Download from GridFS

The downloadToPublisher() method returns a Publisher<ByteBuffer> that reads the contents from MongoDB.

To download a file by its file _id, pass the _id to the method. The following example downloads a file by its file _id:

ObjectId fileId;
ObservableSubscriber<ByteBuffer> downloadSubscriber = new OperationSubscriber<>();
gridFSBucket.downloadToPublisher(fileId).subscribe(downloadSubscriber);

If you don't know the _id of the file but know the filename, then you can pass the filename to the downloadToPublisher() method. By default, it will download the latest version of the file. Use the GridFSDownloadOptions class to configure which version to download.

The following example downloads the original version of the file named mongodb-tutorial:

GridFSDownloadOptions downloadOptions = new GridFSDownloadOptions().revision(0);
downloadSubscriber = new OperationSubscriber<>();
gridFSBucket.downloadToPublisher("mongodb-tutorial", downloadOptions).subscribe(downloadSubscriber);

Rename Files

If you need to rename a file, then use the rename() method.

The following example renames a file to mongodbTutorial:

ObjectId fileId; //ObjectId of a file uploaded to GridFS
gridFSBucket.rename(fileId, "mongodbTutorial").subscribe(new ObservableSubscriber<Void>());

Note

The rename() method requires an ObjectId rather than a filename to ensure the correct file is renamed.

To rename multiple revisions of the same filename, first retrieve the full list of files. Then, for every file that should be renamed, run rename() with the corresponding _id.

Delete Files

To delete a file from the GridFSBucket, use the delete() method.

The following example deletes a file from the GridFSBucket:

ObjectId fileId; //ObjectId of a file uploaded to GridFS
gridFSBucket.delete(fileId).subscribe(new ObservableSubscriber<Void>());

Back

Transactions

Write Concern