MongoDBI::Document::Storage::Operation - Standard MongoDBI Document/Collection Operations
version 0.0.12
package main; my $cds = CDDB::Album; my @cds = $cds->all; # returns all records (as hashes not instances) foreach my $cd (@cds) { my $this_cd = $cds->new(%{ $cd }); my $that_cd = $this_cd->clone; $this_cd->rating(5); $that_cd->rating(1); $this_cd->save; # save changes to existing cd $that_cd->insert; # new cd record } 1;
MongoDBI::Document::Storage::Operation is a role that provides collection-specific functionality to your MongoDBI document classes.
The all method, called on the class or instance, returns an arrayref of hashrefs corresponding to the documents in the document class collection which match the criteria specified.
my @cds = CDDB::Album->all; ... db.albums.find(); my @cds = CDDB::Album->all(title => 'Thriller'); ... db.albums.find({ "title" : "thriller" }); # using M::D::S::Criterion query syntax my @cds = CDDB::Album->all('rating$gt' => 10); ... db.albums.find({ "rating" : { "$gt" : 10 } });
The clone method, can only be called on a class instance which has been previously inserted thus having a valid ID, returns a cloned instance of itself including set attributes and configuration minus its ID.
my $cd1 = CDDB::Album->first; # get the first record as an instance my $cd2 = $cd1->clone; $cd2->insert; # insert not save, can't save without an id
The collection method, called on a class or instance, simply returns the MongoDB::Collection object set in the current document class configuration.
my $mongo_col = CDDB::Album->collection;
The connection method, called on a class or instance, simply returns the MongoDB::Connection object set in the current document class configuration.
my $mongo_con = CDDB::Album->connection;
The count method, called on a class or instance, simply returns the total number of documents matching the specified criteria.
my $count = CDDB::Album->count; ... db.albums.find().count(); my $count = CDDB::Album->all(title => 'Thriller'); ... db.albums.find({ "title" : "thriller" }).count();
The create method, called on a class or instance, inserts a new document into the database and returns the newly create class instance.
my $cd = CDDB::Album->create(title => 'Greatest HITS', released => ...); $cd->title('Greatest Hits'); $cd->save;
The execute_on method, called on a class or instance, is designed to allow the execution of specific database commands against alternate database servers. While it was certainly the goal for this method to be instrumental in providing support for MongoDB clustered environments (master/slave, replicasets, etc), this method has many applications.
my $cds = CDDB::Album; my @cds = $cds->all; # returns all records (from 127.0.0.1, default) $cds->execute_on('192.168.1.101' => sub { foreach my $cd (@cds) { # save changes to cd on the master server $cd->rating(5); $cd->save; } }); # or ... $cds->execute_on(name => 'alt_dbname', host => '192.168.1.101', sub { foreach my $cd (@cds) { # save changes to cd on the master server $cd->rating(5); $cd->save; } }); # or ... # if using MongoDBI::Application with connection pooling my @cds = $cds->execute_on('slave' => sub { return shift->all }); $cds->execute_on('master' => sub { foreach my $cd (@cds) { # save changes to cd on the master server $cd->rating(5); $cd->save; } });
The find method, called on a class or instance, not to be confused with the find method available via the MongoDB driver, allows you to quickly query a resultset using the syntax described in MongoDBI::Document::Storage::Criterion.
The find method always returns a MongoDB::Cursor object, it accepts a single argument (just the document ID, not MongoDB::OID) or key/value query syntax. If you would like to pass in a MongoDB::OID object to reference the document ID, please use the following syntax:
my $cd = CDDB::Album->find('4df7a599005ec15814000000')->next; my $cd = CDDB::Album->find(_id => $mongo_oid)->next; my $search = CDDB::Album->find(title => qr/Hits/); while (my $cd = $search->next) { ... }
The find_one method, called on a class or instance, not to be confused with the find_one method available via the MongoDB driver, allows you to quickly query a resultset using the MongoDBI::Document::Storage::Criterion syntax.
The find_one method tries to return an instance of the current class based on the result of the query. The find_one method accepts a single argument (just the document ID, not MongoDB::OID) or key/value query syntax. If you would like to pass in a MongoDB::OID object to reference the document ID, please use the following syntax:
my $cd = CDDB::Album->find_one('4df7a599005ec15814000000'); my $cd = CDDB::Album->find_one(_id => $mongo_oid); my $search = CDDB::Album->find_one(title => qr/Hits/);
The find_or_create method, called on a class or instance, attempts to find a single document based on the passed-in criteria, returning a class instance based on the returned document, if no matching documents can be found inserts a new document into the database and returns the newly create class instance.
my $cd = CDDB::Album->find_or_create(title => 'Greatest HITS'); $cd->save;
The find_or_new method, called on a class or instance, attempts to find a single document based on the passed-in criteria, returning a class instance based on the returned document, if no matching documents can be found instantiates and returns a new class object.
my $cd = CDDB::Album->find_or_new(title => 'Greatest HITS'); $cd->id ? $cd->save : $cd->insert;
The full_name method, called on a class or instance, simply returns the fully-qualified database collection name based on the collection and connection configuration.
CDDB::Album->config->set_database('test'); my $col_name = CDDB::Album->full_name; print $col_name; # prints test.albums
The first method, called on a class or instance, allows you to quickly query a resultset using the MongoDBI::Document::Storage::Criterion syntax returning an instance of the current class based on the first result of the query automatically sorted by ID in ascending order. The first method accepts key/value query syntax.
my $cd = CDDB::Album->first; my $cd = CDDB::Album->first(title => qr/Hits/);
The insert method, can only be called on a class instance which has NOT been previously inserted thus not having an ID set, collapses the dirty attributes/fields and inserts the instance into the defined collection returning itself.
my $cd1 = CDDB::Album->new(...); $cd1->insert;
The last method, called on a class or instance, allows you to quickly query a resultset using the MongoDBI::Document::Storage::Criterion syntax returning an instance of the current class based on the last result of the query automatically sorted by ID in descending order. The last method accepts key/value query syntax.
my $cd = CDDB::Album->last; my $cd = CDDB::Album->last(title => qr/Hits/);
The name method, called on a class or instance, simply returns the name of the database collection based on the collection configuration.
my $col_name = CDDB::Album->name; print $col_name; # prints albums
The query method, called on a class or instance, is shorthand (an alias) for calling the search method and eventually calling the query method within MongoDBI::Document::Storage::Criterion package executing pre-defined filters and returning the resulting MongoDB::Cursor object.
package CDDB::Album; use MongoDBI::Document; filter 'w_quantity' => sub { my ($filter, $self, $cond, $value) = @_; $filter->and_where("quantity$cond" => $value); }; package main; # note: any arg not recognized as an pre-defined filter is passed to the # filter preceding it my $cursor = CDDB::Album->query('w_quantity', '$gte', 1000); # is the equivalent of ... my $search = CDDB::Album->search->where('w_quantity', '$gte', 1000); my $cursor = $search->query; while (my $document = $cursor->next) { ... }
The reload method, can only be called on a class instance which has been previously inserted thus having an ID set, uses the ID to poll the database returning a new instance object based on the query result if any.
This method is useful in stateless applications or applications where the instance may remain in-use for an inordinate amount of time allowing someone else the possibility to update that exact same record with information that differs from your own unsaved object thus having your eventual save overwrite their changes.
my $cd1 = CDDB::Album->first; ... 10 mins later ... # i should probably reload this object before making changes $cd1->reload; $cd1->title(...); # change it $cd1->save;
The remove method, can only be called on a class instance which has been previously inserted thus having an ID set, uses the ID to poll the database for the corresponding document and removes it (both on the object and in the collection) returning a copy of the original before deletion.
my $cd1 = CDDB::Album->first; # $cd1 = $cd1->remove; if you're a stickler for convention $cd1->remove; $cd1->title(...); # completely new title $cd1->insert; # new document based on the deleted
The save method, can only be called on a class instance which has been previously inserted thus having an ID set, uses the ID to poll the database for the corresponding document updating the "dirty fields only" while saving it to the database.
my $cd1 = CDDB::Album->first; $cd1->save; # saves nothing $cd1->title(...); # completely new title $cd1->save; # save, updating the title only, not the entire document
The search method, called on a class or instance, simply returns a MongoDBI::Document::Storage::Criterion object allowing you to build complex queries.
my $search = CDDB::Album->search; my $search = CDDB::Album->search->where('title$in' => ['Bad', 'Thriller']); # call query to return a MongoDB::Cursor object for further usage my $cursor = $search->query; while (my $document = $cursor->next) { ... }
The search method also supports another syntax for chaining stored queries/filters.
package CDDB::Album; use MongoDBI::Document; filter 'filter_a' => sub { my ($filter, $self, @ ) = @_; $filter->and_where(...) }; filter 'filter_b' => sub { my ($filter, $self, @args) = @_; $filter->and_where(...) }; package main; my $search = CDDB::Album->search('filter_a', 'filter_b'); # experimental syntax (pass args to filters) # my $search = CDDB::Album->search('filter_a', 'filter_b' => (1..9)); # my $search = CDDB::Album->search('filter_a' => (1..9), 'filter_b'); my $cursor = $search->query; while (my $document = $cursor->next) { ... }
The update method, unlike the MongoDB driver update method, can only be called on a class instance which has been previously inserted thus having an ID set, uses the ID to poll the database for the corresponding document updating the "dirty fields only" while saving it to the database. The main difference between the update method and the save method is that the update method can change the entire structure of the document by discarding fields that haven't been set.
You can safely use the save option where the update function might sound like the right choice, and only use the update option when needed (knowing exactly what it does). The following is an example:
my $cd1 = CDDB::Album->first; $cd1->update; # updates nothing $cd1->title(...); # completely new title $cd1->update; # update, updating the title only, not the entire document $cd1->update(set => 0); # update, replacing the document with title and ID
Al Newkirk <awncorp@cpan.org>
This software is copyright (c) 2011 by awncorp.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install MongoDBI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDBI
CPAN shell
perl -MCPAN -e shell install MongoDBI
For more information on module installation, please visit the detailed CPAN module installation guide.