NAME

Mongoose::Join - simple class relationship resolver

SYNOPSIS

    package Author;
    use Moose;
    with 'Mongoose::Document';
    has 'articles' => (
        is      => 'rw',
        isa     => 'Mongoose::Join[Article]',
        default => sub { Mongoose::Join->new( with_class => 'Article' ) }
    );

DESCRIPTION

This module can be used to establish relationships between two "Mongoose::Document" classes. It should not be used with "Mongoose::EmbeddedDocument" classes.

All object relationships are stored as reference $id arrays into the parent object. This translates into a slight performance hit when loading the parent class, but not as much as loading all objects at one as when using an "ArrayRef".

Attention: the relationship attribute needs to be initialized to an instance of "Mongoose::Join" before it can be used.

Mongoose::Class

Take a look at Mongoose::Class, it has nice syntatic sugar that does most of the initialization behind the scenes for you.

METHODS

add

Add (join) a Mongoose::Document object for later saving.

Saving the parent Mongoose::Document will save both.

    my $author = Author->new;
    $author->articles->add( Article->new );
    $author->save; # saves all objects

remove

Delete from the relationship list.

    my $author = Author->find_one;
    my $first_article = $author->articles->find_one;
    $author->articles->remove( $first_article );

find

Run a MongoDB "find" on the joint collection.

    # searches for articles belonging to this collection
    my $cursor = $author->articles->find({ title=>'foo article' });
    while( my $article = $cursor->next ) {
        ...
    }

Returns a Mongoose::Cursor.

count

Count relations.

find_one

Just like find, but returns the first row found.

first

Alias to "find_one"

    $first_cd = $artist->cds->first;

all

Same as "find", but returns an ARRAY with all the results, instead of a cursor.

    my @cds = $artist->cds->all;

hash_on

Same as "all", but returns a HASH instead of an ARRAY. The hash will be indexed by the key name sent as the first parameter. The hash value contains exactly one object. In case duplicate rows with the same key value are found, the resulting hash will contain the first one found.

    # ie. returns $cds{'111888888292adf0000003'} = <CD Object>;
    my %cds = $artist->cds->hash_on( '_id' => { artist=>'Joe' });

    # ie. returns $joe_cds{'Title1'} = <CD Object>;
    my %joe_cds = $artist->cds->hash_on( 'title' => { artist=>qr/Joe/ });

hash_array

Similar to "hash_on", but returns a hash with ALL rows found, grouped by the key.

    # ie. returns $cds{'Title1'} = [ <CD1 Object>, <CD2 Object>, ... ];
    my %cds = $artist->cds->hash_array( 'title' => { artist=>'Joe' });

Hash values are ARRAYREFs with 1 or more rows.