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.