.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "MongoDB::GridFS 3pm"
.TH MongoDB::GridFS 3pm "2018-01-18" "perl v5.26.1" "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::GridFS \- A file storage abstraction (DEPRECATED)
.SH "VERSION"
.IX Header "VERSION"
version v1.8.1
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    my $grid = $database\->get_gridfs;
\&    my $fh = IO::File\->new("myfile", "r");
\&    $grid\->insert($fh, {"filename" => "mydbfile"});
.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`get_gridfs\*(C'\fR on a MongoDB::Database object.
.SH "USAGE"
.IX Header "USAGE"
.SS "\s-1API\s0"
.IX Subsection "API"
There are two interfaces for GridFS: a file\-system/collection\-like interface
(insert, remove, drop, find_one) and a more general interface
(get, put, delete).  Their functionality is the almost identical (get, put and
delete are always safe ops, insert, remove, and find_one are optionally safe),
using one over the other is a matter of preference.
.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.
.PP
To catch and handle errors, the Try::Tiny and Safe::Isa modules
are recommended:
.PP
.Vb 2
\&    use Try::Tiny;
\&    use Safe::Isa; # provides $_isa
\&
\&    try {
\&        $grid\->get( $id )
\&    }
\&    catch {
\&        if ( $_\->$_isa("MongoDB::TimeoutError" ) {
\&            ...
\&        }
\&        else {
\&            ...
\&        }
\&    };
.Ve
.PP
To retry failures automatically, consider using Try::Tiny::Retry.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "chunk_size"
.IX Subsection "chunk_size"
The number of bytes per chunk.  Defaults to 261120 (255kb).
.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.
.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 "max_time_ms"
.IX Subsection "max_time_ms"
Specifies the default maximum amount of time in milliseconds that the
server should use for working on a query.
.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 "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 MongoDB::BSON.  It may be initialized with a hash reference that
will be coerced into a new MongoDB::BSON object.  By default it will be
inherited from a MongoDB::Database object.
.SS "prefix"
.IX Subsection "prefix"
The prefix used for the collections.  Defaults to \*(L"fs\*(R".
.SH "METHODS"
.IX Header "METHODS"
.SS "get"
.IX Subsection "get"
.Vb 1
\&    $file = $grid\->get($id);
.Ve
.PP
Get a file from GridFS based on its _id.  Returns a MongoDB::GridFS::File.
.PP
To retrieve a file based on metadata like \f(CW\*(C`filename\*(C'\fR, use the \*(L"find_one\*(R"
method instead.
.SS "put"
.IX Subsection "put"
.Vb 2
\&    $id = $grid\->put($fh, $metadata);
\&    $id = $grid\->put($fh, {filename => "pic.jpg"});
.Ve
.PP
Inserts a file into GridFS, adding a MongoDB::OID as the _id field if the
field is not already defined.  This is a wrapper for \f(CW\*(C`MongoDB::GridFS::insert\*(C'\fR,
see that method below for more information.
.PP
Returns the _id field.
.SS "delete"
.IX Subsection "delete"
.Vb 1
\&    $grid\->delete($id)
.Ve
.PP
Removes the file with the given _id.  Will die if the remove is unsuccessful.
Does not return anything on success.
.SS "find_one"
.IX Subsection "find_one"
.Vb 2
\&    $file = $grid\->find_one({"filename" => "foo.txt"});
\&    $file = $grid\->find_one($criteria, $fields);
.Ve
.PP
Returns a matching MongoDB::GridFS::File or undef.
.SS "remove"
.IX Subsection "remove"
.Vb 2
\&    $grid\->remove({"filename" => "foo.txt"});
\&    $grid\->remove({"filename" => "foo.txt"}, $options);
.Ve
.PP
Cleanly removes files from the database.  \f(CW$options\fR is a hash of options for
the remove.
.PP
A hashref of options may be provided with the following keys:
.IP "\(bu" 4
\&\f(CW\*(C`just_one\*(C'\fR: If true, only one file matching the criteria will be removed.
.IP "\(bu" 4
\&\f(CW\*(C`safe\*(C'\fR: (\s-1DEPRECATED\s0) If true, each remove will be checked for success and die on failure.  Set the \*(L"write_concern\*(R" attribute instead.
.PP
This method doesn't return anything.
.SS "insert"
.IX Subsection "insert"
.Vb 3
\&    $id = $gridfs\->insert($fh);
\&    $id = $gridfs\->insert($fh, $metadata);
\&    $id = $gridfs\->insert($fh, $metadata, $options);
\&
\&    $id = $gridfs\->insert($fh, {"content\-type" => "text/html"});
.Ve
.PP
Reads from a file handle into the database.  Saves the file with the given
metadata.  The file handle must be readable.
.PP
A hashref of options may be provided with the following keys:
.IP "\(bu" 4
\&\f(CW\*(C`safe\*(C'\fR: (\s-1DEPRECATED\s0) Will do safe inserts and check the \s-1MD5\s0 hash calculated by the database against an \s-1MD5\s0 hash calculated by the local filesystem.  If the two hashes do not match, then the chunks already inserted will be removed and the program will die. Set the \*(L"write_concern\*(R" attribute instead.
.PP
Because \f(CW\*(C`MongoDB::GridFS::insert\*(C'\fR takes a file handle, it can be used to insert
very long strings into the database (as well as files).  \f(CW$fh\fR must be a
FileHandle (not just the native file handle type), so you can insert a string
with:
.PP
.Vb 2
\&    # open the string like a file
\&    open($basic_fh, \*(Aq<\*(Aq, \e$very_long_string);
\&
\&    # turn the file handle into a FileHandle
\&    $fh = FileHandle\->new;
\&    $fh\->fdopen($basic_fh, \*(Aqr\*(Aq);
\&
\&    $gridfs\->insert($fh);
.Ve
.SS "drop"
.IX Subsection "drop"
.Vb 1
\&    $grid\->drop;
.Ve
.PP
Removes all files' metadata and contents.
.SS "all"
.IX Subsection "all"
.Vb 1
\&    @files = $grid\->all;
.Ve
.PP
Returns a list of the files in the database as MongoDB::GridFS::File
objects.
.SH "DEPRECATION"
.IX Header "DEPRECATION"
\&\fBNote\fR: This class has been deprecated in favor of
MongoDB::GridFSBucket, which implements the new, driver-standard GridFS
\&\s-1API.\s0  It is also faster and more flexible than this class.  This class will
be removed in a future release and you are encouraged to migrate your
applications to MongoDB::GridFSBucket.
.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) 2018 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve