--- name: "MongoDB::GridFSBucket" section: "3pm" platform: "linux" package: "libmongodb-perl" version: "2.2.2-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/MongoDB::GridFSBucket" --- # MongoDB::GridFSBucket(3pm) A file storage abstraction ## NAME MongoDB::GridFSBucket - A file storage abstraction ## VERSION version v2.2.2 ## SYNOPSIS ``` $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() }; ``` ## DESCRIPTION This class models a GridFS file store in a MongoDB database and provides an API for interacting with it. Generally, you never construct one of these directly with `"new"`. Instead, you call `"gfs"` (short for `"get_gridfsbucket"`) on a MongoDB::Database object. ## USAGE ### Data model A GridFS file is represented in MongoDB as a "file document" with information like the file's name, length, and any user-supplied metadata. The actual contents are stored as a number of "chunks" of binary data. (Think of the file document as a directory entry and the chunks like blocks on disk.) 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 In addition to general methods like `"find"`, `"delete"` and `"drop"`, there are two ways to go about uploading and downloading: - • 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 Unless otherwise explicitly documented, all methods throw exceptions if an error occurs. The error types are documented in MongoDB::Error. ## ATTRIBUTES ### database The MongoDB::Database containing the GridFS bucket collections. ### bucket\_name The name of the GridFS bucket. Defaults to 'fs'. The underlying collections that are 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 will be 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 will be 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 will be inherited from a MongoDB::Database object. **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 An object that provides the `"encode_one"` and `"decode_one"` methods, such as from BSON. It may be initialized with a hash reference that will be coerced into a new BSON object. By default it will be inherited from a MongoDB::Database object. ### max\_time\_ms Specifies the maximum amount of time in milliseconds that the server should use for working on a query. By default it will be inherited from a MongoDB::Database object. **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 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; ``` 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. ## SEE ALSO Core documentation on GridFS: \. ## AUTHORS - • David Golden \ - • Rassi \ - • Mike Friedman \ - • Kristina Chodorow \ - • Florian Ragwitz \ ## 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 ```