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