Data model

Valid file documents typically include the following fields:

• _id – a unique ID for this document, typically a BSON ObjectId.
• length – the length of this stored file, in bytes
• chunkSize – the size, in bytes, of each full data chunk of this file. This value is configurable per file.
• uploadDate – the date and time this file was added to GridFS, stored as a BSON datetime value.
• filename – the name of this stored file; the combination of filename and uploadDate (millisecond resolution) must be unique
• metadata – any additional application data the user wishes to store (optional)
• md5 – DEPRECATED a hash of the contents of the stored file (store this in "metadata" if you need it) (optional)
• contentType – DEPRECATED (store this in "metadata" if you need it) (optional)
• aliases – DEPRECATED (store this in "metadata" if you need it) (optional)

The "find" method searches file documents using these fields. Given the "_id" from a document, a file can be downloaded using the download methods.

API Overview

• filehandle-like: you get an object that you can read/write from similar to a filehandle. You can even get a tied filehandle that you can hand off to other code that requires an actual Perl handle.
• streaming: you provide a file handle to read from (upload) or print to (download) and data is streamed to (upload) or from (download) GridFS until EOF.

Error handling

database

bucket_name

chunk_size_bytes

write_concern

read_concern

By default it will be inherited from a MongoDB::Database object.

read_preference

Note: Because many GridFS operations require multiple independent reads from separate collections, use with secondaries is strongly discouraged because reads could go to different secondaries, resulting in inconsistent data if all file and chunk documents have not replicated to all secondaries.

bson_codec

max_time_ms

Note: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS meta-operator was introduced.

disable_md5

find

    $result = $bucket->find($filter);
    $result = $bucket->find($filter, $options);

    $file_doc = $result->next;

Executes a query on the file documents collection with a filter expression and returns a MongoDB::QueryResult object. It takes an optional hashref of options identical to "find" in MongoDB::Collection.

find_one

    $file_doc = $bucket->find_one($filter, $projection);
    $file_doc = $bucket->find_one($filter, $projection, $options);

Executes a query on the file documents collection with a filter expression and returns the first document found, or "undef" if no document is found.

See "find_one" in MongoDB::Collection for details about the $projection and optional $options fields.

find_id

    $file_doc = $bucket->find_id( $id );
    $file_doc = $bucket->find_id( $id, $projection );
    $file_doc = $bucket->find_id( $id, $projection, $options );

Executes a query with a filter expression of "{ _id => $id }" and returns a single document or "undef" if no document is found.

See "find_one" in MongoDB::Collection for details about the $projection and optional $options fields.

open_download_stream

    $stream = $bucket->open_download_stream($id);
    $line = $stream->readline;

Returns a new MongoDB::GridFSBucket::DownloadStream that can be used to download the file with the file document "_id" matching $id. This throws a MongoDB::GridFSError if no such file exists.

open_upload_stream

    $stream = $bucket->open_upload_stream($filename);
    $stream = $bucket->open_upload_stream($filename, $options);

    $stream->print('data');
    $stream->close;
    $file_id = $stream->id

Returns a new MongoDB::GridFSBucket::UploadStream that can be used to upload a new file to a GridFS bucket.

This method requires a filename to store in the "filename" field of the file document. Note: the filename is an arbitrary string; the method does not read from this filename locally.

You can provide an optional hash reference of options that are passed to the MongoDB::GridFSBucket::UploadStream constructor:

• "chunk_size_bytes" – the number of bytes per chunk. Defaults to the "chunk_size_bytes" of the bucket object.
• "metadata" – a hash reference for storing arbitrary metadata about the file.

open_upload_stream_with_id

    $stream = $bucket->open_upload_stream_with_id($id, $filename);
    $stream = $bucket->open_upload_stream_with_id($id, $filename, $options);

    $stream->print('data');
    $stream->close;

Returns a new MongoDB::GridFSBucket::UploadStream that can be used to upload a new file to a GridFS bucket.

This method uses $id as the _id of the file being created, which must be unique.

This method requires a filename to store in the "filename" field of the file document. Note: the filename is an arbitrary string; the method does not read from this filename locally.

You can provide an optional hash reference of options, just like "open_upload_stream".

download_to_stream

    $bucket->download_to_stream($id, $out_fh);

Downloads the file matching $id and writes it to the file handle $out_fh. This throws a MongoDB::GridFSError if no such file exists.

upload_from_stream

    $file_id = $bucket->upload_from_stream($filename, $in_fh);
    $file_id = $bucket->upload_from_stream($filename, $in_fh, $options);

Reads from a filehandle and uploads its contents to GridFS. It returns the "_id" field stored in the file document.

This method requires a filename to store in the "filename" field of the file document. Note: the filename is an arbitrary string; the method does not read from this filename locally.

You can provide an optional hash reference of options, just like "open_upload_stream".

upload_from_stream_with_id

    $bucket->upload_from_stream_with_id($id, $filename, $in_fh);
    $bucket->upload_from_stream_with_id($id, $filename, $in_fh, $options);

Reads from a filehandle and uploads its contents to GridFS.

This method uses $id as the _id of the file being created, which must be unique.

This method requires a filename to store in the "filename" field of the file document. Note: the filename is an arbitrary string; the method does not read from this filename locally.

You can provide an optional hash reference of options, just like "open_upload_stream".

Unlike "open_upload_stream", this method returns nothing.

delete

    $bucket->delete($id);

Deletes the file matching $id from the bucket. This throws a MongoDB::GridFSError if no such file exists.

drop

    $bucket->drop;

Drops the underlying files documents and chunks collections for this bucket.