NAME

MongoDBI::Document::Storage::Criterion - MongoDBI Chainable Collection Query Builder

VERSION

version 0.0.12

SYNOPSIS

    my $search = MongoDBI::Document::Storage::Criterion->new(
        collection => $mongdb_collection
    );
    
    $search->all_in(...);
    $search->all_of(...);
    $search->also_in(...);
    $search->any_in(...);
    $search->any_of(...);
    $search->asc_sort(...);
    $search->desc_sort(...);
    $search->select(...);
    
    ... etc
    
    my $search = CDDB::Album->search;
       $search = $search->where('released$lt' => DateTime->now->set(...));
       $search = $search->asc_sort('title')->limit(25);
       
    my $mongodb_cursor = $search->query;

DESCRIPTION

MongoDBI::Document::Storage::Criterion provides MongoDBI with a chainable object for building complex and dynamic queries. The querying object will never hit the database until you ask it to.

ATTRIBUTES

collection

The collection attribute is a reference to a MongoDB::Collection object. You will not likely need to access this directly.

criteria

The criteria attribute is a hashref which represents the current query.

METHODS

all_in

The all_in method adds a criterion that specifies values that must all match in order to return results. The corresponding MongoDB operation is $all.

    $search->all_in(aliases => '007', 'Bond');
    
    ... { "aliases" : { "$all" : ['007', 'Bond'] } }

all_of

The all_of method adds a criterion that specifies expressions that must all match in order to return results. The corresponding MongoDB operation is $and.

    $search->all_of('age$gt' => 60, emp_status => 'retired');
    
    ... { "$and" : { "age" : { "$gt" : 60 }, "emp_status" : "retired" } }

and_where

The and_where method wraps and appends the where criterion.

    $search->and_where('age$gte' => 21);
    $search->and_where('age$lte' => 60);
    
    ... { "$and" : [{ "age" : { "$gte" : 21 }, "age" : { "$lte" : 60 } }] }

any_in

The any_in method adds a criterion that specifies values where any value can match in order to return results. The corresponding MongoDB operation is $in.

    $search->any_in(aliases => '007', 'Bond');
    
    ... { "aliases" : { "$in" : ['007', 'Bond'] } }

any_of

The any_of method adds a criterion that specifies a set of expressions that any can match in order to return results. The underlying MongoDB expression is $or.

    $search->any_of(last_name => 'Penn', 'Teller');
    
    ... { "$or" : [{ "last_name" : "Penn" }, { "last_name" : "Teller" }] }

asc_sort

The asc_sort method adds a criterion that instructs the MongoDB::Collection query method to sort the results on specified key in ascending order.

    $search->asc_sort('first_name', 'last_name');

desc_sort

The desc_sort method adds a criterion that instructs the MongoDB::Collection query method to sort the results on specified key in descending order.

    $search->desc_sort('first_name', 'last_name');

foreach_document

The foreach_document method queries the database using the existing criteria and loops incrementally executing the coderef passed foreach document in the resultset. This method will proceed to loop through all the documents in the resultset as long as the passed-in coderef returns a true value.

    my $code = sub {
        my ($row, $self, $cursor) = @_;
        # ...
    };
    
    my $cursor = $search->foreach_document($code);

limit

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

    $search->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 to be on the provided field.

    $search->near(location => [52.30, 13.25]);
    
    ... { "location" : { "$near" : [52.30, 13.25] } }

never

The never method adds a criterion that instructs the MongoDB::Collection query method to select all columns except the ones specified. The opposite of this is the only() method, these two methods can't be used together.

    $search->never('password');

not_in

The not_in method adds a criterion that specifies a set of expressions that cannot match in order to return results. The underlying MongoDB expression is $nin.

    $search->not_in(last_name => ['Teller', 'Penn']);
    
    ... { "last_name" : { "$nin" : ['Teller', 'Penn'] } }

only

The only method adds a criterion that instructs the MongoDB::Collection query method to only select the specified columns. The opposite of this is the never() method, these two methods can't be used together.

    $search->only('first_name', 'last_name', 'login');

or_where

The or_where method wraps and appends the where criterion.

    $search->or_where('age$gte' => 21);
    $search->or_where('age$lte' => 60);
    
    ... { "$or" : [{ "age" : { "$gte" : 21 }, "age" : { "$lte" : 60 } }] }

page

The page method is a purely a convenience method which adds a limit and skip criterion to the query.

    $search->page($limit, $page); # page is optional, defaults to 0

query

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

    my $cursor = $search->query;

skip

The skip method adds a criterion that instructs the MongoDB::Collection query method to limit the results by the number specified.

    $search->skip(2);

sort

The sort method adds a criterion that instructs the MongoDB::Collection query method to sort the results on specified key in the specified order.

    $search->sort(first_name => 1, last_name => -1);

where

The where method wraps and appends the where criterion.

    $search->where('age$gte' => 21);
    $search->where('age$lte' => 60);
    
    ... { "age" : { "$gte" : 21 }, "age" : { "$lte" : 60 } }

where_exists

The where_exists method adds a criterion that specifies fields that must exist in order to return results. The corresponding MongoDB operation is $exists.

    $search->where_exists('mother.name', 'father.name');
    
    ... {
        "mother.name" : { "$exists" : true },
        "father.name" : { "$exists" : true }
    }

where_not_exists

The where_not_exists method adds a criterion that specifies fields that must NOT exist in order to return results. The corresponding MongoDB operation is $exists.

    $search->where_not_exists('mother.name', 'father.name');
    
    ... {
        "mother.name" : { "$exists" : false },
        "father.name" : { "$exists" : false }
    }

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

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.

cpanm MongoDBI

perl -MCPAN -e shell
install MongoDBI