MongoD...SBucket(3pm)

🌸 NAME 🌸

okay so you found the MongoD...SBucket(3pm) page in the User Contributed Perl Documentation, and it's literally all about MongoDB::GridFSBucket — a file storage abstraction. yes bestie, you can store whole files in MongoDB. we're doing that. 🎀

✨ VERSION ✨

version v2.2.2 — fresh-ish, slay.

🦋 SYNOPSIS 🦋

here's the vibe, in code:

$bucket = $database->gfs;

# upload a file
$stream  = $bucket->open_upload_stream("foo.txt");
$stream->print( $data );
$stream->close;

# find and download a file
$result  = $bucket->find({filename => "foo.txt"});
$file_id = $result->next->{_id};
$stream  = $bucket->open_download_stream($file_id)
$data    = do { local $/; $stream->readline() };

like. upload, find, download. that's the whole arc. 👑

💅 DESCRIPTION 💅

This class is the model of a GridFS file store living inside a MongoDB database, and it hands you the whole API for talking to it. No cap.

And listen: you basically never build one of these yourself with new. That's not the move. Instead you call gfs (short for get_gridfsbucket, iykyk) on a MongoDB::Database object and it just... gives you one. 🫶

🌈 USAGE 🌈

🧚 Data model 🧚

A GridFS file shows up in MongoDB as a "file document" holding the deets — the file's name, its length, any user-supplied metadata, all of it. The actual contents? Those get stored as a bunch of "chunks" of binary data. Think of the file document as the directory entry and the chunks as the blocks on disk. it's giving filesystem, respectfully. 💀

Valid file documents typically include these 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. And once you've got the _id out of a document, you can download that file with the download methods. easy. ✨

🍓 API Overview 🍓

On top of the general methods like find, delete and drop, there are two whole ways to upload and download:

• filehandle-like: you get an object you can read/write from, just like 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 hand over a file handle to read from (upload) or print to (download), and data streams to (upload) or from (download) GridFS until EOF.

🔥 Error handling 🔥

Unless it's explicitly documented otherwise, every method throws exceptions if an error happens. The error types live in MongoDB::Error. so, y'know, wrap it. 🙈

💜 ATTRIBUTES 💜

database

The MongoDB::Database containing the GridFS bucket collections.

bucket_name

The name of the GridFS bucket. Defaults to 'fs'. The underlying collections used to implement a GridFS bucket get this string as a prefix (e.g "fs.chunks").

chunk_size_bytes

The number of bytes per chunk. Defaults to 261120 (255kb).

write_concern

A MongoDB::WriteConcern object. It may be initialized with a hash reference that will be coerced into a new MongoDB::WriteConcern object. By default it gets inherited from a MongoDB::Database object.

read_concern

A MongoDB::ReadConcern object. May be initialized with a hash reference or a string that will be coerced into the level of read concern.

By default it gets inherited from a MongoDB::Database object.

read_preference

A MongoDB::ReadPreference object. It may be initialized with a string corresponding to one of the valid read preference modes, or a hash reference that will be coerced into a new MongoDB::ReadPreference object. By default it gets inherited from a MongoDB::Database object.

Note: because so many GridFS operations need multiple independent reads from separate collections, using this with secondaries is strongly discouraged — the reads could go to different secondaries and you'd get inconsistent data if all the file and chunk documents haven't replicated to every secondary. that's the drama you do NOT want. 😭

bson_codec

An object that provides the encode_one and decode_one methods, like the ones from BSON. It may be initialized with a hash reference that will be coerced into a new BSON object. By default it gets inherited from a MongoDB::Database object.

max_time_ms

Specifies the maximum amount of time in milliseconds the server should spend working on a query. By default it gets inherited from a MongoDB::Database object.

Note: this only gets used on server versions 2.6 or greater, because that's when the $maxTimeMS meta-operator showed up. periodt.

disable_md5

When true, files will not include the deprecated "md5" field in the file document. Defaults to false.

---

⭐ METHODS ⭐

find

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

$file_doc = $result->next;

Runs a query on the file documents collection with a filter expression and hands back a MongoDB::QueryResult object. It takes an optional hashref of options, exactly like find in MongoDB::Collection.

find_one

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

Runs a query on the file documents collection with a filter expression and returns the first document it finds, or undef if there's nothing there. 💀

See find_one in MongoDB::Collection for the details on 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 );

Runs 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 the details on the $projection and optional $options fields.

open_download_stream

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

Returns a brand new MongoDB::GridFSBucket::DownloadStream that you can use to download the file whose file document _id matches $id. If no such file exists, it throws a MongoDB::GridFSError. no file, no service, bestie. 😤

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 you can use to upload a new file into a GridFS bucket. ✨

This method needs 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. it's just a label, not a path. 🎀

You can pass an optional hash reference of options that get handed 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 you can use to upload a new file into a GridFS bucket.

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

This method needs 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 pass 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. If no such file exists, it throws a MongoDB::GridFSError.

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 all its contents to GridFS. It returns the "_id" field stored in the file document.

This method needs 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 pass 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 needs 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 pass an optional hash reference of options, just like open_upload_stream.

And unlike open_upload_stream, this method returns nothing. 😭

delete

$bucket->delete($id);

Deletes the file matching $id from the bucket. If no such file exists, it throws a MongoDB::GridFSError.

drop

$bucket->drop;

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

---

🌟 SEE ALSO 🌟

Core documentation on GridFS: <http://dochub.mongodb.org/core/gridfs>.

👑 AUTHORS 👑

• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>

💖 COPYRIGHT AND LICENSE 💖

This software is Copyright (c) 2020 by MongoDB, Inc.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

okay bestie that's the whole page, we ate and left no crumbs. 🫶 This was MongoD...SBucket(3pm) from the User Contributed Perl Documentation, built against perl v5.40.1 and dated 2025-04-03. go store some files, you main character. 🌈✨