{ "mode": "perldoc", "parameter": "MongoDB::GridFSBucket", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/MongoDB%3A%3AGridFSBucket/json", "generated": "2026-06-09T11:49:30Z", "synopsis": "$bucket = $database->gfs;\n# upload a file\n$stream = $bucket->openuploadstream(\"foo.txt\");\n$stream->print( $data );\n$stream->close;\n# find and download a file\n$result = $bucket->find({filename => \"foo.txt\"});\n$fileid = $result->next->{id};\n$stream = $bucket->opendownloadstream($fileid)\n$data = do { local $/; $stream->readline() };", "sections": { "NAME": { "content": "MongoDB::GridFSBucket - A file storage abstraction\n", "subsections": [] }, "VERSION": { "content": "version v2.2.2\n", "subsections": [] }, "SYNOPSIS": { "content": "$bucket = $database->gfs;\n\n# upload a file\n$stream = $bucket->openuploadstream(\"foo.txt\");\n$stream->print( $data );\n$stream->close;\n\n# find and download a file\n$result = $bucket->find({filename => \"foo.txt\"});\n$fileid = $result->next->{id};\n$stream = $bucket->opendownloadstream($fileid)\n$data = do { local $/; $stream->readline() };\n", "subsections": [] }, "DESCRIPTION": { "content": "This class models a GridFS file store in a MongoDB database and provides an API for interacting\nwith it.\n\nGenerally, you never construct one of these directly with \"new\". Instead, you call \"gfs\" (short\nfor \"getgridfsbucket\") on a MongoDB::Database object.\n", "subsections": [] }, "USAGE": { "content": "", "subsections": [ { "name": "Data model", "content": "A GridFS file is represented in MongoDB as a \"file document\" with information like the file's\nname, length, and any user-supplied metadata. The actual contents are stored as a number of\n\"chunks\" of binary data. (Think of the file document as a directory entry and the chunks like\nblocks on disk.)\n\nValid file documents typically include the following fields:\n\n* id – a unique ID for this document, typically a BSON ObjectId.\n\n* length – the length of this stored file, in bytes\n\n* chunkSize – the size, in bytes, of each full data chunk of this file. This value is\nconfigurable per file.\n\n* uploadDate – the date and time this file was added to GridFS, stored as a BSON datetime\nvalue.\n\n* filename – the name of this stored file; the combination of filename and uploadDate\n(millisecond resolution) must be unique\n\n* metadata – any additional application data the user wishes to store (optional)\n\n* md5 – DEPRECATED a hash of the contents of the stored file (store this in \"metadata\" if you\nneed it) (optional)\n\n* contentType – DEPRECATED (store this in \"metadata\" if you need it) (optional)\n\n* aliases – DEPRECATED (store this in \"metadata\" if you need it) (optional)\n\nThe \"find\" method searches file documents using these fields. Given the \"id\" from a document, a\nfile can be downloaded using the download methods.\n\nAPI Overview\nIn addition to general methods like \"find\", \"delete\" and \"drop\", there are two ways to go about\nuploading and downloading:\n\n* filehandle-like: you get an object that you can read/write from similar to a filehandle. You\ncan even get a tied filehandle that you can hand off to other code that requires an actual\nPerl handle.\n\n* streaming: you provide a file handle to read from (upload) or print to (download) and data\nis streamed to (upload) or from (download) GridFS until EOF.\n" }, { "name": "Error handling", "content": "Unless otherwise explicitly documented, all methods throw exceptions if an error occurs. The\nerror types are documented in MongoDB::Error.\n" } ] }, "ATTRIBUTES": { "content": "database\nThe MongoDB::Database containing the GridFS bucket collections.\n\nbucketname\nThe name of the GridFS bucket. Defaults to 'fs'. The underlying collections that are used to\nimplement a GridFS bucket get this string as a prefix (e.g \"fs.chunks\").\n\nchunksizebytes\nThe number of bytes per chunk. Defaults to 261120 (255kb).\n\nwriteconcern\nA MongoDB::WriteConcern object. It may be initialized with a hash reference that will be coerced\ninto a new MongoDB::WriteConcern object. By default it will be inherited from a\nMongoDB::Database object.\n\nreadconcern\nA MongoDB::ReadConcern object. May be initialized with a hash reference or a string that will be\ncoerced into the level of read concern.\n\nBy default it will be inherited from a MongoDB::Database object.\n\nreadpreference\nA MongoDB::ReadPreference object. It may be initialized with a string corresponding to one of\nthe valid read preference modes or a hash reference that will be coerced into a new\nMongoDB::ReadPreference object. By default it will be inherited from a MongoDB::Database object.\n\nNote: Because many GridFS operations require multiple independent reads from separate\ncollections, use with secondaries is strongly discouraged because reads could go to different\nsecondaries, resulting in inconsistent data if all file and chunk documents have not replicated\nto all secondaries.\n\nbsoncodec\nAn object that provides the \"encodeone\" and \"decodeone\" methods, such as from BSON. It may be\ninitialized with a hash reference that will be coerced into a new BSON object. By default it\nwill be inherited from a MongoDB::Database object.\n\nmaxtimems\nSpecifies the maximum amount of time in milliseconds that the server should use for working on a\nquery. By default it will be inherited from a MongoDB::Database object.\n\nNote: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS\nmeta-operator was introduced.\n\ndisablemd5\nWhen true, files will not include the deprecated \"md5\" field in the file document. Defaults to\nfalse.\n", "subsections": [] }, "METHODS": { "content": "find\n$result = $bucket->find($filter);\n$result = $bucket->find($filter, $options);\n\n$filedoc = $result->next;\n\nExecutes a query on the file documents collection with a filter expression and returns a\nMongoDB::QueryResult object. It takes an optional hashref of options identical to \"find\" in\nMongoDB::Collection.\n\nfindone\n$filedoc = $bucket->findone($filter, $projection);\n$filedoc = $bucket->findone($filter, $projection, $options);\n\nExecutes a query on the file documents collection with a filter expression and returns the first\ndocument found, or \"undef\" if no document is found.\n\nSee \"findone\" in MongoDB::Collection for details about the $projection and optional $options\nfields.\n\nfindid\n$filedoc = $bucket->findid( $id );\n$filedoc = $bucket->findid( $id, $projection );\n$filedoc = $bucket->findid( $id, $projection, $options );\n\nExecutes a query with a filter expression of \"{ id => $id }\" and returns a single document or\n\"undef\" if no document is found.\n\nSee \"findone\" in MongoDB::Collection for details about the $projection and optional $options\nfields.\n\nopendownloadstream\n$stream = $bucket->opendownloadstream($id);\n$line = $stream->readline;\n\nReturns a new MongoDB::GridFSBucket::DownloadStream that can be used to download the file with\nthe file document \"id\" matching $id. This throws a MongoDB::GridFSError if no such file exists.\n\nopenuploadstream\n$stream = $bucket->openuploadstream($filename);\n$stream = $bucket->openuploadstream($filename, $options);\n\n$stream->print('data');\n$stream->close;\n$fileid = $stream->id\n\nReturns a new MongoDB::GridFSBucket::UploadStream that can be used to upload a new file to a\nGridFS bucket.\n\nThis method requires a filename to store in the \"filename\" field of the file document. Note: the\nfilename is an arbitrary string; the method does not read from this filename locally.\n\nYou can provide an optional hash reference of options that are passed to the\nMongoDB::GridFSBucket::UploadStream constructor:\n\n* \"chunksizebytes\" – the number of bytes per chunk. Defaults to the \"chunksizebytes\" of\nthe bucket object.\n\n* \"metadata\" – a hash reference for storing arbitrary metadata about the file.\n\nopenuploadstreamwithid\n$stream = $bucket->openuploadstreamwithid($id, $filename);\n$stream = $bucket->openuploadstreamwithid($id, $filename, $options);\n\n$stream->print('data');\n$stream->close;\n\nReturns a new MongoDB::GridFSBucket::UploadStream that can be used to upload a new file to a\nGridFS bucket.\n\nThis method uses $id as the id of the file being created, which must be unique.\n\nThis method requires a filename to store in the \"filename\" field of the file document. Note: the\nfilename is an arbitrary string; the method does not read from this filename locally.\n\nYou can provide an optional hash reference of options, just like \"openuploadstream\".\n\ndownloadtostream\n$bucket->downloadtostream($id, $outfh);\n\nDownloads the file matching $id and writes it to the file handle $outfh. This throws a\nMongoDB::GridFSError if no such file exists.\n\nuploadfromstream\n$fileid = $bucket->uploadfromstream($filename, $infh);\n$fileid = $bucket->uploadfromstream($filename, $infh, $options);\n\nReads from a filehandle and uploads its contents to GridFS. It returns the \"id\" field stored in\nthe file document.\n\nThis method requires a filename to store in the \"filename\" field of the file document. Note: the\nfilename is an arbitrary string; the method does not read from this filename locally.\n\nYou can provide an optional hash reference of options, just like \"openuploadstream\".\n\nuploadfromstreamwithid\n$bucket->uploadfromstreamwithid($id, $filename, $infh);\n$bucket->uploadfromstreamwithid($id, $filename, $infh, $options);\n\nReads from a filehandle and uploads its contents to GridFS.\n\nThis method uses $id as the id of the file being created, which must be unique.\n\nThis method requires a filename to store in the \"filename\" field of the file document. Note: the\nfilename is an arbitrary string; the method does not read from this filename locally.\n\nYou can provide an optional hash reference of options, just like \"openuploadstream\".\n\nUnlike \"openuploadstream\", this method returns nothing.\n\ndelete\n$bucket->delete($id);\n\nDeletes the file matching $id from the bucket. This throws a MongoDB::GridFSError if no such\nfile exists.\n\ndrop\n$bucket->drop;\n\nDrops the underlying files documents and chunks collections for this bucket.\n", "subsections": [] }, "SEE ALSO": { "content": "Core documentation on GridFS: .\n", "subsections": [] }, "AUTHORS": { "content": "* David Golden \n\n* Rassi \n\n* Mike Friedman \n\n* Kristina Chodorow \n\n* Florian Ragwitz \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n", "subsections": [] } }, "summary": "MongoDB::GridFSBucket - A file storage abstraction", "flags": [], "examples": [], "see_also": [] }