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 To specify joins which describe more than a simple equality of column
129 values, the custom join condition coderef syntax can be used. For
132 My::Schema::Artist->has_many(
133 cds_80s => 'My::Schema::CD',
138 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
139 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
146 $artist_rs->search_related('cds_80s')->next;
148 will result in the C<JOIN> clause:
150 ... FROM artist me LEFT JOIN cd cds_80s ON
151 cds_80s.artist = me.artistid
155 with the bind values:
159 C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
160 same values that would be otherwise substituted for C<foreign> and C<self>
161 in the simple hashref syntax case.
163 The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
164 like what one would supply as the first argument to
165 L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
166 L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
167 clause of the C<JOIN> statement associated with this relationship.
169 While every coderef-based condition must return a valid C<ON> clause, it may
170 elect to additionally return a simplified join-free condition hashref when
171 invoked as C<< $result->relationship >>, as opposed to
172 C<< $rs->related_resultset('relationship') >>. In this case C<$result> is
173 passed to the coderef as C<< $args->{self_rowobj} >>, so a user can do the
181 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
182 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
184 $args->{self_rowobj} && {
185 "$args->{foreign_alias}.artist" => $args->{self_rowobj}->artistid,
186 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
193 my $artist = $schema->resultset("Artist")->find({ id => 4 });
194 $artist->cds_80s->all;
196 Can skip a C<JOIN> altogether and instead produce:
198 SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
200 WHERE cds_80s.artist = ?
204 With the bind values:
208 Note that in order to be able to use
209 L<< $row->create_related|DBIx::Class::Relationship::Base/create_related >>,
210 the coderef must not only return as its second such a "simple" condition
211 hashref which does not depend on joins being available, but the hashref must
212 contain only plain values/deflatable objects, such that the result can be
213 passed directly to L<DBIx::Class::Relationship::Base/set_from_related>. For
214 instance the C<year> constraint in the above example prevents the relationship
215 from being used to to create related objects (an exception will be thrown).
217 In order to allow the user to go truly crazy when generating a custom C<ON>
218 clause, the C<$args> hashref passed to the subroutine contains some extra
219 metadata. Currently the supplied coderef is executed as:
221 $relationship_info->{cond}->({
222 self_alias => The alias of the invoking resultset ('me' in case of a result object),
223 foreign_alias => The alias of the to-be-joined resultset (often matches relname),
224 self_resultsource => The invocant's resultsource,
225 foreign_relname => The relationship name (does *not* always match foreign_alias),
226 self_rowobj => The invocant itself in case of a $result_object->$relationship call
231 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
232 be used as relationship attributes. In particular, the 'where' attribute is
233 useful for filtering relationships:
235 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
236 { 'foreign.user_id' => 'self.user_id' },
237 { where => { valid => 1 } }
240 The following attributes are also valid:
246 Explicitly specifies the type of join to use in the relationship. Any SQL
247 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
248 command immediately before C<JOIN>.
250 =item proxy =E<gt> $column | \@columns | \%column
252 The 'proxy' attribute can be used to retrieve values, and to perform
253 updates if the relationship has 'cascade_update' set. The 'might_have'
254 and 'has_one' relationships have this set by default; if you want a proxy
255 to update across a 'belongs_to' relationship, you must set the attribute
262 An arrayref containing a list of accessors in the foreign class to create in
263 the main class. If, for example, you do the following:
265 MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
267 proxy => [ qw/notes/ ],
270 Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
272 my $cd = MyApp::Schema::CD->find(1);
273 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
274 # created if it doesn't exist
276 For a 'belongs_to relationship, note the 'cascade_update':
278 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd,
279 { proxy => ['title'], cascade_update => 1 }
281 $track->title('New Title');
282 $track->update; # updates title in CD
286 A hashref where each key is the accessor you want installed in the main class,
287 and its value is the name of the original in the fireign class.
289 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
290 proxy => { cd_title => 'title' },
293 This will create an accessor named C<cd_title> on the C<$track> result object.
297 NOTE: you can pass a nested struct too, for example:
299 MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
300 proxy => [ 'year', { cd_title => 'title' } ],
305 Specifies the type of accessor that should be created for the relationship.
306 Valid values are C<single> (for when there is only a single related object),
307 C<multi> (when there can be many), and C<filter> (for when there is a single
308 related object, but you also want the relationship accessor to double as
309 a column accessor). For C<multi> accessors, an add_to_* method is also
310 created, which calls C<create_related> for the relationship.
312 =item is_foreign_key_constraint
314 If you are using L<SQL::Translator> to create SQL for you and you find that it
315 is creating constraints where it shouldn't, or not creating them where it
316 should, set this attribute to a true or false value to override the detection
317 of when to create constraints.
321 If C<cascade_copy> is true on a C<has_many> relationship for an
322 object, then when you copy the object all the related objects will
323 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
324 in the C<$attr> hashref.
326 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
331 By default, DBIx::Class cascades deletes across C<has_many>,
332 C<has_one> and C<might_have> relationships. You can disable this
333 behaviour on a per-relationship basis by supplying
334 C<< cascade_delete => 0 >> in the relationship attributes.
336 The cascaded operations are performed after the requested delete,
337 so if your database has a constraint on the relationship, it will
338 have deleted/updated the related records or raised an exception
339 before DBIx::Class gets to perform the cascaded operation.
343 By default, DBIx::Class cascades updates across C<has_one> and
344 C<might_have> relationships. You can disable this behaviour on a
345 per-relationship basis by supplying C<< cascade_update => 0 >> in
346 the relationship attributes.
348 The C<belongs_to> relationship does not update across relationships
349 by default, so if you have a 'proxy' attribute on a belongs_to and want to
350 use 'update' on it, you muse set C<< cascade_update => 1 >>.
352 This is not a RDMS style cascade update - it purely means that when
353 an object has update called on it, all the related objects also
354 have update called. It will not change foreign keys automatically -
355 you must arrange to do this yourself.
357 =item on_delete / on_update
359 If you are using L<SQL::Translator> to create SQL for you, you can use these
360 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
361 type. If not supplied the SQLT parser will attempt to infer the constraint type by
362 interrogating the attributes of the B<opposite> relationship. For any 'multi'
363 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
364 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
365 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
366 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
367 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
368 C<< on_delete => '' >>, and the same for C<on_update> respectively.
372 Tells L<SQL::Translator> that the foreign key constraint it creates should be
373 deferrable. In other words, the user may request that the constraint be ignored
374 until the end of the transaction. Currently, only the PostgreSQL producer
375 actually supports this.
379 Tells L<SQL::Translator> to add an index for this constraint. Can also be
380 specified globally in the args to L<DBIx::Class::Schema/deploy> or
381 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
385 =head2 register_relationship
389 =item Arguments: $rel_name, $rel_info
393 Registers a relationship on the class. This is called internally by
394 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
398 sub register_relationship { }
400 =head2 related_resultset
404 =item Arguments: $rel_name
406 =item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
410 $rs = $cd->related_resultset('artist');
412 Returns a L<DBIx::Class::ResultSet> for the relationship named
415 =head2 $relationship_accessor
419 =item Arguments: none
421 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
425 # These pairs do the same thing
426 $row = $cd->related_resultset('artist')->single; # has_one relationship
428 $rs = $cd->related_resultset('tracks'); # has_many relationship
431 This is the recommended way to traverse through relationships, based
432 on the L</accessor> name given in the relationship definition.
434 This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
435 L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
436 C<single> (returns only one row) or C<multi> (returns many rows). The
437 method may also return C<undef> if the relationship doesn't exist for
438 this instance (like in the case of C<might_have> relationships).
442 sub related_resultset {
444 $self->throw_exception("Can't call *_related as class methods")
447 my $rel_info = $self->relationship_info($rel);
448 $self->throw_exception( "No such relationship '$rel'" )
451 return $self->{related_resultsets}{$rel} ||= do {
452 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
453 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
455 $self->throw_exception( "Invalid query: @_" )
456 if (@_ > 1 && (@_ % 2 == 1));
457 my $query = ((@_ > 1) ? {@_} : shift);
459 my $source = $self->result_source;
461 # condition resolution may fail if an incomplete master-object prefetch
462 # is encountered - that is ok during prefetch construction (not yet in_storage)
463 my ($cond, $is_crosstable) = try {
464 $source->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel )
467 if ($self->in_storage) {
468 $self->throw_exception ($_);
471 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
474 # keep in mind that the following if() block is part of a do{} - no return()s!!!
475 if ($is_crosstable) {
476 $self->throw_exception (
477 "A cross-table relationship condition returned for statically declared '$rel'"
478 ) unless ref $rel_info->{cond} eq 'CODE';
480 # A WHOREIFFIC hack to reinvoke the entire condition resolution
481 # with the correct alias. Another way of doing this involves a
482 # lot of state passing around, and the @_ positions are already
483 # mapped out, making this crap a less icky option.
485 # The point of this exercise is to retain the spirit of the original
486 # $obj->search_related($rel) where the resulting rset will have the
487 # root alias as 'me', instead of $rel (as opposed to invoking
488 # $rs->search_related)
490 local $source->{_relationships}{me} = $source->{_relationships}{$rel}; # make the fake 'me' rel
491 my $obj_table_alias = lc($source->source_name) . '__row';
492 $obj_table_alias =~ s/\W+/_/g;
494 $source->resultset->search(
495 $self->ident_condition($obj_table_alias),
496 { alias => $obj_table_alias },
497 )->search_related('me', $query, $attrs)
500 # FIXME - this conditional doesn't seem correct - got to figure out
501 # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
502 # business seems shady - we could simply not query *at all*
503 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
504 my $reverse = $source->reverse_relationship_info($rel);
505 foreach my $rev_rel (keys %$reverse) {
506 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
507 weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
509 weaken($attrs->{related_objects}{$rev_rel} = $self);
513 elsif (ref $cond eq 'ARRAY') {
515 if (ref $_ eq 'HASH') {
517 foreach my $key (keys %$_) {
518 my $newkey = $key !~ /\./ ? "me.$key" : $key;
519 $hash->{$newkey} = $_->{$key};
527 elsif (ref $cond eq 'HASH') {
528 foreach my $key (grep { ! /\./ } keys %$cond) {
529 $cond->{"me.$key"} = delete $cond->{$key};
533 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
534 $self->result_source->related_source($rel)->resultset->search(
541 =head2 search_related
545 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
547 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
551 Run a search on a related resultset. The search will be restricted to the
552 results represented by the L<DBIx::Class::ResultSet> it was called
555 See L<DBIx::Class::ResultSet/search_related> for more information.
560 return shift->related_resultset(shift)->search(@_);
563 =head2 search_related_rs
565 This method works exactly the same as search_related, except that
566 it guarantees a resultset, even in list context.
570 sub search_related_rs {
571 return shift->related_resultset(shift)->search_rs(@_);
578 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
580 =item Return Value: $count
584 Returns the count of all the rows in the related resultset, restricted by the
585 current result or where conditions.
590 shift->search_related(@_)->count;
597 =item Arguments: $rel_name, \%col_data
599 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
603 Create a new result object of the related foreign class. It will magically set
604 any foreign key columns of the new object to the related primary key columns
605 of the source object for you. The newly created result will not be saved into
606 your storage until you call L<DBIx::Class::Row/insert> on it.
611 my ($self, $rel, $values) = @_;
613 # FIXME - this is a bad position for this (also an identical copy in
614 # set_from_related), but I have no saner way to hook, and I absolutely
615 # want this to throw at least for coderefs, instead of the "insert a NULL
616 # when it gets hard" insanity --ribasushi
618 # sanity check - currently throw when a complex coderef rel is encountered
619 # FIXME - should THROW MOAR!
621 if (ref $self) { # cdbi calls this as a class method, /me vomits
623 my $rsrc = $self->result_source;
624 my (undef, $crosstable, $relcols) = $rsrc->_resolve_condition (
625 $rsrc->relationship_info($rel)->{cond}, $rel, $self, $rel
628 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
631 if (@{$relcols || []} and @$relcols = grep { ! exists $values->{$_} } @$relcols) {
632 $self->throw_exception(sprintf (
633 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
635 map { "'$_'" } @$relcols
640 return $self->search_related($rel)->new_result($values);
643 =head2 create_related
647 =item Arguments: $rel_name, \%col_data
649 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
653 my $result = $obj->create_related($rel_name, \%col_data);
655 Creates a new result object, similarly to new_related, and also inserts the
656 result's data into your storage medium. See the distinction between C<create>
657 and C<new> in L<DBIx::Class::ResultSet> for details.
664 my $obj = $self->new_related($rel, @_)->insert;
665 delete $self->{related_resultsets}->{$rel};
673 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
675 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
679 my $result = $obj->find_related($rel_name, \%col_data);
681 Attempt to find a related object using its primary key or unique constraints.
682 See L<DBIx::Class::ResultSet/find> for details.
687 #my ($self, $rel, @args) = @_;
688 return shift->search_related(shift)->find(@_);
691 =head2 find_or_new_related
695 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
697 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
701 Find a result object of a related class. See L<DBIx::Class::ResultSet/find_or_new>
706 sub find_or_new_related {
708 my $obj = $self->find_related(@_);
709 return defined $obj ? $obj : $self->new_related(@_);
712 =head2 find_or_create_related
716 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
718 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
722 Find or create a result object of a related class. See
723 L<DBIx::Class::ResultSet/find_or_create> for details.
727 sub find_or_create_related {
729 my $obj = $self->find_related(@_);
730 return (defined($obj) ? $obj : $self->create_related(@_));
733 =head2 update_or_create_related
737 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
739 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
743 Update or create a result object of a related class. See
744 L<DBIx::Class::ResultSet/update_or_create> for details.
748 sub update_or_create_related {
749 #my ($self, $rel, @args) = @_;
750 shift->related_resultset(shift)->update_or_create(@_);
753 =head2 set_from_related
757 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
759 =item Return Value: not defined
763 $book->set_from_related('author', $author_obj);
764 $book->author($author_obj); ## same thing
766 Set column values on the current object, using related values from the given
767 related object. This is used to associate previously separate objects, for
768 example, to set the correct author for a book, find the Author object, then
769 call set_from_related on the book.
771 This is called internally when you pass existing objects as values to
772 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
774 The columns are only set in the local copy of the object, call L</update> to
775 set them in the storage.
779 sub set_from_related {
780 my ($self, $rel, $f_obj) = @_;
782 my $rsrc = $self->result_source;
783 my $rel_info = $rsrc->relationship_info($rel)
784 or $self->throw_exception( "No such relationship '$rel'" );
786 if (defined $f_obj) {
787 my $f_class = $rel_info->{class};
788 $self->throw_exception( "Object '$f_obj' isn't a ".$f_class )
789 unless blessed $f_obj and $f_obj->isa($f_class);
793 # FIXME - this is a bad position for this (also an identical copy in
794 # new_related), but I have no saner way to hook, and I absolutely
795 # want this to throw at least for coderefs, instead of the "insert a NULL
796 # when it gets hard" insanity --ribasushi
798 # sanity check - currently throw when a complex coderef rel is encountered
799 # FIXME - should THROW MOAR!
800 my ($cond, $crosstable, $relcols) = $rsrc->_resolve_condition (
801 $rel_info->{cond}, $f_obj, $rel, $rel
803 $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
805 $self->throw_exception(sprintf (
806 "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
808 map { "'$_'" } @$relcols
809 )) if @{$relcols || []};
811 $self->set_columns($cond);
816 =head2 update_from_related
820 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
822 =item Return Value: not defined
826 $book->update_from_related('author', $author_obj);
828 The same as L</"set_from_related">, but the changes are immediately updated
833 sub update_from_related {
835 $self->set_from_related(@_);
839 =head2 delete_related
843 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
845 =item Return Value: $underlying_storage_rv
849 Delete any related row, subject to the given conditions. Internally, this
852 $self->search_related(@_)->delete
854 And returns the result of that.
860 my $obj = $self->search_related(@_)->delete;
861 delete $self->{related_resultsets}->{$_[0]};
867 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
870 =head3 has_many / multi
874 =item Arguments: \%col_data
876 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
880 Creates/inserts a new result object. Internally, this calls:
882 $self->create_related($rel, @_)
884 And returns the result of that.
890 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
892 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
896 my $role = $schema->resultset('Role')->find(1);
897 $actor->add_to_roles($role);
898 # creates a My::DBIC::Schema::ActorRoles linking table result object
900 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
901 # creates a new My::DBIC::Schema::Role result object and the linking table
902 # object with an extra column in the link
904 Adds a linking table object. If the first argument is a hash reference, the
905 related object is created first with the column values in the hash. If an object
906 reference is given, just the linking table object is created. In either case,
907 any additional column values for the linking table object can be specified in
910 See L<DBIx::Class::Relationship/many_to_many> for additional details.
914 B<Currently only available for C<many_to_many> relationships.>
918 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
920 =item Return Value: not defined
924 my $actor = $schema->resultset('Actor')->find(1);
925 my @roles = $schema->resultset('Role')->search({ role =>
926 { '-in' => ['Fred', 'Barney'] } } );
928 $actor->set_roles(\@roles);
929 # Replaces all of $actor's previous roles with the two named
931 $actor->set_roles(\@roles, { salary => 15_000_000 });
932 # Sets a column in the link table for all roles
935 Replace all the related objects with the given reference to a list of
936 objects. This does a C<delete> B<on the link table resultset> to remove the
937 association between the current object and all related objects, then calls
938 C<add_to_$rel> repeatedly to link all the new objects.
940 Note that this means that this method will B<not> delete any objects in the
941 table on the right side of the relation, merely that it will delete the link
944 Due to a mistake in the original implementation of this method, it will also
945 accept a list of objects or hash references. This is B<deprecated> and will be
946 removed in a future version.
948 =head2 remove_from_$rel
950 B<Currently only available for C<many_to_many> relationships.>
954 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
956 =item Return Value: not defined
960 my $role = $schema->resultset('Role')->find(1);
961 $actor->remove_from_roles($role);
962 # removes $role's My::DBIC::Schema::ActorRoles linking table result object
964 Removes the link between the current object and the related object. Note that
965 the related object itself won't be deleted unless you call ->delete() on
966 it. This method just removes the link between the two objects.
968 =head1 AUTHOR AND CONTRIBUTORS
970 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
974 You may distribute this code under the same terms as Perl itself.