NAME

MongoDB::QueryBuilder - Query Builder for MongoDB

VERSION

version 0.0005

SYNOPSIS

    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};
    }

DESCRIPTION

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.

METHODS

new

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

all_in

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.

and_where

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.

any_in

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.

asc_sort

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');

collection

The collection method provides an accessor for the MongoDB::Collection object used to query the database.

    my $collection = $query->collection($new_collection);

criteria

The criteria method provides an accessor for the query-specification-object used to query the database.

    my $criteria = $query->criteria;

criteria_where

The criteria_where method is a convenience method which provides access to the query-specification where-clause.

    my $criteria = $query->criteria_where

cursor

The cursor method analyzes the current query criteria, generates a MongoDB::Cursor object and queries the databases.

    my $cursor = $query->cursor;

desc_sort

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');

limit

The limit method adds a criterion that instructs the MongoDB::Cursor object to limit the results by the number specified.

    $query->limit(25);

near

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.

never

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');

nor_where

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.

not_in

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.

offset

The offset method adds a criterion that instructs the MongoDB::Cursor object to offset the results by the number specified.

    $query->limit(25);

only

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');

or_where

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.

page

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

sort

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

where

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] } } }

where_exists

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.

where_not_exists

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 } }