NAME

       MongoDBx::Class::Collection - A MongoDBx::Class collection object

VERSION

       version 1.02

EXTENDS

       MongoDB::Collection

SYNOPSIS

               # get a collection from a L<MongoDBx::Class::Database> object
               my $coll = $db->get_collection($coll_name); # or $db->$coll_name

               # insert a document
               my $doc = $coll->insert({ title => 'The Valley of Fear', year => 1914, author => 'Conan Doyle', _class => 'Novel' }, { safe => 1 });

               # find some documents
               my @docs = $coll->find({ author => 'Conan Doyle' })->sort({ year => 1 })->all;

DESCRIPTION

       MongoDBx::Class::Collection extends MongoDB::Collection. It adds some convenient options
       to the syntax and a few method modifications to allow automatic document expansion (when
       finding) and collapsing (when inserting).

       If you're not familiar with MongoDB::Collection, please read it first.

ATTRIBUTES

       No special attributes are added.

OBJECT METHODS

       The following methods are available along with all methods defined in MongoDB::Collection.
       However, most (or all) of those are modifications of MongoDB::Collection methods.

   find( \%query, [ \%attrs ] )
   query( \%query, [ \%attrs ] )
   search( \%query, [ \%attrs ] )
       All three methods are equivalent (the last two aliases of the first).  These methods
       perform a search for documents in the collection for documents matching a certain query
       and return a MongoDBx::Class::Cursor object. Refer to "find($query)" in
       MongoDB::Collection for more information about queries.

       These methods are modified in the following way:

       1. They return a MongoDBx::Class::Cursor object instead of a plain MongoDB::Cursor object.

       2. The "sort_by" attribute in the $attr hash-ref can contain an array-ref instead of a
       Tie::IxHash object, such as:

               $coll->find({ some => 'thing' }, { sort_by => [ title => 1, some => -1 ] })

       This array-ref will be converted into a Tie::IxHash object automatically.

   find_one( $query, [ \%fields ] )
       Performs a query on the collection and returns the first matching document.

       This method is modified in the following way:

       1. In MongoDB::Collection, $query can either be a hash-ref, a Tie::IxHash object or an
       array-ref. Here, however, $query can also be a MongoDB::OID, or a MongoDB::OID's string
       representation (see "to_string" in MongoDB::OID).  Searching by internal ID is thus much
       more convenient:

               my $doc = $coll->find_one("4cbca90d3a41e35916720100");

       2. The matching document is automatically expanded to the appropriate document class, but
       only if it has the '_class' attribute (as described in "CAVEATS AND THINGS TO CONSIDER" in
       MongoDBx::Class). If it doesn't, or if expansion is impossible due to other reasons, it
       will be returned as is (i.e. as a hash-ref).

       3. In MongoDB::Collection, passing a "\%fields" hash-ref will result in the document being
       returned with those fields only (and the _id field).  Behavior of this when documents are
       expanded is currently undefined.

   insert( $doc, [ \%opts ] )
       Inserts the given document into the database, automatically collapsing it before
       insertion.

       An optional options hash-ref can be passed. If this hash-ref holds a safe key with a true
       value, insert will be safe (refer to "insert ($object, $options?)" in MongoDB::Collection
       for more information). When performing a safe insert, the newly created document is
       returned (after expansions). If unsafe, its MongoDB::OID is returned.

       If your connection object has a true value for the safe attribute, insert will be safe by
       default. If that is the case, and you want the specific insert to be unsafe, pass a false
       value for "safe" in the "\%opts" hash-ref.

       Document to insert can either be a hash-ref, a Tie::IxHash object or an even-numbered
       array-ref, but currently only hash-refs are automatically collapsed.

   batch_insert( \@docs, [ \%opts ] )
       Receives an array-ref of documents and an optional hash-ref of options, and inserts all
       the documents to the collection one after the other. "\%opts" can have a "safe" key that
       should hold a boolean value. If true (and if your connection object has a true value for
       the safe attribute), inserts will be safe, and an array of all the documents inserted
       (after expansion) will be returned. If false, an array with all the document IDs is
       returned.

       Documents to insert can either be hash-refs, Tie::IxHash objects or even-numbered array
       references, but currently only hash-refs are automatically collapsed.

   update( \%criteria, \%object, [ \%options ] )
       Searches for documents matching "\%criteria" and updates them according to "\%object"
       (refer to "update (\%criteria, \%object, \%options?)" in MongoDB::Collection for more
       info). As opposed to the original method, this method will automatically collapse the
       "\%object" hash-ref. It will croak if criteria and/or object aren't hash references.

       Do not use this method to update a specific document that you already have (i.e. after
       expansion). MongoDBx::Class::Document has its own update method which is more convenient.

       Notice that this method doesn't collapse attributes with the Parsed trait. Only the
       MongoDBx::Class::Document update method performs that.

   ensure_index( $keys, [ \%options ] )
       Makes sure the given keys of this collection are indexed. $keys is either an unordered
       hash-ref, an ordered Tie::IxHash object, or an ordered, even-numbered array reference like
       this:

               $coll->ensure_index([ title => 1, date => -1 ])

INTERNAL METHODS

       The following methods are only to be used internally:

   _collapse_hash( \%object )
       Collapses an entire hash-ref for proper database insertions.

AUTHOR

       Ido Perlmuter, "<ido at ido50.net>"

BUGS

       Please report any bugs or feature requests to "bug-mongodbx-class at rt.cpan.org", or
       through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MongoDBx-Class
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MongoDBx-Class>. I will be notified, and
       then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

               perldoc MongoDBx::Class::Collection

       You can also look for information at:

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MongoDBx::Class>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/MongoDBx::Class>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/MongoDBx::Class>

       •   Search CPAN

           <http://search.cpan.org/dist/MongoDBx::Class/>

SEE ALSO

       MongoDB::Collection.

LICENSE AND COPYRIGHT

       Copyright 2010-2012 Ido Perlmuter.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See http://dev.perl.org/licenses/ for more information.