trusty (3) MongoDBx::Class::Collection.3pm.gz

Provided by: libmongodbx-class-perl_1.02-3_all bug

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.


       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.