/ 
MongoDBx-Class-1.030002
River stage zero No dependents
/ MongoDBx::Class::Collection

NAME

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

VERSION

version 1.030002

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. 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:

SEE ALSO

MongoDB::Collection.

LICENSE AND COPYRIGHT

Copyright 2010-2014 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.