MongoDB::QueryBuilder - Query Builder for MongoDB
version 0.0005
use MongoDB; use MongoDB::QueryBuilder; # build query conditions my $query = MongoDB::QueryBuilder->new( and_where => ['cd.title' => $some_title], and_where => ['cd.released$gt$date' => $some_isodate], any_in => ['cd.artist' => $some_artist], page => [25, 0], ); # .. in sql # .. select * from cds cd where cd.title = ? and # .. cd.released > ? and cd.artist IN (?) limit 25 offset 0 # connect and query my $client = MongoDB::MongoClient->new(host => 'localhost:27017'); my $database = $client->get_database('musicbox'); my $collection = $query->collection($database->get_collection('cds')); my $cursor = $query->cursor; while (my $album = $cursor->next) { say $album->{name}; }
MongoDB::QueryBuilder provides an interface to query MongoDB using chainable objects for building complex and dynamic queries. This module will only hit the database when you ask it to return a MongoDB::Cursor object.
The new method is the object constructor, it accepts a single hashref or list containing action/value pairs where an action is a MongoDB::QueryBuilder class method and a value is a scalar or arrayref. All methods that do not interact with the database can be passed as an argument.
my $query = MongoDB::QueryBuilder->new( where => ['record_label' => 'Time-Warner'], limit => 25 );
The all_in method adds a criterion which returns documents where the field specified holds an array which contains all of the values specified. The corresponding MongoDB operation is $all.
$query->all_in(tags => ['hip-hop', 'rap']); # e.g. { "tags" : { "$all" : ['hip-hop', 'rap'] } }
Please see http://docs.mongodb.org/manual/reference/operator/all/ for more information.
The and_where method adds a criterion which returns documents where the clauses specified must all match in order to return results. The corresponding MongoDB operation is $and.
$query->and_where('quantity$lt' => 50, status => 'available'); # e.g. { "$and" : [ { "quantity" : { "$lt" : 50 } }, { "status" : "available" } ] }
Please see http://docs.mongodb.org/manual/reference/operator/and/ for more information.
The any_in method adds a criterion which returns documents where the field specified must holds one of the values specified in order to return results. The corresponding MongoDB operation is $in.
$query->any_in(tags => ['hip-hop', 'rap']); # e.g. { "tags" : { "$in" : ['hip-hop', 'rap'] } }
Please see http://docs.mongodb.org/manual/reference/operator/in/ for more information.
The asc_sort method adds a criterion that instructs the MongoDB::Cursor object to sort the results on specified key(s) in ascending order.
$query->asc_sort('artist.first_name', 'artist.last_name');
The collection method provides an accessor for the MongoDB::Collection object used to query the database.
my $collection = $query->collection($new_collection);
The criteria method provides an accessor for the query-specification-object used to query the database.
my $criteria = $query->criteria;
The criteria_where method is a convenience method which provides access to the query-specification where-clause.
my $criteria = $query->criteria_where
The cursor method analyzes the current query criteria, generates a MongoDB::Cursor object and queries the databases.
my $cursor = $query->cursor;
The desc_sort method adds a criterion that instructs the MongoDB::Cursor object to sort the results on specified key(s) in ascending order.
$query->desc_sort('artist.first_name', 'artist.last_name');
The limit method adds a criterion that instructs the MongoDB::Cursor object to limit the results by the number specified.
$query->limit(25);
The near method adds a criterion to find locations that are near the supplied coordinates. This performs a MongoDB $near selection and requires a 2d index on the field specified. The corresponding MongoDB operation is $near.
$query->near('store.location.latlng' => [52.30, 13.25]); # e.g. { "store.location.latlng" : { "$near" : [52.30, 13.25] } }
Please see http://docs.mongodb.org/manual/reference/operator/near/ for more information.
The never method adds a criterion that instructs the MongoDB::Cursor object to select all columns except the ones specified. The opposite of this is the only() method, these two methods can't be used together.
$query->never('password', 'apikey');
The nor_where method adds a criterion which returns documents where none of the clauses specified should match in order to return results. The corresponding MongoDB operation is $nor.
$query->nor_where('quantity$lte' => 30, 'quantity$gte' => 10); # e.g. { "$nor" : [ { "quantity" : { "$lte" : 30 } }, { "quantity" : { "$gte" : 10 } } ] }
Please see http://docs.mongodb.org/manual/reference/operator/nor/ for more information.
The not_in method adds a criterion which returns documents where the field specified must not hold any of the values specified in order to return results. The corresponding MongoDB operation is $nin.
$query->not_in('artist.last_name' => ['Jackson', 'Nelson']); # e.g. { "artist.last_name" : { "$nin" : ['Jackson', 'Nelson'] } }
Please see http://docs.mongodb.org/manual/reference/operator/nin/ for more information.
The offset method adds a criterion that instructs the MongoDB::Cursor object to offset the results by the number specified.
The only method adds a criterion that instructs the MongoDB::Cursor object to select only the columns specified. The opposite of this is the never() method, these two methods can't be used together.
$query->only('artist.first_name', 'artist.last_name');
The or_where method adds a criterion which returns documents where at-least one of the clauses specified must match in order to return results. The corresponding MongoDB operation is $or.
$query->or_where('quantity$lte' => 30, 'quantity$gte' => 10); # e.g. { "$or" : [ { "quantity" : { "$lte" : 30 } }, { "quantity" : { "$gte" : 10 } } ] }
Please see http://docs.mongodb.org/manual/reference/operator/or/ for more information.
The page method is a purely a convenience method which adds a limit and offset criterion to the query. The page parameter is optional and defaults to 0, it should be a number that when multiplied by the limit will represents how many documents should be offset.
$query->page($limit, $page); # page is optional and defaults to 0
The sort method adds a criterion that instructs the MongoDB::Cursor object to sort the results on specified key(s) in the specified order.
$query->sort('artist.first_name' => -1, 'artist.last_name' => 1);
The where method adds a criterion which returns documents where all or the clauses specified must be truthful in order to return results.
$query->where('agent.office.location$within$center' => [[0,0],10]); # e.g. { "agent.office.location" : { "$within" : { "$center" : [[0,0],10] } } }
The where_exists method adds a criterion which returns documents where the fields specified must all exist in order to return results. The corresponding MongoDB operation is $exists.
$query->where_exists('artist.email_address', 'artist.phone_number'); # e.g. { "artist.email_address" : { "$exists" : true }, "artist.phone_number" : { "$exists" : true } }
Please see http://docs.mongodb.org/manual/reference/operator/exists/ for more information.
The where_not_exists method adds a criterion which returns documents where the fields specified must NOT exist in order to return results. The corresponding MongoDB operation is $exists.
$query->where_not_exists('artist.terminated'); # e.g. { "artist.terminated" : { "$exists" : false } }
Al Newkirk <anewkirk@ana.io>
This software is copyright (c) 2011 by Al Newkirk.
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 MongoDB::QueryBuilder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDB::QueryBuilder
CPAN shell
perl -MCPAN -e shell install MongoDB::QueryBuilder
For more information on module installation, please visit the detailed CPAN module installation guide.