/ 
MorboDB-0.001002
River stage zero No dependents
/ MorboDB::Collection

NAME

MorboDB::Collection - A MorboDB collection

VERSION

version 0.001002

SYNOPSIS

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

DESCRIPTION

This module provides the API for handling collections in a MorboDB::Database.

ATTRIBUTES

name

The name of the collection. String, required.

full_name

The full name of the collection, including the name of the database, joined by dots. String, created automatically.

STATIC FUNCTIONS

to_index_string( $keys )

Receives a hash-reference, array-reference or Tie::IxHash object and converts into a query string.

OBJECT METHODS

find( [ $query ] )

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

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().

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

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.

For a complete reference on querying in MorboDB, please look at "QUERY STRUCTURES" in MQUL::Reference.

query( [ $query ] )

Alias for find().

find_one( [ $query ] )

Executes the provided query and returns the first result found (if any, otherwise undef is returned).

Internally, this is really a shortcut for running $coll->find($query)->limit(1)->next().

insert( $doc )

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.

batch_insert( \@docs )

Inserts each of the documents in the array into the database and returns an array of their _id attributes.

update( $query, \%update, [ \%opts ] )

Updates document(s) that match the provided query (which is the same as what find() accepts) according to the update (\%update) hash-ref.

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:

  • upsert - If no object matches the query, \%update will be inserted as a new document (possibly taking values from $query too).

  • multiple - All of the documents that match the query will be updated, not just the first document found.

For a complete reference on update syntax and behavior, please look at "UPDATE STRUCTURES" in MQUL::Reference.

remove( [ $query, \%opts ] )

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:

  • just_one - Only one matching document to be removed instead of all.

ensure_index()

Not implemented. Simply returns true here.

save( \%doc )

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.

count( [ $query ] )

Shortcut for running $coll->find($query)->count().

validate()

Not implemented. Returns an empty hash-ref here.

drop_indexes()

Not implemented. Returns true here.

drop_index()

Not implemented. Returns true here.

get_indexes()

Not implemented. Returns false here.

drop()

Deletes the collection and all documents in it.

DIAGNOSTICS

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.

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.

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.

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.

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.

BUGS AND LIMITATIONS

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.

SEE ALSO

MongoDB::Collection.

AUTHOR

Ido Perlmuter <ido@ido50.net>

LICENSE AND COPYRIGHT

Copyright (c) 2011, Ido Perlmuter 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.

DISCLAIMER OF WARRANTY

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.