1 package DBIx::Class::Relationship::Base;
6 use base qw/DBIx::Class/;
8 use Scalar::Util qw/weaken blessed/;
10 use DBIx::Class::_Util 'UNRESOLVABLE_CONDITION';
15 DBIx::Class::Relationship::Base - Inter-table relationships
19 __PACKAGE__->add_relationship(
20 spiders => 'My::DB::Result::Creatures',
24 "$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" },
25 "$args->{foreign_alias}.type" => 'arachnid'
32 This class provides methods to describe the relationships between the
33 tables in your database model. These are the "bare bones" relationships
34 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
38 =head2 add_relationship
42 =item Arguments: $rel_name, $foreign_class, $condition, $attrs
46 __PACKAGE__->add_relationship('rel_name',
50 Create a custom relationship between one result source and another
51 source, indicated by its class name.
55 The condition argument describes the C<ON> clause of the C<JOIN>
56 expression used to connect the two sources when creating SQL queries.
58 =head4 Simple equality
60 To create simple equality joins, supply a hashref containing the remote
61 table column name as the key(s) prefixed by C<'foreign.'>, and the
62 corresponding local table column name as the value(s) prefixed by C<'self.'>.
63 Both C<foreign> and C<self> are pseudo aliases and must be entered
64 literally. They will be replaced with the actual correct table alias
65 when the SQL is produced.
69 My::Schema::Author->has_many(
70 books => 'My::Schema::Book',
71 { 'foreign.author_id' => 'self.id' }
76 $author_rs->search_related('books')->next
78 will result in the following C<JOIN> clause:
80 ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
82 This describes a relationship between the C<Author> table and the
83 C<Book> table where the C<Book> table has a column C<author_id>
84 containing the ID value of the C<Author>.
88 My::Schema::Book->has_many(
89 editions => 'My::Schema::Edition',
91 'foreign.publisher_id' => 'self.publisher_id',
92 'foreign.type_id' => 'self.type_id',
98 $book_rs->search_related('editions')->next
100 will result in the C<JOIN> clause:
103 LEFT JOIN edition editions ON
104 editions.publisher_id = me.publisher_id
105 AND editions.type_id = me.type_id ...
107 This describes the relationship from C<Book> to C<Edition>, where the
108 C<Edition> table refers to a publisher and a type (e.g. "paperback"):
110 =head4 Multiple groups of simple equality conditions
112 As is the default in L<SQL::Abstract>, the key-value pairs will be
113 C<AND>ed in the resulting C<JOIN> clause. An C<OR> can be achieved with
114 an arrayref. For example a condition like:
116 My::Schema::Item->has_many(
117 related_item_links => My::Schema::Item::Links,
119 { 'foreign.left_itemid' => 'self.id' },
120 { 'foreign.right_itemid' => 'self.id' },
124 will translate to the following C<JOIN> clause:
126 ... FROM item me JOIN item_relations related_item_links ON
127 related_item_links.left_itemid = me.id
128 OR related_item_links.right_itemid = me.id ...
130 This describes the relationship from C<Item> to C<Item::Links>, where
131 C<Item::Links> is a many-to-many linking table, linking items back to
132 themselves in a peer fashion (without a "parent-child" designation)
134 =head4 Custom join conditions
136 NOTE: The custom join condition specification mechanism is capable of
137 generating JOIN clauses of virtually unlimited complexity. This may limit
138 your ability to traverse some of the more involved relationship chains the
139 way you expect, *and* may bring your RDBMS to its knees. Exercise care
140 when declaring relationships as described here.
142 To specify joins which describe more than a simple equality of column
143 values, the custom join condition coderef syntax can be used. For
146 My::Schema::Artist->has_many(
147 cds_80s => 'My::Schema::CD',
152 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
153 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
160 $artist_rs->search_related('cds_80s')->next;
162 will result in the C<JOIN> clause:
164 ... FROM artist me LEFT JOIN cd cds_80s ON
165 cds_80s.artist = me.artistid
169 with the bind values:
173 C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
174 same values that would be otherwise substituted for C<foreign> and C<self>
175 in the simple hashref syntax case.
177 The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
178 like what one would supply as the first argument to
179 L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
180 L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
181 clause of the C<JOIN> statement associated with this relationship.
183 While every coderef-based condition must return a valid C<ON> clause, it may
184 elect to additionally return a simplified B<optional> join-free condition
185 consisting of a hashref with B<all keys being fully qualified names of columns
186 declared on the corresponding result source>. This boils down to two scenarios:
192 When relationship resolution is invoked after C<< $result->$rel_name >>, as
193 opposed to C<< $rs->related_resultset($rel_name) >>, the C<$result> object
194 is passed to the coderef as C<< $args->{self_result_object} >>.
198 Alternatively when the user-space invokes resolution via
199 C<< $result->set_from_related( $rel_name => $foreign_values_or_object ) >>, the
200 corresponding data is passed to the coderef as C<< $args->{foreign_values} >>,
201 B<always> in the form of a hashref. If a foreign result object is supplied
202 (which is valid usage of L</set_from_related>), its values will be extracted
203 into hashref form by calling L<get_columns|DBIx::Class::Row/get_columns>.
207 Note that the above scenarios are mutually exclusive, that is you will be supplied
208 none or only one of C<self_result_object> and C<foreign_values>. In other words if
209 you define your condition coderef as:
216 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
217 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
219 ! $args->{self_result_object} ? () : {
220 "$args->{foreign_alias}.artist" => $args->{self_result_object}->artistid,
221 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
223 ! $args->{foreign_values} ? () : {
224 "$args->{self_alias}.artistid" => $args->{foreign_values}{artist},
231 my $artist = $schema->resultset("Artist")->find({ id => 4 });
232 $artist->cds_80s->all;
234 Can skip a C<JOIN> altogether and instead produce:
236 SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
238 WHERE cds_80s.artist = ?
242 With the bind values:
248 my $cd = $schema->resultset("CD")->search({ artist => 1 }, { rows => 1 })->single;
249 my $artist = $schema->resultset("Artist")->new({});
250 $artist->set_from_related('cds_80s');
252 Will properly set the C<< $artist->artistid >> field of this new object to C<1>
254 Note that in order to be able to use L</set_from_related> (and by extension
255 L<< $result->create_related|DBIx::Class::Relationship::Base/create_related >>),
256 the returned join free condition B<must> contain only plain values/deflatable
257 objects. For instance the C<year> constraint in the above example prevents
258 the relationship from being used to create related objects using
259 C<< $artst->create_related( cds_80s => { title => 'blah' } ) >> (an
260 exception will be thrown).
262 In order to allow the user to go truly crazy when generating a custom C<ON>
263 clause, the C<$args> hashref passed to the subroutine contains some extra
264 metadata. Currently the supplied coderef is executed as:
266 $relationship_info->{cond}->({
267 self_resultsource => The resultsource instance on which rel_name is registered
268 rel_name => The relationship name (does *NOT* always match foreign_alias)
270 self_alias => The alias of the invoking resultset
271 foreign_alias => The alias of the to-be-joined resultset (does *NOT* always match rel_name)
273 # only one of these (or none at all) will ever be supplied to aid in the
274 # construction of a join-free condition
276 self_result_object => The invocant *object* itself in case of a call like
277 $result_object->$rel_name( ... )
279 foreign_values => A *hashref* of related data: may be passed in directly or
280 derived via ->get_columns() from a related object in case of
281 $result_object->set_from_related( $rel_name, $foreign_result_object )
283 # deprecated inconsistent names, will be forever available for legacy code
284 self_rowobj => Old deprecated slot for self_result_object
285 foreign_relname => Old deprecated slot for rel_name
290 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
291 be used as relationship attributes. In particular, the 'where' attribute is
292 useful for filtering relationships:
294 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
295 { 'foreign.user_id' => 'self.user_id' },
296 { where => { valid => 1 } }
299 The following attributes are also valid:
305 Explicitly specifies the type of join to use in the relationship. Any SQL
306 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
307 command immediately before C<JOIN>.
309 =item proxy =E<gt> $column | \@columns | \%column
311 The 'proxy' attribute can be used to retrieve values, and to perform
312 updates if the relationship has 'cascade_update' set. The 'might_have'
313 and 'has_one' relationships have this set by default; if you want a proxy
314 to update across a 'belongs_to' relationship, you must set the attribute
321 An arrayref containing a list of accessors in the foreign class to create in
322 the main class. If, for example, you do the following:
324 MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
326 proxy => [ qw/notes/ ],
329 Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
331 my $cd = MyApp::Schema::CD->find(1);
332 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
333 # created if it doesn't exist
335 For a 'belongs_to relationship, note the 'cascade_update':
337 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
338 { proxy => ['title'], cascade_update => 1 }
340 $track->title('New Title');
341 $track->update; # updates title in CD
345 A hashref where each key is the accessor you want installed in the main class,
346 and its value is the name of the original in the foreign class.
348 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
349 proxy => { cd_title => 'title' },
352 This will create an accessor named C<cd_title> on the C<$track> result object.
356 NOTE: you can pass a nested struct too, for example:
358 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
359 proxy => [ 'year', { cd_title => 'title' } ],
364 Specifies the type of accessor that should be created for the relationship.
365 Valid values are C<single> (for when there is only a single related object),
366 C<multi> (when there can be many), and C<filter> (for when there is a single
367 related object, but you also want the relationship accessor to double as
368 a column accessor). For C<multi> accessors, an add_to_* method is also
369 created, which calls C<create_related> for the relationship.
371 =item is_foreign_key_constraint
373 If you are using L<SQL::Translator> to create SQL for you and you find that it
374 is creating constraints where it shouldn't, or not creating them where it
375 should, set this attribute to a true or false value to override the detection
376 of when to create constraints.
380 If C<cascade_copy> is true on a C<has_many> relationship for an
381 object, then when you copy the object all the related objects will
382 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
383 in the C<$attr> hashref.
385 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
390 By default, DBIx::Class cascades deletes across C<has_many>,
391 C<has_one> and C<might_have> relationships. You can disable this
392 behaviour on a per-relationship basis by supplying
393 C<< cascade_delete => 0 >> in the relationship attributes.
395 The cascaded operations are performed after the requested delete,
396 so if your database has a constraint on the relationship, it will
397 have deleted/updated the related records or raised an exception
398 before DBIx::Class gets to perform the cascaded operation.
402 By default, DBIx::Class cascades updates across C<has_one> and
403 C<might_have> relationships. You can disable this behaviour on a
404 per-relationship basis by supplying C<< cascade_update => 0 >> in
405 the relationship attributes.
407 The C<belongs_to> relationship does not update across relationships
408 by default, so if you have a 'proxy' attribute on a belongs_to and want to
409 use 'update' on it, you must set C<< cascade_update => 1 >>.
411 This is not a RDMS style cascade update - it purely means that when
412 an object has update called on it, all the related objects also
413 have update called. It will not change foreign keys automatically -
414 you must arrange to do this yourself.
416 =item on_delete / on_update
418 If you are using L<SQL::Translator> to create SQL for you, you can use these
419 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
420 type. If not supplied the SQLT parser will attempt to infer the constraint type by
421 interrogating the attributes of the B<opposite> relationship. For any 'multi'
422 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
423 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
424 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
425 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
426 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
427 C<< on_delete => '' >>, and the same for C<on_update> respectively.
431 Tells L<SQL::Translator> that the foreign key constraint it creates should be
432 deferrable. In other words, the user may request that the constraint be ignored
433 until the end of the transaction. Currently, only the PostgreSQL producer
434 actually supports this.
438 Tells L<SQL::Translator> to add an index for this constraint. Can also be
439 specified globally in the args to L<DBIx::Class::Schema/deploy> or
440 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
444 =head2 register_relationship
448 =item Arguments: $rel_name, $rel_info
452 Registers a relationship on the class. This is called internally by
453 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
457 sub register_relationship { }
459 =head2 related_resultset
463 =item Arguments: $rel_name
465 =item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
469 $rs = $cd->related_resultset('artist');
471 Returns a L<DBIx::Class::ResultSet> for the relationship named
474 =head2 $relationship_accessor
478 =item Arguments: none
480 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
484 # These pairs do the same thing
485 $result = $cd->related_resultset('artist')->single; # has_one relationship
486 $result = $cd->artist;
487 $rs = $cd->related_resultset('tracks'); # has_many relationship
490 This is the recommended way to traverse through relationships, based
491 on the L</accessor> name given in the relationship definition.
493 This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
494 L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
495 C<single> (returns only one row) or C<multi> (returns many rows). The
496 method may also return C<undef> if the relationship doesn't exist for
497 this instance (like in the case of C<might_have> relationships).
501 sub related_resultset {
502 $_[0]->throw_exception(
503 '$result->related_resultset() no longer accepts extra search arguments, '
504 . 'you need to switch to ...->related_resultset($relname)->search_rs(...) '
505 . 'instead (it was never documented and more importantly could never work '
506 . 'reliably due to the heavy caching involved)'
509 $_[0]->throw_exception("Can't call *_related as class methods")
512 return $_[0]->{related_resultsets}{$_[1]}
513 if defined $_[0]->{related_resultsets}{$_[1]};
515 my ($self, $rel) = @_;
517 return $self->{related_resultsets}{$rel} = do {
519 my $rsrc = $self->result_source;
521 my $rel_info = $rsrc->relationship_info($rel)
522 or $self->throw_exception( "No such relationship '$rel'" );
524 my $cond_res = $rsrc->_resolve_relationship_condition(
526 self_result_object => $self,
528 # this may look weird, but remember that we are making a resultset
529 # out of an existing object, with the new source being at the head
530 # of the FROM chain. Having a 'me' alias is nothing but expected there
531 foreign_alias => 'me',
533 self_alias => "!!!\xFF()!!!_SHOULD_NEVER_BE_SEEN_IN_USE_!!!()\xFF!!!",
535 # not strictly necessary, but shouldn't hurt either
536 require_join_free_condition => !!(ref $rel_info->{cond} ne 'CODE'),
539 # keep in mind that the following if() block is part of a do{} - no return()s!!!
541 ! $cond_res->{join_free_condition}
543 ref $rel_info->{cond} eq 'CODE'
546 # A WHOREIFFIC hack to reinvoke the entire condition resolution
547 # with the correct alias. Another way of doing this involves a
548 # lot of state passing around, and the @_ positions are already
549 # mapped out, making this crap a less icky option.
551 # The point of this exercise is to retain the spirit of the original
552 # $obj->search_related($rel) where the resulting rset will have the
553 # root alias as 'me', instead of $rel (as opposed to invoking
554 # $rs->search_related)
556 # make the fake 'me' rel
557 local $rsrc->{_relationships}{me} = {
558 %{ $rsrc->{_relationships}{$rel} },
559 _original_name => $rel,
562 my $obj_table_alias = lc($rsrc->source_name) . '__row';
563 $obj_table_alias =~ s/\W+/_/g;
565 $rsrc->resultset->search(
566 $self->ident_condition($obj_table_alias),
567 { alias => $obj_table_alias },
568 )->search_related('me', undef, $rel_info->{attrs})
572 # FIXME - this conditional doesn't seem correct - got to figure out
573 # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
574 # business seems shady - we could simply not query *at all*
576 if ( $cond_res->{join_free_condition} eq UNRESOLVABLE_CONDITION ) {
577 $attrs = { %{$rel_info->{attrs}} };
578 my $reverse = $rsrc->reverse_relationship_info($rel);
579 foreach my $rev_rel (keys %$reverse) {
580 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
581 weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
583 weaken($attrs->{related_objects}{$rev_rel} = $self);
588 $rsrc->related_source($rel)->resultset->search(
589 $cond_res->{join_free_condition},
590 $attrs || $rel_info->{attrs},
596 =head2 search_related
600 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
602 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
606 Run a search on a related resultset. The search will be restricted to the
607 results represented by the L<DBIx::Class::ResultSet> it was called
610 See L<DBIx::Class::ResultSet/search_related> for more information.
615 return shift->related_resultset(shift)->search(@_);
618 =head2 search_related_rs
620 This method works exactly the same as search_related, except that
621 it guarantees a resultset, even in list context.
625 sub search_related_rs {
626 return shift->related_resultset(shift)->search_rs(@_);
633 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
635 =item Return Value: $count
639 Returns the count of all the rows in the related resultset, restricted by the
640 current result or where conditions.
645 shift->search_related(@_)->count;
652 =item Arguments: $rel_name, \%col_data
654 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
658 Create a new result object of the related foreign class. It will magically set
659 any foreign key columns of the new object to the related primary key columns
660 of the source object for you. The newly created result will not be saved into
661 your storage until you call L<DBIx::Class::Row/insert> on it.
666 my ($self, $rel, $data) = @_;
668 return $self->search_related($rel)->new_result( $self->result_source->_resolve_relationship_condition (
669 infer_values_based_on => $data,
671 self_result_object => $self,
672 foreign_alias => $rel,
674 )->{inferred_values} );
677 =head2 create_related
681 =item Arguments: $rel_name, \%col_data
683 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
687 my $result = $obj->create_related($rel_name, \%col_data);
689 Creates a new result object, similarly to new_related, and also inserts the
690 result's data into your storage medium. See the distinction between C<create>
691 and C<new> in L<DBIx::Class::ResultSet> for details.
698 my $obj = $self->new_related($rel, @_)->insert;
699 delete $self->{related_resultsets}->{$rel};
707 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
709 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
713 my $result = $obj->find_related($rel_name, \%col_data);
715 Attempt to find a related object using its primary key or unique constraints.
716 See L<DBIx::Class::ResultSet/find> for details.
721 #my ($self, $rel, @args) = @_;
722 return shift->search_related(shift)->find(@_);
725 =head2 find_or_new_related
729 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
731 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
735 Find a result object of a related class. See L<DBIx::Class::ResultSet/find_or_new>
740 sub find_or_new_related {
742 my $obj = $self->find_related(@_);
743 return defined $obj ? $obj : $self->new_related(@_);
746 =head2 find_or_create_related
750 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
752 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
756 Find or create a result object of a related class. See
757 L<DBIx::Class::ResultSet/find_or_create> for details.
761 sub find_or_create_related {
763 my $obj = $self->find_related(@_);
764 return (defined($obj) ? $obj : $self->create_related(@_));
767 =head2 update_or_create_related
771 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
773 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
777 Update or create a result object of a related class. See
778 L<DBIx::Class::ResultSet/update_or_create> for details.
782 sub update_or_create_related {
783 #my ($self, $rel, @args) = @_;
784 shift->related_resultset(shift)->update_or_create(@_);
787 =head2 set_from_related
791 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
793 =item Return Value: not defined
797 $book->set_from_related('author', $author_obj);
798 $book->author($author_obj); ## same thing
800 Set column values on the current object, using related values from the given
801 related object. This is used to associate previously separate objects, for
802 example, to set the correct author for a book, find the Author object, then
803 call set_from_related on the book.
805 This is called internally when you pass existing objects as values to
806 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
808 The columns are only set in the local copy of the object, call
809 L<update|DBIx::Class::Row/update> to update them in the storage.
813 sub set_from_related {
814 my ($self, $rel, $f_obj) = @_;
816 $self->set_columns( $self->result_source->_resolve_relationship_condition (
817 infer_values_based_on => {},
819 foreign_values => $f_obj,
820 foreign_alias => $rel,
822 )->{inferred_values} );
827 =head2 update_from_related
831 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
833 =item Return Value: not defined
837 $book->update_from_related('author', $author_obj);
839 The same as L</"set_from_related">, but the changes are immediately updated
844 sub update_from_related {
846 $self->set_from_related(@_);
850 =head2 delete_related
854 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
856 =item Return Value: $underlying_storage_rv
860 Delete any related row, subject to the given conditions. Internally, this
863 $self->search_related(@_)->delete
865 And returns the result of that.
871 my $obj = $self->search_related(@_)->delete;
872 delete $self->{related_resultsets}->{$_[0]};
878 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
881 =head3 has_many / multi
885 =item Arguments: \%col_data
887 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
891 Creates/inserts a new result object. Internally, this calls:
893 $self->create_related($rel, @_)
895 And returns the result of that.
901 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
903 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
907 my $role = $schema->resultset('Role')->find(1);
908 $actor->add_to_roles($role);
909 # creates a My::DBIC::Schema::ActorRoles linking table result object
911 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
912 # creates a new My::DBIC::Schema::Role result object and the linking table
913 # object with an extra column in the link
915 Adds a linking table object. If the first argument is a hash reference, the
916 related object is created first with the column values in the hash. If an object
917 reference is given, just the linking table object is created. In either case,
918 any additional column values for the linking table object can be specified in
921 See L<DBIx::Class::Relationship/many_to_many> for additional details.
925 B<Currently only available for C<many_to_many> relationships.>
929 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
931 =item Return Value: not defined
935 my $actor = $schema->resultset('Actor')->find(1);
936 my @roles = $schema->resultset('Role')->search({ role =>
937 { '-in' => ['Fred', 'Barney'] } } );
939 $actor->set_roles(\@roles);
940 # Replaces all of $actor's previous roles with the two named
942 $actor->set_roles(\@roles, { salary => 15_000_000 });
943 # Sets a column in the link table for all roles
946 Replace all the related objects with the given reference to a list of
947 objects. This does a C<delete> B<on the link table resultset> to remove the
948 association between the current object and all related objects, then calls
949 C<add_to_$rel> repeatedly to link all the new objects.
951 Note that this means that this method will B<not> delete any objects in the
952 table on the right side of the relation, merely that it will delete the link
955 Due to a mistake in the original implementation of this method, it will also
956 accept a list of objects or hash references. This is B<deprecated> and will be
957 removed in a future version.
959 =head2 remove_from_$rel
961 B<Currently only available for C<many_to_many> relationships.>
965 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
967 =item Return Value: not defined
971 my $role = $schema->resultset('Role')->find(1);
972 $actor->remove_from_roles($role);
973 # removes $role's My::DBIC::Schema::ActorRoles linking table result object
975 Removes the link between the current object and the related object. Note that
976 the related object itself won't be deleted unless you call ->delete() on
977 it. This method just removes the link between the two objects.
979 =head1 FURTHER QUESTIONS?
981 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
983 =head1 COPYRIGHT AND LICENSE
985 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
986 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
987 redistribute it and/or modify it under the same terms as the
988 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.