.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::GridFSBucket 3pm"
.TH MongoDB::GridFSBucket 3pm "2020-08-15" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::GridFSBucket \- A file storage abstraction
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    $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() };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class models a GridFS file store in a MongoDB database and provides an
\&\s-1API\s0 for interacting with it.
.PP
Generally, you never construct one of these directly with \f(CW\*(C`new\*(C'\fR.  Instead,
you call \f(CW\*(C`gfs\*(C'\fR (short for \f(CW\*(C`get_gridfsbucket\*(C'\fR) on a MongoDB::Database
object.
.SH "USAGE"
.IX Header "USAGE"
.SS "Data model"
.IX Subsection "Data model"
A GridFS file is represented in MongoDB as a \*(L"file document\*(R" with
information like the file's name, length, and any user-supplied
metadata.  The actual contents are stored as a number of \*(L"chunks\*(R" of binary
data.  (Think of the file document as a directory entry and the chunks like
blocks on disk.)
.PP
Valid file documents typically include the following fields:
.IP "\(bu" 4
_id – a unique \s-1ID\s0 for this document, typically a \s-1BSON\s0 ObjectId.
.IP "\(bu" 4
length – the length of this stored file, in bytes
.IP "\(bu" 4
chunkSize – the size, in bytes, of each full data chunk of this file. This value is configurable per file.
.IP "\(bu" 4
uploadDate – the date and time this file was added to GridFS, stored as a \s-1BSON\s0 datetime value.
.IP "\(bu" 4
filename – the name of this stored file; the combination of filename and uploadDate (millisecond resolution) must be unique
.IP "\(bu" 4
metadata – any additional application data the user wishes to store (optional)
.IP "\(bu" 4
md5 – \s-1DEPRECATED\s0 a hash of the contents of the stored file (store this in \f(CW\*(C`metadata\*(C'\fR if you need it) (optional)
.IP "\(bu" 4
contentType – \s-1DEPRECATED\s0 (store this in \f(CW\*(C`metadata\*(C'\fR if you need it) (optional)
.IP "\(bu" 4
aliases – \s-1DEPRECATED\s0 (store this in \f(CW\*(C`metadata\*(C'\fR if you need it) (optional)
.PP
The \f(CW\*(C`find\*(C'\fR method searches file documents using these fields.  Given the
\&\f(CW\*(C`_id\*(C'\fR from a document, a file can be downloaded using the download
methods.
.SS "\s-1API\s0 Overview"
.IX Subsection "API Overview"
In addition to general methods like \f(CW\*(C`find\*(C'\fR, \f(CW\*(C`delete\*(C'\fR and \f(CW\*(C`drop\*(C'\fR, there
are two ways to go about uploading and downloading:
.IP "\(bu" 4
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.
.IP "\(bu" 4
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 \s-1EOF.\s0
.SS "Error handling"
.IX Subsection "Error handling"
Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs.  The error types are documented in MongoDB::Error.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "database"
.IX Subsection "database"
The MongoDB::Database containing the GridFS bucket collections.
.SS "bucket_name"
.IX Subsection "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 \*(L"fs.chunks\*(R").
.SS "chunk_size_bytes"
.IX Subsection "chunk_size_bytes"
The number of bytes per chunk.  Defaults to 261120 (255kb).
.SS "write_concern"
.IX Subsection "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.
.SS "read_concern"
.IX Subsection "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.
.PP
By default it will be inherited from a MongoDB::Database object.
.SS "read_preference"
.IX Subsection "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.
.PP
\&\fBNote:\fR Because many GridFS operations require multiple independent reads from
separate collections, use with secondaries is \fBstrongly discouraged\fR because
reads could go to different secondaries, resulting in inconsistent data
if all file and chunk documents have not replicated to all secondaries.
.SS "bson_codec"
.IX Subsection "bson_codec"
An object that provides the \f(CW\*(C`encode_one\*(C'\fR and \f(CW\*(C`decode_one\*(C'\fR methods, such
as from \s-1BSON\s0.  It may be initialized with a hash reference that
will be coerced into a new \s-1BSON\s0 object.  By default it will be
inherited from a MongoDB::Database object.
.SS "max_time_ms"
.IX Subsection "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.
.PP
\&\fBNote\fR: this will only be used for server versions 2.6 or greater, as that
was when the \f(CW$maxTimeMS\fR meta-operator was introduced.
.SS "disable_md5"
.IX Subsection "disable_md5"
When true, files will not include the deprecated \f(CW\*(C`md5\*(C'\fR field in the
file document.  Defaults to false.
.SH "METHODS"
.IX Header "METHODS"
.SS "find"
.IX Subsection "find"
.Vb 2
\&    $result = $bucket\->find($filter);
\&    $result = $bucket\->find($filter, $options);
\&
\&    $file_doc = $result\->next;
.Ve
.PP
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 \*(L"find\*(R" in MongoDB::Collection.
.SS "find_one"
.IX Subsection "find_one"
.Vb 2
\&    $file_doc = $bucket\->find_one($filter, $projection);
\&    $file_doc = $bucket\->find_one($filter, $projection, $options);
.Ve
.PP
Executes a query on the file documents collection with a
filter expression and
returns the first document found, or \f(CW\*(C`undef\*(C'\fR if no document is found.
.PP
See \*(L"find_one\*(R" in MongoDB::Collection for details about the
\&\f(CW$projection\fR and optional \f(CW$options\fR fields.
.SS "find_id"
.IX Subsection "find_id"
.Vb 3
\&    $file_doc = $bucket\->find_id( $id );
\&    $file_doc = $bucket\->find_id( $id, $projection );
\&    $file_doc = $bucket\->find_id( $id, $projection, $options );
.Ve
.PP
Executes a query with a filter expression of
\&\f(CW\*(C`{ _id => $id }\*(C'\fR and returns a single document or \f(CW\*(C`undef\*(C'\fR if no document
is found.
.PP
See \*(L"find_one\*(R" in MongoDB::Collection for details about the
\&\f(CW$projection\fR and optional \f(CW$options\fR fields.
.SS "open_download_stream"
.IX Subsection "open_download_stream"
.Vb 2
\&    $stream = $bucket\->open_download_stream($id);
\&    $line = $stream\->readline;
.Ve
.PP
Returns a new MongoDB::GridFSBucket::DownloadStream that can be used to
download the file with the file document \f(CW\*(C`_id\*(C'\fR matching \f(CW$id\fR.  This
throws a MongoDB::GridFSError if no such file exists.
.SS "open_upload_stream"
.IX Subsection "open_upload_stream"
.Vb 2
\&    $stream = $bucket\->open_upload_stream($filename);
\&    $stream = $bucket\->open_upload_stream($filename, $options);
\&
\&    $stream\->print(\*(Aqdata\*(Aq);
\&    $stream\->close;
\&    $file_id = $stream\->id
.Ve
.PP
Returns a new MongoDB::GridFSBucket::UploadStream that can be used
to upload a new file to a GridFS bucket.
.PP
This method requires a filename to store in the \f(CW\*(C`filename\*(C'\fR field of the
file document.  \fBNote\fR: the filename is an arbitrary string; the method
does not read from this filename locally.
.PP
You can provide an optional hash reference of options that are passed to the
MongoDB::GridFSBucket::UploadStream constructor:
.IP "\(bu" 4
\&\f(CW\*(C`chunk_size_bytes\*(C'\fR – the number of bytes per chunk.  Defaults to the \f(CW\*(C`chunk_size_bytes\*(C'\fR of the bucket object.
.IP "\(bu" 4
\&\f(CW\*(C`metadata\*(C'\fR – a hash reference for storing arbitrary metadata about the file.
.SS "open_upload_stream_with_id"
.IX Subsection "open_upload_stream_with_id"
.Vb 2
\&    $stream = $bucket\->open_upload_stream_with_id($id, $filename);
\&    $stream = $bucket\->open_upload_stream_with_id($id, $filename, $options);
\&
\&    $stream\->print(\*(Aqdata\*(Aq);
\&    $stream\->close;
.Ve
.PP
Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
upload a new file to a GridFS bucket.
.PP
This method uses \f(CW$id\fR as the _id of the file being created, which must be
unique.
.PP
This method requires a filename to store in the \f(CW\*(C`filename\*(C'\fR field of the
file document.  \fBNote\fR: the filename is an arbitrary string; the method
does not read from this filename locally.
.PP
You can provide an optional hash reference of options, just like
\&\*(L"open_upload_stream\*(R".
.SS "download_to_stream"
.IX Subsection "download_to_stream"
.Vb 1
\&    $bucket\->download_to_stream($id, $out_fh);
.Ve
.PP
Downloads the file matching \f(CW$id\fR and writes it to the file handle \f(CW$out_fh\fR.
This throws a MongoDB::GridFSError if no such file exists.
.SS "upload_from_stream"
.IX Subsection "upload_from_stream"
.Vb 2
\&    $file_id = $bucket\->upload_from_stream($filename, $in_fh);
\&    $file_id = $bucket\->upload_from_stream($filename, $in_fh, $options);
.Ve
.PP
Reads from a filehandle and uploads its contents to GridFS.  It returns the
\&\f(CW\*(C`_id\*(C'\fR field stored in the file document.
.PP
This method requires a filename to store in the \f(CW\*(C`filename\*(C'\fR field of the
file document.  \fBNote\fR: the filename is an arbitrary string; the method
does not read from this filename locally.
.PP
You can provide an optional hash reference of options, just like
\&\*(L"open_upload_stream\*(R".
.SS "upload_from_stream_with_id"
.IX Subsection "upload_from_stream_with_id"
.Vb 2
\&    $bucket\->upload_from_stream_with_id($id, $filename, $in_fh);
\&    $bucket\->upload_from_stream_with_id($id, $filename, $in_fh, $options);
.Ve
.PP
Reads from a filehandle and uploads its contents to GridFS.
.PP
This method uses \f(CW$id\fR as the _id of the file being created, which must be
unique.
.PP
This method requires a filename to store in the \f(CW\*(C`filename\*(C'\fR field of the
file document.  \fBNote\fR: the filename is an arbitrary string; the method
does not read from this filename locally.
.PP
You can provide an optional hash reference of options, just like
\&\*(L"open_upload_stream\*(R".
.PP
Unlike \*(L"open_upload_stream\*(R", this method returns nothing.
.SS "delete"
.IX Subsection "delete"
.Vb 1
\&    $bucket\->delete($id);
.Ve
.PP
Deletes the file matching \f(CW$id\fR from the bucket.
This throws a MongoDB::GridFSError if no such file exists.
.SS "drop"
.IX Subsection "drop"
.Vb 1
\&    $bucket\->drop;
.Ve
.PP
Drops the underlying files documents and chunks collections for this bucket.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Core documentation on GridFS: <http://dochub.mongodb.org/core/gridfs>.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve