1 package DBIx::Class::Relationship::Base;
6 use base qw/DBIx::Class/;
8 use Scalar::Util qw/weaken blessed/;
14 DBIx::Class::Relationship::Base - Inter-table relationships
18 __PACKAGE__->add_relationship(
19 spiders => 'My::DB::Result::Creatures',
23 "$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" },
24 "$args->{foreign_alias}.type" => 'arachnid'
31 This class provides methods to describe the relationships between the
32 tables in your database model. These are the "bare bones" relationships
33 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
37 =head2 add_relationship
41 =item Arguments: 'relname', 'Foreign::Class', $condition, $attrs
45 __PACKAGE__->add_relationship('relname',
49 Create a custom relationship between one result source and another
50 source, indicated by its class name.
54 The condition argument describes the C<ON> clause of the C<JOIN>
55 expression used to connect the two sources when creating SQL queries.
57 To create simple equality joins, supply a hashref containing the
58 remote table column name as the key(s), and the local table column
59 name as the value(s), for example given:
61 My::Schema::Author->has_many(
62 books => 'My::Schema::Book',
63 { 'foreign.author_id' => 'self.id' }
68 $author_rs->search_related('books')->next
70 will result in the following C<JOIN> clause:
72 ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
74 This describes a relationship between the C<Author> table and the
75 C<Book> table where the C<Book> table has a column C<author_id>
76 containing the ID value of the C<Author>.
78 C<foreign> and C<self> are pseudo aliases and must be entered
79 literally. They will be replaced with the actual correct table alias
80 when the SQL is produced.
84 My::Schema::Book->has_many(
85 editions => 'My::Schema::Edition',
87 'foreign.publisher_id' => 'self.publisher_id',
88 'foreign.type_id' => 'self.type_id',
94 $book_rs->search_related('editions')->next
96 will result in the C<JOIN> clause:
99 LEFT JOIN edition editions ON
100 editions.publisher_id = me.publisher_id
101 AND editions.type_id = me.type_id ...
103 This describes the relationship from C<Book> to C<Edition>, where the
104 C<Edition> table refers to a publisher and a type (e.g. "paperback"):
106 As is the default in L<SQL::Abstract>, the key-value pairs will be
107 C<AND>ed in the result. C<OR> can be achieved with an arrayref, for
108 example a condition like:
110 My::Schema::Item->has_many(
111 related_item_links => My::Schema::Item::Links,
113 { 'foreign.left_itemid' => 'self.id' },
114 { 'foreign.right_itemid' => 'self.id' },
118 will translate to the following C<JOIN> clause:
120 ... FROM item me JOIN item_relations related_item_links ON
121 related_item_links.left_itemid = me.id
122 OR related_item_links.right_itemid = me.id ...
124 This describes the relationship from C<Item> to C<Item::Links>, where
125 C<Item::Links> is a many-to-many linking table, linking items back to
126 themselves in a peer fashion (without a "parent-child" designation)
128 =head4 Custom join conditions (via coderefs)
130 To specify joins which describe more than a simple equality of column
131 values, the custom join condition coderef syntax can be used. For
134 My::Schema::Artist->has_many(
135 cds_80s => 'My::Schema::CD',
140 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
141 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
148 $artist_rs->search_related('cds_80s')->next;
150 will result in the C<JOIN> clause:
152 ... FROM artist me LEFT JOIN cd cds_80s ON
153 cds_80s.artist = me.artistid
157 with the bind values:
161 C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
162 same values that would be otherwise substituted for C<foreign> and C<self>
163 in the simple hashref syntax case.
165 The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
166 like what one would supply as the first argument to
167 L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
168 L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
169 clause of the C<JOIN> statement associated with this relationship.
171 While every coderef-based condition must return a valid C<ON> clause, it may
172 elect to additionally return a simplified join-free condition hashref when
173 invoked as C<< $result->relationship >>, as opposed to
174 C<< $rs->related_resultset('relationship') >>. In this case C<$result> is
175 passed to the coderef as C<< $args->{self_rowobj} >>, so a user can do the
183 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
184 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
186 $args->{self_rowobj} && {
187 "$args->{foreign_alias}.artist" => $args->{self_rowobj}->artistid,
188 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
195 my $artist = $schema->resultset("Artist")->find({ id => 4 });
196 $artist->cds_80s->all;
198 Can skip a C<JOIN> altogether and instead produce:
200 SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
202 WHERE cds_80s.artist = ?
206 With the bind values:
210 Note that in order to be able to use
211 L<< $row->create_related|DBIx::Class::Relationship::Base/create_related >>,
212 the coderef must not only return as its second such a "simple" condition
213 hashref which does not depend on joins being available, but the hashref must
214 contain only plain values/deflatable objects, such that the result can be
215 passed directly to L<DBIx::Class::Relationship::Base/set_from_related>. For
216 instance the C<year> constraint in the above example prevents the relationship
217 from being used to to create related objects (an exception will be thrown).
219 In order to allow the user to go truly crazy when generating a custom C<ON>
220 clause, the C<$args> hashref passed to the subroutine contains some extra
221 metadata. Currently the supplied coderef is executed as:
223 $relationship_info->{cond}->({
224 self_alias => The alias of the invoking resultset ('me' in case of a result object),
225 foreign_alias => The alias of the to-be-joined resultset (often matches relname),
226 self_resultsource => The invocant's resultsource,
227 foreign_relname => The relationship name (does *not* always match foreign_alias),
228 self_rowobj => The invocant itself in case of a $result_object->$relationship call
233 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
234 be used as relationship attributes. In particular, the 'where' attribute is
235 useful for filtering relationships:
237 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
238 { 'foreign.user_id' => 'self.user_id' },
239 { where => { valid => 1 } }
242 The following attributes are also valid:
248 Explicitly specifies the type of join to use in the relationship. Any SQL
249 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
250 command immediately before C<JOIN>.
252 =item proxy =E<gt> $column | \@columns | \%column
254 The 'proxy' attribute can be used to retrieve values, and to perform
255 updates if the relationship has 'cascade_update' set. The 'might_have'
256 and 'has_one' relationships have this set by default; if you want a proxy
257 to update across a 'belongs_to' relationship, you must set the attribute
264 An arrayref containing a list of accessors in the foreign class to create in
265 the main class. If, for example, you do the following:
267 MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
269 proxy => [ qw/notes/ ],
272 Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
274 my $cd = MyApp::Schema::CD->find(1);
275 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
276 # created if it doesn't exist
278 For a 'belongs_to relationship, note the 'cascade_update':
280 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd,
281 { proxy => ['title'], cascade_update => 1 }
283 $track->title('New Title');
284 $track->update; # updates title in CD
288 A hashref where each key is the accessor you want installed in the main class,
289 and its value is the name of the original in the fireign class.
291 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
292 proxy => { cd_title => 'title' },
295 This will create an accessor named C<cd_title> on the C<$track> result object.
299 NOTE: you can pass a nested struct too, for example:
301 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
302 proxy => [ 'year', { cd_title => 'title' } ],
307 Specifies the type of accessor that should be created for the relationship.
308 Valid values are C<single> (for when there is only a single related object),
309 C<multi> (when there can be many), and C<filter> (for when there is a single
310 related object, but you also want the relationship accessor to double as
311 a column accessor). For C<multi> accessors, an add_to_* method is also
312 created, which calls C<create_related> for the relationship.
314 =item is_foreign_key_constraint
316 If you are using L<SQL::Translator> to create SQL for you and you find that it
317 is creating constraints where it shouldn't, or not creating them where it
318 should, set this attribute to a true or false value to override the detection
319 of when to create constraints.
323 If C<cascade_copy> is true on a C<has_many> relationship for an
324 object, then when you copy the object all the related objects will
325 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
326 in the C<$attr> hashref.
328 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
333 By default, L<DBIC|DBIx::Class> cascades deletes across C<has_many>,
334 C<has_one> and C<might_have> relationships. You can disable this
335 behaviour on a per-relationship basis by supplying
336 C<< cascade_delete => 0 >> in the relationship attributes.
338 The cascaded operations are performed after the requested delete,
339 so if your database has a constraint on the relationship, it will
340 have deleted/updated the related records or raised an exception
341 before L<DBIC|DBIx::Class> gets to perform the cascaded operation.
345 By default, L<DBIC|DBIx::Class> cascades updates across C<has_one> and
346 C<might_have> relationships. You can disable this behaviour on a
347 per-relationship basis by supplying C<< cascade_update => 0 >> in
348 the relationship attributes.
350 The C<belongs_to> relationship does not update across relationships
351 by default, so if you have a 'proxy' attribute on a belongs_to and want to
352 use 'update' on it, you muse set C<< cascade_update => 1 >>.
354 This is not a RDMS style cascade update - it purely means that when
355 an object has update called on it, all the related objects also
356 have update called. It will not change foreign keys automatically -
357 you must arrange to do this yourself.
359 =item on_delete / on_update
361 If you are using L<SQL::Translator> to create SQL for you, you can use these
362 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
363 type. If not supplied the SQLT parser will attempt to infer the constraint type by
364 interrogating the attributes of the B<opposite> relationship. For any 'multi'
365 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
366 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
367 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
368 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
369 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
370 C<< on_delete => '' >>, and the same for C<on_update> respectively.
374 Tells L<SQL::Translator> that the foreign key constraint it creates should be
375 deferrable. In other words, the user may request that the constraint be ignored
376 until the end of the transaction. Currently, only the PostgreSQL producer
377 actually supports this.
381 Tells L<SQL::Translator> to add an index for this constraint. Can also be
382 specified globally in the args to L<DBIx::Class::Schema/deploy> or
383 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
387 =head2 register_relationship
391 =item Arguments: $rel_name, $rel_info
395 Registers a relationship on the class. This is called internally by
396 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
400 sub register_relationship { }
402 =head2 related_resultset
406 =item Arguments: $rel_name
408 =item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
412 $rs = $cd->related_resultset('artist');
414 Returns a L<DBIx::Class::ResultSet> for the relationship named
417 =head2 $relationship_accessor
421 =item Arguments: none
423 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
427 # These pairs do the same thing
428 $row = $cd->related_resultset('artist')->single; # has_one relationship
430 $rs = $cd->related_resultset('tracks'); # has_many relationship
433 This is the recommended way to traverse through relationships, based
434 on the L</accessor> name given in the relationship definition.
436 This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
437 L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
438 C<single> (returns only one row) or C<multi> (returns many rows). The
439 method may also return C<undef> if the relationship doesn't exist for
440 this instance (like in the case of C<might_have> relationships).
444 sub related_resultset {
446 $self->throw_exception("Can't call *_related as class methods")
449 my $rel_info = $self->relationship_info($rel);
450 $self->throw_exception( "No such relationship '$rel'" )
453 return $self->{related_resultsets}{$rel} ||= do {
454 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
455 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
457 $self->throw_exception( "Invalid query: @_" )
458 if (@_ > 1 && (@_ % 2 == 1));
459 my $query = ((@_ > 1) ? {@_} : shift);
461 my $source = $self->result_source;
463 # condition resolution may fail if an incomplete master-object prefetch
464 # is encountered - that is ok during prefetch construction (not yet in_storage)
465 my ($cond, $is_crosstable) = try {
466 $source->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel )
469 if ($self->in_storage) {
470 $self->throw_exception ($_);
473 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
476 # keep in mind that the following if() block is part of a do{} - no return()s!!!
477 if ($is_crosstable) {
478 $self->throw_exception (
479 "A cross-table relationship condition returned for statically declared '$rel'"
480 ) unless ref $rel_info->{cond} eq 'CODE';
482 # A WHOREIFFIC hack to reinvoke the entire condition resolution
483 # with the correct alias. Another way of doing this involves a
484 # lot of state passing around, and the @_ positions are already
485 # mapped out, making this crap a less icky option.
487 # The point of this exercise is to retain the spirit of the original
488 # $obj->search_related($rel) where the resulting rset will have the
489 # root alias as 'me', instead of $rel (as opposed to invoking
490 # $rs->search_related)
492 local $source->{_relationships}{me} = $source->{_relationships}{$rel}; # make the fake 'me' rel
493 my $obj_table_alias = lc($source->source_name) . '__row';
494 $obj_table_alias =~ s/\W+/_/g;
496 $source->resultset->search(
497 $self->ident_condition($obj_table_alias),
498 { alias => $obj_table_alias },
499 )->search_related('me', $query, $attrs)
502 # FIXME - this conditional doesn't seem correct - got to figure out
503 # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
504 # business seems shady - we could simply not query *at all*
505 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
506 my $reverse = $source->reverse_relationship_info($rel);
507 foreach my $rev_rel (keys %$reverse) {
508 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
509 weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
511 weaken($attrs->{related_objects}{$rev_rel} = $self);
515 elsif (ref $cond eq 'ARRAY') {
517 if (ref $_ eq 'HASH') {
519 foreach my $key (keys %$_) {
520 my $newkey = $key !~ /\./ ? "me.$key" : $key;
521 $hash->{$newkey} = $_->{$key};
529 elsif (ref $cond eq 'HASH') {
530 foreach my $key (grep { ! /\./ } keys %$cond) {
531 $cond->{"me.$key"} = delete $cond->{$key};
535 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
536 $self->result_source->related_source($rel)->resultset->search(
543 =head2 search_related
547 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
549 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
553 Run a search on a related resultset. The search will be restricted to the
554 results represented by the L<DBIx::Class::ResultSet> it was called
557 See L<DBIx::Class::ResultSet/search_related> for more information.
562 return shift->related_resultset(shift)->search(@_);
565 =head2 search_related_rs
567 This method works exactly the same as search_related, except that
568 it guarantees a resultset, even in list context.
572 sub search_related_rs {
573 return shift->related_resultset(shift)->search_rs(@_);
580 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
582 =item Return Value: $count
586 Returns the count of all the rows in the related resultset, restricted by the
587 current result or where conditions.
592 shift->search_related(@_)->count;
599 =item Arguments: $rel_name, \%col_data
601 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
605 Create a new result object of the related foreign class. It will magically set
606 any foreign key columns of the new object to the related primary key columns
607 of the source object for you. The newly created result will not be saved into
608 your storage until you call L<DBIx::Class::Row/insert> on it.
613 my ($self, $rel, $values) = @_;
615 # FIXME - this is a bad position for this (also an identical copy in
616 # set_from_related), but I have no saner way to hook, and I absolutely
617 # want this to throw at least for coderefs, instead of the "insert a NULL
618 # when it gets hard" insanity --ribasushi
620 # sanity check - currently throw when a complex coderef rel is encountered
621 # FIXME - should THROW MOAR!
623 if (ref $self) { # cdbi calls this as a class method, /me vomits
625 my $rsrc = $self->result_source;
626 my (undef, $crosstable, $relcols) = $rsrc->_resolve_condition (
627 $rsrc->relationship_info($rel)->{cond}, $rel, $self, $rel
630 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
633 if (@{$relcols || []} and @$relcols = grep { ! exists $values->{$_} } @$relcols) {
634 $self->throw_exception(sprintf (
635 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
637 map { "'$_'" } @$relcols
642 return $self->search_related($rel)->new_result($values);
645 =head2 create_related
649 =item Arguments: $rel_name, \%col_data
651 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
655 my $result = $obj->create_related($rel_name, \%col_data);
657 Creates a new result object, similarly to new_related, and also inserts the
658 result's data into your storage medium. See the distinction between C<create>
659 and C<new> in L<DBIx::Class::ResultSet> for details.
666 my $obj = $self->new_related($rel, @_)->insert;
667 delete $self->{related_resultsets}->{$rel};
675 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
677 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
681 my $result = $obj->find_related($rel_name, \%col_data);
683 Attempt to find a related object using its primary key or unique constraints.
684 See L<DBIx::Class::ResultSet/find> for details.
689 #my ($self, $rel, @args) = @_;
690 return shift->search_related(shift)->find(@_);
693 =head2 find_or_new_related
697 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
699 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
703 Find a result object of a related class. See L<DBIx::Class::ResultSet/find_or_new>
708 sub find_or_new_related {
710 my $obj = $self->find_related(@_);
711 return defined $obj ? $obj : $self->new_related(@_);
714 =head2 find_or_create_related
718 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
720 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
724 Find or create a result object of a related class. See
725 L<DBIx::Class::ResultSet/find_or_create> for details.
729 sub find_or_create_related {
731 my $obj = $self->find_related(@_);
732 return (defined($obj) ? $obj : $self->create_related(@_));
735 =head2 update_or_create_related
739 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
741 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
745 Update or create a result object of a related class. See
746 L<DBIx::Class::ResultSet/update_or_create> for details.
750 sub update_or_create_related {
751 #my ($self, $rel, @args) = @_;
752 shift->related_resultset(shift)->update_or_create(@_);
755 =head2 set_from_related
759 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
761 =item Return Value: not defined
765 $book->set_from_related('author', $author_obj);
766 $book->author($author_obj); ## same thing
768 Set column values on the current object, using related values from the given
769 related object. This is used to associate previously separate objects, for
770 example, to set the correct author for a book, find the Author object, then
771 call set_from_related on the book.
773 This is called internally when you pass existing objects as values to
774 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
776 The columns are only set in the local copy of the object, call L</update> to
777 set them in the storage.
781 sub set_from_related {
782 my ($self, $rel, $f_obj) = @_;
784 my $rsrc = $self->result_source;
785 my $rel_info = $rsrc->relationship_info($rel)
786 or $self->throw_exception( "No such relationship '$rel'" );
788 if (defined $f_obj) {
789 my $f_class = $rel_info->{class};
790 $self->throw_exception( "Object '$f_obj' isn't a ".$f_class )
791 unless blessed $f_obj and $f_obj->isa($f_class);
795 # FIXME - this is a bad position for this (also an identical copy in
796 # new_related), but I have no saner way to hook, and I absolutely
797 # want this to throw at least for coderefs, instead of the "insert a NULL
798 # when it gets hard" insanity --ribasushi
800 # sanity check - currently throw when a complex coderef rel is encountered
801 # FIXME - should THROW MOAR!
802 my ($cond, $crosstable, $relcols) = $rsrc->_resolve_condition (
803 $rel_info->{cond}, $f_obj, $rel, $rel
805 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
807 $self->throw_exception(sprintf (
808 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
810 map { "'$_'" } @$relcols
811 )) if @{$relcols || []};
813 $self->set_columns($cond);
818 =head2 update_from_related
822 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
824 =item Return Value: not defined
828 $book->update_from_related('author', $author_obj);
830 The same as L</"set_from_related">, but the changes are immediately updated
835 sub update_from_related {
837 $self->set_from_related(@_);
841 =head2 delete_related
845 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
847 =item Return Value: $underlying_storage_rv
851 Delete any related row, subject to the given conditions. Internally, this
854 $self->search_related(@_)->delete
856 And returns the result of that.
862 my $obj = $self->search_related(@_)->delete;
863 delete $self->{related_resultsets}->{$_[0]};
869 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
872 =head3 has_many / multi
876 =item Arguments: \%col_data
878 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
882 Creates/inserts a new result object. Internally, this calls:
884 $self->create_related($rel, @_)
886 And returns the result of that.
892 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
894 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
898 my $role = $schema->resultset('Role')->find(1);
899 $actor->add_to_roles($role);
900 # creates a My::DBIC::Schema::ActorRoles linking table result object
902 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
903 # creates a new My::DBIC::Schema::Role result object and the linking table
904 # object with an extra column in the link
906 Adds a linking table object. If the first argument is a hash reference, the
907 related object is created first with the column values in the hash. If an object
908 reference is given, just the linking table object is created. In either case,
909 any additional column values for the linking table object can be specified in
912 See L<DBIx::Class::Relationship/many_to_many> for additional details.
916 B<Currently only available for C<many_to_many> relationships.>
920 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
922 =item Return Value: not defined
926 my $actor = $schema->resultset('Actor')->find(1);
927 my @roles = $schema->resultset('Role')->search({ role =>
928 { '-in' => ['Fred', 'Barney'] } } );
930 $actor->set_roles(\@roles);
931 # Replaces all of $actor's previous roles with the two named
933 $actor->set_roles(\@roles, { salary => 15_000_000 });
934 # Sets a column in the link table for all roles
937 Replace all the related objects with the given reference to a list of
938 objects. This does a C<delete> B<on the link table resultset> to remove the
939 association between the current object and all related objects, then calls
940 C<add_to_$rel> repeatedly to link all the new objects.
942 Note that this means that this method will B<not> delete any objects in the
943 table on the right side of the relation, merely that it will delete the link
946 Due to a mistake in the original implementation of this method, it will also
947 accept a list of objects or hash references. This is B<deprecated> and will be
948 removed in a future version.
950 =head2 remove_from_$rel
952 B<Currently only available for C<many_to_many> relationships.>
956 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
958 =item Return Value: not defined
962 my $role = $schema->resultset('Role')->find(1);
963 $actor->remove_from_roles($role);
964 # removes $role's My::DBIC::Schema::ActorRoles linking table result object
966 Removes the link between the current object and the related object. Note that
967 the related object itself won't be deleted unless you call ->delete() on
968 it. This method just removes the link between the two objects.
970 =head1 AUTHOR AND CONTRIBUTORS
972 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
976 You may distribute this code under the same terms as Perl itself.