view release on metacpan or  search on metacpan

lib/MongoDB/GridFSBucket.pm  view on Meta::CPAN

Valid file documents typically include the following fields:

=over 4

=item *

_id – a unique ID for this document, typically a BSON ObjectId.

=item *

length – the length of this stored file, in bytes

=item *

chunkSize – the size, in bytes, of each full data chunk of this file. This value is configurable per file.

=item *

uploadDate – the date and time this file was added to GridFS, stored as a BSON datetime value.

=item *

filename – the name of this stored file; the combination of filename and uploadDate (millisecond resolution) must be unique

=item *

metadata – any additional application data the user wishes to store (optional)

=item *

md5 – DEPRECATED a hash of the contents of the stored file (store this in C<metadata> if you need it) (optional)

=item *

contentType – DEPRECATED (store this in C<metadata> if you need it) (optional)

=item *

aliases – DEPRECATED (store this in C<metadata> if you need it) (optional)

=back

The C<find> method searches file documents using these fields.  Given the
C<_id> from a document, a file can be downloaded using the download
methods.

=head2 API Overview

In addition to general methods like C<find>, C<delete> and C<drop>, there
are two ways to go about uploading and downloading:

=over 4

=item *

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.

=item *

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.

=back

=head2 Error handling

Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs.  The error types are documented in L<MongoDB::Error>.

=head1 ATTRIBUTES

=head2 database

The L<MongoDB::Database> containing the GridFS bucket collections.

=head2 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").

=head2 chunk_size_bytes

The number of bytes per chunk.  Defaults to 261120 (255kb).

=head2 write_concern

A L<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 L<MongoDB::Database> object.

=head2 read_concern

A L<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 L<MongoDB::Database> object.

=head2 read_preference

A L<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 L<MongoDB::Database> object.

B<Note:> Because many GridFS operations require multiple independent reads from
separate collections, use with secondaries is B<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.

=head2 bson_codec

An object that provides the C<encode_one> and C<decode_one> methods, such
as from L<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 L<MongoDB::Database> object.

=head2 max_time_ms

Specifies the maximum amount of time in milliseconds that the server should