/ 
MongoDBI-0.0.4
/ MongoDBI::Document::Storage::Criterion

NAME

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

VERSION

version 0.0.4

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', last_name => 'Teller');

... {
        "last_name" : {
            "$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');

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.