NAME

Meerkat::Collection - Associate a class, database and MongoDB collection

VERSION

version 0.007

SYNOPSIS

    use Meerkat;

    my $meerkat = Meerkat->new(
        model_namespace => "My::Model",
        database_name   => "test"
    );

    my $person = $meerkat->collection("Person"); # My::Model::Person

    # create an object and insert it into the MongoDB collection
    my $obj = $person->create( name => 'John' );

    # find a single object
    my $copy = $person->find_one( { name => 'John' } );

    # get a Meerkat::Cursor for multiple objects
    my $cursor = $person->find( { tag => 'hot' } );

DESCRIPTION

A Meerkat::Collection holds an association between your model class and a collection in the database. This class does all the real work of creating, searching, updating, or deleting from the underlying MongoDB collection.

If you use the Meerkat::Collection object to run a query that could have multiple results, it returns a Meerkat::Cursor object that wraps the MongoDB::Cursor and inflates results into objects from your model.

ATTRIBUTES

meerkat (required)

The Meerkat object that constructed the object. It holds the MongoDB collections used to access the database.

class (required)

The class name to associate with documents. The class is loaded for you if needed.

collection_name

The collection name to associate with the class. Defaults to the name of the class with "::" replaced with "_".

METHODS

create

    my $obj = $person->create( name => 'John' );

Creates an object of the class associated with the Meerkat::Collection and inserts it into the associated collection in the database. Returns the object on success or throws an error on failure.

Any arguments given are passed directly to the associated class constructor. Arguments may be given either as a list or as a hash reference.

count

    my $count = $person->count;
    my $count = $person->count( $query );

Returns the number of documents in the associated collection or throws an error on failure. If a hash reference is provided, it is passed as a query parameter to the MongoDB count method.

find_id

    my $obj = $person->find_id( $id );

Finds a document with the given _id and returns it as an object of the associated class. Returns undef if the _id is not found or throws an error if one occurs. This is a shorthand for the same query via find_one:

    $person->find_one( { _id => $id } );

However, find_id can take either a scalar _id or a MongoDB::OID object as an argument.

find_one

    my $obj = $person->find_one( { name => "Larry Wall" } );

Finds the first document matching a query parameter hash reference and returns it as an object of the associated class. Returns undef if the _id is not found or throws an error if one occurs.

find

    my $cursor = $person->find( { tag => "trendy" } );
    my @objs   = $cursor->all;

Executes a query against collection_name. It returns a Meerkat::Cursor or throws an error on failure. If a hash reference is provided, it is passed as a query parameter to the MongoDB find method, otherwise all documents are returned. Iterating the cursor will return objects of the associated class.

ensure_indexes

    $person->ensure_indexes;

Executes MongoDB's ensure_index for every index returned by the _index method of the associated class. Returns true on success or throws an error if one occurs. See Meerkat::Role::Document for more.

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

cpanm Meerkat

perl -MCPAN -e shell
install Meerkat