/ 
Meerkat-0.016
River stage one • 1 direct dependent • 1 total dependent
/ Meerkat::Collection

NAME

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

VERSION

version 0.016

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_documents method. Otherwise, the MongoDB estimated_document_count method is used instead.

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 BSON::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. You may include and optional options hash reference after the query hash reference. Iterating the cursor will return objects of the associated class.

ensure_indexes

$person->ensure_indexes;

Ensures an index is constructed for 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