MongoDB Inc > MongoDB > MongoDB::GridFS

Download:
MongoDB-v1.4.4.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v1.4.4   Source  

NAME ^

MongoDB::GridFS - A file storage abstraction (DEPRECATED)

VERSION ^

version v1.4.4

SYNOPSIS ^

    my $grid = $database->get_gridfs;
    my $fh = IO::File->new("myfile", "r");
    $grid->insert($fh, {"filename" => "mydbfile"});

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 get_gridfs on a MongoDB::Database object.

USAGE ^

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.

Error handling

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

To catch and handle errors, the Try::Tiny and Safe::Isa modules are recommended:

    use Try::Tiny;
    use Safe::Isa; # provides $_isa

    try {
        $grid->get( $id )
    }
    catch {
        if ( $_->$_isa("MongoDB::TimeoutError" ) {
            ...
        }
        else {
            ...
        }
    };

To retry failures automatically, consider using Try::Tiny::Retry.

ATTRIBUTES ^

chunk_size

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

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.

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.

max_time_ms

Specifies the default maximum amount of time in milliseconds that the server should use for working on a query.

Note: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS meta-operator was introduced.

bson_codec

An object that provides the encode_one and decode_one 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.

prefix

The prefix used for the collections. Defaults to "fs".

METHODS ^

get

    $file = $grid->get($id);

Get a file from GridFS based on its _id. Returns a MongoDB::GridFS::File.

To retrieve a file based on metadata like filename, use the "find_one" method instead.

put

    $id = $grid->put($fh, $metadata);
    $id = $grid->put($fh, {filename => "pic.jpg"});

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 MongoDB::GridFS::insert, see that method below for more information.

Returns the _id field.

delete

    $grid->delete($id)

Removes the file with the given _id. Will die if the remove is unsuccessful. Does not return anything on success.

find_one

    $file = $grid->find_one({"filename" => "foo.txt"});
    $file = $grid->find_one($criteria, $fields);

Returns a matching MongoDB::GridFS::File or undef.

remove

    $grid->remove({"filename" => "foo.txt"});
    $grid->remove({"filename" => "foo.txt"}, $options);

Cleanly removes files from the database. $options is a hash of options for the remove.

A hashref of options may be provided with the following keys:

This method doesn't return anything.

insert

    $id = $gridfs->insert($fh);
    $id = $gridfs->insert($fh, $metadata);
    $id = $gridfs->insert($fh, $metadata, $options);

    $id = $gridfs->insert($fh, {"content-type" => "text/html"});

Reads from a file handle into the database. Saves the file with the given metadata. The file handle must be readable.

A hashref of options may be provided with the following keys:

Because MongoDB::GridFS::insert takes a file handle, it can be used to insert very long strings into the database (as well as files). $fh must be a FileHandle (not just the native file handle type), so you can insert a string with:

    # open the string like a file
    open($basic_fh, '<', \$very_long_string);

    # turn the file handle into a FileHandle
    $fh = FileHandle->new;
    $fh->fdopen($basic_fh, 'r');

    $gridfs->insert($fh);

drop

    $grid->drop;

Removes all files' metadata and contents.

all

    @files = $grid->all;

Returns a list of the files in the database as MongoDB::GridFS::File objects.

DEPRECATION ^

Note: This class has been deprecated in favor of MongoDB::GridFSBucket, which implements the new, driver-standard GridFS API. 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.

SEE ALSO ^

Core documentation on GridFS: http://dochub.mongodb.org/core/gridfs.

AUTHORS ^

COPYRIGHT AND LICENSE ^

This software is Copyright (c) 2016 by MongoDB, Inc.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004
syntax highlighting: