Provided by: libmongodb-perl_2.2.2-2_all bug

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: <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