MorboDB::Collection - A MorboDB collection
version 0.001002
my $coll = $db->get_collection('users'); my $id = $coll->insert({ username => 'someguy98', password => 's3cr3t', email => 'email at address dot com', }); my $cursor = $coll->find({ email => qr/\@address\.com$/ })->sort({ username => 1 }); # use cursor according to MorboDB::Cursor
This module provides the API for handling collections in a MorboDB::Database.
The name of the collection. String, required.
The full name of the collection, including the name of the database, joined by dots. String, created automatically.
Receives a hash-reference, array-reference or Tie::IxHash object and converts into a query string.
Executes the given query and returns a MorboDB::Cursor object with the results (if query is not provided, all documents in the collection will match). $query can be a hash reference, a Tie::IxHash object, or array reference (with an even number of elements).
$query
The set of fields returned can be limited through the use of the MorboDB::Cursor->fields() method on the resulting cursor object. Other commonly used cursor methods are limit(), skip(), and sort().
MorboDB::Cursor->fields()
limit()
skip()
sort()
As opposed to MongoDB::Collection->find(), this method doesn't take a hash-ref of options such as fields and sort, use the appropriate methods on the cursor instead (this is also deprecated in MongoDB anyway).
MongoDB::Collection->find()
fields
sort
Note that currently, providing a Tie::IxHash object or array reference will have no special effect, as the query will be converted into a hash reference. This may or may not change in future version.
Tie::IxHash
For a complete reference on querying in MorboDB, please look at "QUERY STRUCTURES" in MQUL::Reference.
Alias for find().
find()
Executes the provided query and returns the first result found (if any, otherwise undef is returned).
undef
Internally, this is really a shortcut for running $coll->find($query)->limit(1)->next().
$coll->find($query)->limit(1)->next()
Inserts the given document into the database and returns it's ID. The document can be a hash reference, an even-numbered array reference or a Tie::IxHash object. The ID is the _id value specified in the data or a MorboDB::OID object created automatically.
Note that providing a Tie::IxHash object or array reference will not make your document ordered, as documents are always saved as hash references, so this has no benefit except compatibility with MongoDB.
Inserts each of the documents in the array into the database and returns an array of their _id attributes.
Updates document(s) that match the provided query (which is the same as what find() accepts) according to the update (\%update) hash-ref.
\%update
Return a hash-ref of information about the update, including number of documents updated (n).
update() can take a hash reference of options. The options currently supported are:
update()
upsert - If no object matches the query, \%update will be inserted as a new document (possibly taking values from $query too).
upsert
multiple - All of the documents that match the query will be updated, not just the first document found.
multiple
For a complete reference on update syntax and behavior, please look at "UPDATE STRUCTURES" in MQUL::Reference.
Removes all objects matching the given query from the database. If a query is not given, removes all objects from the collection.
Returns a hash-ref of information about the remove, including how many documents were removed (n).
remove() can take a hash reference of options. The options currently supported are:
remove()
just_one - Only one matching document to be removed instead of all.
just_one
Not implemented. Simply returns true here.
Inserts a document into the database if it does not have an _id field, upserts it if it does have an _id field. Mostly used internally. Document must be a hash-reference.
_id
Shortcut for running $coll->find($query)->count().
$coll->find($query)->count()
Not implemented. Returns an empty hash-ref here.
Not implemented. Returns true here.
Not implemented. Returns false here.
Deletes the collection and all documents in it.
This module throws the following exceptions:
expected Tie::IxHash, hash, or array reference for keys
This error is returned by the static to_index_string() function if you're not providing it with a hash reference, array reference (even-numbered) or Tie::IxHash object.
to_index_string()
query must be a hash reference, even-numbered array reference or Tie::IxHash object.
This error is returned by the find(), query(), update(), remove() and count() methods, that expect a query that is either a hash reference, even-numbered array reference or Tie::IxHash object. Just make sure you're providing a valid query variable.
query()
count()
batch_insert() expects an array reference of documents.
This error is thrown by batch_insert() if you're not giving it an array reference of documents to insert into the database.
batch_insert()
data to insert must be a hash reference, even-numbered array reference or Tie::IxHash object.
This error is thrown by insert() and batch_insert() when you're providing them with a document which is not a hash reference, even-numbered array reference or Tie::IxHash object. Just make sure your document(s) is/are valid.
insert()
duplicate key error, ID %s already exists in the collection.
This error is thrown by insert() and batch_insert(), when you're trying to insert a document with an _id attribute that already exists in the collection. If you're trying to update a document you know already exists, use the update() method instead. Otherwise you're just doing it wrong.
the update structure must be a hash reference.
This error is thrown by the update() method when you're not giving it a proper update hash-ref, as described by "UPDATE STRUCTURES" in MQUL::Reference.
the options structure must be a hash reference.
This error is thrown by update() when you're providing it with a third argument that should be an options hash-ref, or by the remove() method when you're providing it with a second argument that should be an options hash-ref. Just make sure you're not sending non hash-refs to these methods.
document to save must be a hash reference.
This error is thrown by the save() method when it receives a document which is not a hash reference. If this happens when invoking insert() or batch_insert(), and non of the specific errors of these methods were thrown, please submit a bug report. Otherwise (if you've called save() directly, please make sure you're providing a hash reference. As opposed to insert() and batch_insert(), save() does not take a Tie::IxHash objects or even-numbered array references.
save()
No bugs have been reported.
Please report any bugs or feature requests to bug-MorboDB@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MorboDB.
bug-MorboDB@rt.cpan.org
MongoDB::Collection.
Ido Perlmuter <ido@ido50.net>
Copyright (c) 2011, Ido Perlmuter ido@ido50.net.
ido@ido50.net
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either version 5.8.1 or any later version. See perlartistic and perlgpl.
The full text of the license can be found in the LICENSE file included with this module.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install MorboDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MorboDB
CPAN shell
perl -MCPAN -e shell install MorboDB
For more information on module installation, please visit the detailed CPAN module installation guide.