1 package DBIx::Class::Relationship::Base;
6 use base qw/DBIx::Class/;
8 use Scalar::Util qw/weaken blessed/;
9 use DBIx::Class::_Util qw(
10 UNRESOLVABLE_CONDITION DUMMY_ALIASPAIR
13 use DBIx::Class::Carp;
18 DBIx::Class::Relationship::Base - Inter-table relationships
22 __PACKAGE__->add_relationship(
23 spiders => 'My::DB::Result::Creatures',
27 "$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" },
28 "$args->{foreign_alias}.type" => 'arachnid'
35 This class provides methods to describe the relationships between the
36 tables in your database model. These are the "bare bones" relationships
37 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
41 =head2 add_relationship
45 =item Arguments: $rel_name, $foreign_class, $condition, $attrs
49 __PACKAGE__->add_relationship('rel_name',
53 Create a custom relationship between one result source and another
54 source, indicated by its class name.
58 The condition argument describes the C<ON> clause of the C<JOIN>
59 expression used to connect the two sources when creating SQL queries.
61 =head4 Simple equality
63 To create simple equality joins, supply a hashref containing the remote
64 table column name as the key(s) prefixed by C<'foreign.'>, and the
65 corresponding local table column name as the value(s) prefixed by C<'self.'>.
66 Both C<foreign> and C<self> are pseudo aliases and must be entered
67 literally. They will be replaced with the actual correct table alias
68 when the SQL is produced.
72 My::Schema::Author->has_many(
73 books => 'My::Schema::Book',
74 { 'foreign.author_id' => 'self.id' }
79 $author_rs->search_related('books')->next
81 will result in the following C<JOIN> clause:
83 ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
85 This describes a relationship between the C<Author> table and the
86 C<Book> table where the C<Book> table has a column C<author_id>
87 containing the ID value of the C<Author>.
91 My::Schema::Book->has_many(
92 editions => 'My::Schema::Edition',
94 'foreign.publisher_id' => 'self.publisher_id',
95 'foreign.type_id' => 'self.type_id',
101 $book_rs->search_related('editions')->next
103 will result in the C<JOIN> clause:
106 LEFT JOIN edition editions ON
107 editions.publisher_id = me.publisher_id
108 AND editions.type_id = me.type_id ...
110 This describes the relationship from C<Book> to C<Edition>, where the
111 C<Edition> table refers to a publisher and a type (e.g. "paperback"):
113 =head4 Multiple groups of simple equality conditions
115 As is the default in L<SQL::Abstract>, the key-value pairs will be
116 C<AND>ed in the resulting C<JOIN> clause. An C<OR> can be achieved with
117 an arrayref. For example a condition like:
119 My::Schema::Item->has_many(
120 related_item_links => My::Schema::Item::Links,
122 { 'foreign.left_itemid' => 'self.id' },
123 { 'foreign.right_itemid' => 'self.id' },
127 will translate to the following C<JOIN> clause:
129 ... FROM item me JOIN item_relations related_item_links ON
130 related_item_links.left_itemid = me.id
131 OR related_item_links.right_itemid = me.id ...
133 This describes the relationship from C<Item> to C<Item::Links>, where
134 C<Item::Links> is a many-to-many linking table, linking items back to
135 themselves in a peer fashion (without a "parent-child" designation)
137 =head4 Custom join conditions
139 NOTE: The custom join condition specification mechanism is capable of
140 generating JOIN clauses of virtually unlimited complexity. This may limit
141 your ability to traverse some of the more involved relationship chains the
142 way you expect, *and* may bring your RDBMS to its knees. Exercise care
143 when declaring relationships as described here.
145 To specify joins which describe more than a simple equality of column
146 values, the custom join condition coderef syntax can be used. For
149 My::Schema::Artist->has_many(
150 cds_80s => 'My::Schema::CD',
155 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
156 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
163 $artist_rs->search_related('cds_80s')->next;
165 will result in the C<JOIN> clause:
167 ... FROM artist me LEFT JOIN cd cds_80s ON
168 cds_80s.artist = me.artistid
172 with the bind values:
176 C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
177 same values that would be otherwise substituted for C<foreign> and C<self>
178 in the simple hashref syntax case.
180 The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
181 like what one would supply as the first argument to
182 L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
183 L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
184 clause of the C<JOIN> statement associated with this relationship.
186 While every coderef-based condition must return a valid C<ON> clause, it may
187 elect to additionally return a simplified B<optional> join-free condition
188 consisting of a hashref with B<all keys being fully qualified names of columns
189 declared on the corresponding result source>. This boils down to two scenarios:
195 When relationship resolution is invoked after C<< $result->$rel_name >>, as
196 opposed to C<< $rs->related_resultset($rel_name) >>, the C<$result> object
197 is passed to the coderef as C<< $args->{self_result_object} >>.
201 Alternatively when the user-space invokes resolution via
202 C<< $result->set_from_related( $rel_name => $foreign_values_or_object ) >>, the
203 corresponding data is passed to the coderef as C<< $args->{foreign_values} >>,
204 B<always> in the form of a hashref. If a foreign result object is supplied
205 (which is valid usage of L</set_from_related>), its values will be extracted
206 into hashref form by calling L<get_columns|DBIx::Class::Row/get_columns>.
210 Note that the above scenarios are mutually exclusive, that is you will be supplied
211 none or only one of C<self_result_object> and C<foreign_values>. In other words if
212 you define your condition coderef as:
219 "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
220 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
222 ! $args->{self_result_object} ? () : {
223 "$args->{foreign_alias}.artist" => $args->{self_result_object}->artistid,
224 "$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
226 ! $args->{foreign_values} ? () : {
227 "$args->{self_alias}.artistid" => $args->{foreign_values}{artist},
234 my $artist = $schema->resultset("Artist")->find({ id => 4 });
235 $artist->cds_80s->all;
237 Can skip a C<JOIN> altogether and instead produce:
239 SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
241 WHERE cds_80s.artist = ?
245 With the bind values:
251 my $cd = $schema->resultset("CD")->search({ artist => 1 }, { rows => 1 })->single;
252 my $artist = $schema->resultset("Artist")->new({});
253 $artist->set_from_related('cds_80s');
255 Will properly set the C<< $artist->artistid >> field of this new object to C<1>
257 Note that in order to be able to use L</set_from_related> (and by extension
258 L<< $result->create_related|DBIx::Class::Relationship::Base/create_related >>),
259 the returned join free condition B<must> contain only plain values/deflatable
260 objects. For instance the C<year> constraint in the above example prevents
261 the relationship from being used to create related objects using
262 C<< $artst->create_related( cds_80s => { title => 'blah' } ) >> (an
263 exception will be thrown).
265 In order to allow the user to go truly crazy when generating a custom C<ON>
266 clause, the C<$args> hashref passed to the subroutine contains some extra
267 metadata. Currently the supplied coderef is executed as:
269 $relationship_info->{cond}->({
270 self_resultsource => The resultsource instance on which rel_name is registered
271 rel_name => The relationship name (does *NOT* always match foreign_alias)
273 self_alias => The alias of the invoking resultset
274 foreign_alias => The alias of the to-be-joined resultset (does *NOT* always match rel_name)
276 # only one of these (or none at all) will ever be supplied to aid in the
277 # construction of a join-free condition
279 self_result_object => The invocant *object* itself in case of a call like
280 $result_object->$rel_name( ... )
282 foreign_values => A *hashref* of related data: may be passed in directly or
283 derived via ->get_columns() from a related object in case of
284 $result_object->set_from_related( $rel_name, $foreign_result_object )
286 # deprecated inconsistent names, will be forever available for legacy code
287 self_rowobj => Old deprecated slot for self_result_object
288 foreign_relname => Old deprecated slot for rel_name
293 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
294 be used as relationship attributes. In particular, the 'where' attribute is
295 useful for filtering relationships:
297 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
298 { 'foreign.user_id' => 'self.user_id' },
299 { where => { valid => 1 } }
302 The following attributes are also valid:
308 Explicitly specifies the type of join to use in the relationship. Any SQL
309 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
310 command immediately before C<JOIN>.
312 =item proxy =E<gt> $column | \@columns | \%column
314 The 'proxy' attribute can be used to retrieve values, and to perform
315 updates if the relationship has 'cascade_update' set. The 'might_have'
316 and 'has_one' relationships have this set by default; if you want a proxy
317 to update across a 'belongs_to' relationship, you must set the attribute
324 An arrayref containing a list of accessors in the foreign class to create in
325 the main class. If, for example, you do the following:
327 MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
329 proxy => [ qw/notes/ ],
332 Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
334 my $cd = MyApp::Schema::CD->find(1);
335 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
336 # created if it doesn't exist
338 For a 'belongs_to relationship, note the 'cascade_update':
340 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
341 { proxy => ['title'], cascade_update => 1 }
343 $track->title('New Title');
344 $track->update; # updates title in CD
348 A hashref where each key is the accessor you want installed in the main class,
349 and its value is the name of the original in the foreign class.
351 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
352 proxy => { cd_title => 'title' },
355 This will create an accessor named C<cd_title> on the C<$track> result object.
359 NOTE: you can pass a nested struct too, for example:
361 MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
362 proxy => [ 'year', { cd_title => 'title' } ],
367 Specifies the type of accessor that should be created for the relationship.
368 Valid values are C<single> (for when there is only a single related object),
369 C<multi> (when there can be many), and C<filter> (for when there is a single
370 related object, but you also want the relationship accessor to double as
371 a column accessor). For C<multi> accessors, an add_to_* method is also
372 created, which calls C<create_related> for the relationship.
374 =item is_foreign_key_constraint
376 If you are using L<SQL::Translator> to create SQL for you and you find that it
377 is creating constraints where it shouldn't, or not creating them where it
378 should, set this attribute to a true or false value to override the detection
379 of when to create constraints.
383 If C<cascade_copy> is true on a C<has_many> relationship for an
384 object, then when you copy the object all the related objects will
385 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
386 in the C<$attr> hashref.
388 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
393 By default, DBIx::Class cascades deletes across C<has_many>,
394 C<has_one> and C<might_have> relationships. You can disable this
395 behaviour on a per-relationship basis by supplying
396 C<< cascade_delete => 0 >> in the relationship attributes.
398 The cascaded operations are performed after the requested delete,
399 so if your database has a constraint on the relationship, it will
400 have deleted/updated the related records or raised an exception
401 before DBIx::Class gets to perform the cascaded operation.
405 By default, DBIx::Class cascades updates across C<has_one> and
406 C<might_have> relationships. You can disable this behaviour on a
407 per-relationship basis by supplying C<< cascade_update => 0 >> in
408 the relationship attributes.
410 The C<belongs_to> relationship does not update across relationships
411 by default, so if you have a 'proxy' attribute on a belongs_to and want to
412 use 'update' on it, you must set C<< cascade_update => 1 >>.
414 This is not a RDMS style cascade update - it purely means that when
415 an object has update called on it, all the related objects also
416 have update called. It will not change foreign keys automatically -
417 you must arrange to do this yourself.
419 =item on_delete / on_update
421 If you are using L<SQL::Translator> to create SQL for you, you can use these
422 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
423 type. If not supplied the SQLT parser will attempt to infer the constraint type by
424 interrogating the attributes of the B<opposite> relationship. For any 'multi'
425 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
426 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
427 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
428 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
429 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
430 C<< on_delete => '' >>, and the same for C<on_update> respectively.
434 Tells L<SQL::Translator> that the foreign key constraint it creates should be
435 deferrable. In other words, the user may request that the constraint be ignored
436 until the end of the transaction. Currently, only the PostgreSQL producer
437 actually supports this.
441 Tells L<SQL::Translator> to add an index for this constraint. Can also be
442 specified globally in the args to L<DBIx::Class::Schema/deploy> or
443 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
447 =head2 register_relationship
451 =item Arguments: $rel_name, $rel_info
455 Registers a relationship on the class. This is called internally by
456 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
460 sub register_relationship { }
462 =head2 related_resultset
466 =item Arguments: $rel_name
468 =item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
472 $rs = $cd->related_resultset('artist');
474 Returns a L<DBIx::Class::ResultSet> for the relationship named
477 =head2 $relationship_accessor
481 =item Arguments: none
483 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
487 # These pairs do the same thing
488 $result = $cd->related_resultset('artist')->single; # has_one relationship
489 $result = $cd->artist;
490 $rs = $cd->related_resultset('tracks'); # has_many relationship
493 This is the recommended way to traverse through relationships, based
494 on the L</accessor> name given in the relationship definition.
496 This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
497 L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
498 C<single> (returns only one row) or C<multi> (returns many rows). The
499 method may also return C<undef> if the relationship doesn't exist for
500 this instance (like in the case of C<might_have> relationships).
504 sub related_resultset {
505 $_[0]->throw_exception(
506 '$result->related_resultset() no longer accepts extra search arguments, '
507 . 'you need to switch to ...->related_resultset($relname)->search_rs(...) '
508 . 'instead (it was never documented and more importantly could never work '
509 . 'reliably due to the heavy caching involved)'
512 $_[0]->throw_exception("Can't call *_related as class methods")
515 return $_[0]->{related_resultsets}{$_[1]}
516 if defined $_[0]->{related_resultsets}{$_[1]};
518 my ($self, $rel) = @_;
520 my $rsrc = $self->result_source;
522 my $rel_info = $rsrc->relationship_info($rel)
523 or $self->throw_exception( "No such relationship '$rel'" );
525 my $relcond_is_freeform = ref $rel_info->{cond} eq 'CODE';
527 my $jfc = $rsrc->_resolve_relationship_condition(
530 self_result_object => $self,
532 # an extra sanity check guard
533 require_join_free_condition => ! $relcond_is_freeform,
535 # an API where these are optional would be too cumbersome,
536 # instead always pass in some dummy values
539 # this may look weird, but remember that we are making a resultset
540 # out of an existing object, with the new source being at the head
541 # of the FROM chain. Having a 'me' alias is nothing but expected there
542 foreign_alias => 'me',
544 )->{join_free_condition};
550 $rel_rset = $rsrc->related_source($rel)->resultset->search(
555 elsif( $relcond_is_freeform ) {
557 # A WHOREIFFIC hack to reinvoke the entire condition resolution
558 # with the correct alias. Another way of doing this involves a
559 # lot of state passing around, and the @_ positions are already
560 # mapped out, making this crap a less icky option.
562 # The point of this exercise is to retain the spirit of the original
563 # $obj->search_related($rel) where the resulting rset will have the
564 # root alias as 'me', instead of $rel (as opposed to invoking
565 # $rs->search_related)
567 # make the fake 'me' rel
568 local $rsrc->{_relationships}{me} = {
569 %{ $rsrc->{_relationships}{$rel} },
570 _original_name => $rel,
573 my $obj_table_alias = lc($rsrc->source_name) . '__row';
574 $obj_table_alias =~ s/\W+/_/g;
576 $rel_rset = $rsrc->resultset->search(
577 $self->ident_condition($obj_table_alias),
578 { alias => $obj_table_alias },
579 )->related_resultset('me')->search(undef, $rel_info->{attrs})
583 my $attrs = { %{$rel_info->{attrs}} };
584 my $reverse = $rsrc->reverse_relationship_info($rel);
586 # FIXME - this loop doesn't seem correct - got to figure out
587 # at some point what exactly it does.
588 ( ( $reverse->{$_}{attrs}{accessor}||'') eq 'multi' )
589 ? weaken( $attrs->{related_objects}{$_}[0] = $self )
590 : weaken( $attrs->{related_objects}{$_} = $self )
593 $rel_rset = $rsrc->related_source($rel)->resultset->search(
594 UNRESOLVABLE_CONDITION, # guards potential use of the $rs in the future
599 $self->{related_resultsets}{$rel} = $rel_rset;
602 =head2 search_related
606 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
608 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
612 Run a search on a related resultset. The search will be restricted to the
613 results represented by the L<DBIx::Class::ResultSet> it was called
616 See L<DBIx::Class::ResultSet/search_related> for more information.
620 sub search_related :DBIC_method_is_indirect_sugar {
621 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
622 shift->related_resultset(shift)->search(@_);
625 =head2 search_related_rs
627 This method works exactly the same as search_related, except that
628 it guarantees a resultset, even in list context.
632 sub search_related_rs :DBIC_method_is_indirect_sugar {
633 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
634 shift->related_resultset(shift)->search_rs(@_)
641 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
643 =item Return Value: $count
647 Returns the count of all the rows in the related resultset, restricted by the
648 current result or where conditions.
652 sub count_related :DBIC_method_is_indirect_sugar {
653 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
654 shift->related_resultset(shift)->search_rs(@_)->count;
661 =item Arguments: $rel_name, \%col_data
663 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
667 Create a new result object of the related foreign class. It will magically set
668 any foreign key columns of the new object to the related primary key columns
669 of the source object for you. The newly created result will not be saved into
670 your storage until you call L<DBIx::Class::Row/insert> on it.
675 my ($self, $rel, $data) = @_;
677 $self->related_resultset($rel)->new_result( $self->result_source->_resolve_relationship_condition (
678 infer_values_based_on => $data,
680 self_result_object => $self,
682 # an API where these are optional would be too cumbersome,
683 # instead always pass in some dummy values
686 )->{inferred_values} );
689 =head2 create_related
693 =item Arguments: $rel_name, \%col_data
695 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
699 my $result = $obj->create_related($rel_name, \%col_data);
701 Creates a new result object, similarly to new_related, and also inserts the
702 result's data into your storage medium. See the distinction between C<create>
703 and C<new> in L<DBIx::Class::ResultSet> for details.
710 my $obj = $self->new_related($rel, @_)->insert;
711 delete $self->{related_resultsets}->{$rel};
719 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
721 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
725 my $result = $obj->find_related($rel_name, \%col_data);
727 Attempt to find a related object using its primary key or unique constraints.
728 See L<DBIx::Class::ResultSet/find> for details.
732 sub find_related :DBIC_method_is_indirect_sugar {
733 #my ($self, $rel, @args) = @_;
734 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
735 return shift->related_resultset(shift)->find(@_);
738 =head2 find_or_new_related
742 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
744 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
748 Find a result object of a related class. See L<DBIx::Class::ResultSet/find_or_new>
753 sub find_or_new_related {
756 my $obj = $self->related_resultset($rel)->find(@_);
757 return defined $obj ? $obj : $self->related_resultset($rel)->new_result(@_);
760 =head2 find_or_create_related
764 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
766 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
770 Find or create a result object of a related class. See
771 L<DBIx::Class::ResultSet/find_or_create> for details.
775 sub find_or_create_related {
778 my $obj = $self->related_resultset($rel)->find(@_);
779 return (defined($obj) ? $obj : $self->create_related( $rel => @_ ));
782 =head2 update_or_create_related
786 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
788 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
792 Update or create a result object of a related class. See
793 L<DBIx::Class::ResultSet/update_or_create> for details.
797 sub update_or_create_related :DBIC_method_is_indirect_sugar {
798 #my ($self, $rel, @args) = @_;
799 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
800 shift->related_resultset(shift)->update_or_create(@_);
803 =head2 set_from_related
807 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
809 =item Return Value: not defined
813 $book->set_from_related('author', $author_obj);
814 $book->author($author_obj); ## same thing
816 Set column values on the current object, using related values from the given
817 related object. This is used to associate previously separate objects, for
818 example, to set the correct author for a book, find the Author object, then
819 call set_from_related on the book.
821 This is called internally when you pass existing objects as values to
822 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
824 The columns are only set in the local copy of the object, call
825 L<update|DBIx::Class::Row/update> to update them in the storage.
829 sub set_from_related {
830 my ($self, $rel, $f_obj) = @_;
832 $self->set_columns( $self->result_source->_resolve_relationship_condition (
833 infer_values_based_on => {},
836 # maintain crazy set_from_related interface
838 ( ! defined $f_obj ) ? +{}
839 : ( ! defined blessed $f_obj ) ? $f_obj
842 my $f_result_class = $self->result_source->related_source($rel)->result_class;
844 unless( $f_obj->isa($f_result_class) ) {
846 $self->throw_exception(
847 'Object supplied to set_from_related() must inherit from '
848 . "'$DBIx::Class::ResultSource::__expected_result_class_isa'"
849 ) unless $f_obj->isa(
850 $DBIx::Class::ResultSource::__expected_result_class_isa
854 'Object supplied to set_from_related() usually should inherit from '
855 . "the related ResultClass ('$f_result_class'), perhaps you've made "
860 +{ $f_obj->get_columns };
864 # an API where these are optional would be too cumbersome,
865 # instead always pass in some dummy values
868 )->{inferred_values} );
873 =head2 update_from_related
877 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
879 =item Return Value: not defined
883 $book->update_from_related('author', $author_obj);
885 The same as L</"set_from_related">, but the changes are immediately updated
890 sub update_from_related {
892 $self->set_from_related(@_);
896 =head2 delete_related
900 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
902 =item Return Value: $underlying_storage_rv
906 Delete any related row, subject to the given conditions. Internally, this
909 $self->search_related(@_)->delete
911 And returns the result of that.
918 my $obj = $self->related_resultset($rel)->search_rs(@_)->delete;
919 delete $self->{related_resultsets}->{$rel};
925 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
928 =head3 has_many / multi
932 =item Arguments: \%col_data
934 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
938 Creates/inserts a new result object. Internally, this calls:
940 $self->create_related($rel, @_)
942 And returns the result of that.
948 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
950 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
954 my $role = $schema->resultset('Role')->find(1);
955 $actor->add_to_roles($role);
956 # creates a My::DBIC::Schema::ActorRoles linking table result object
958 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
959 # creates a new My::DBIC::Schema::Role result object and the linking table
960 # object with an extra column in the link
962 Adds a linking table object. If the first argument is a hash reference, the
963 related object is created first with the column values in the hash. If an object
964 reference is given, just the linking table object is created. In either case,
965 any additional column values for the linking table object can be specified in
968 See L<DBIx::Class::Relationship/many_to_many> for additional details.
972 B<Currently only available for C<many_to_many> relationships.>
976 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
978 =item Return Value: not defined
982 my $actor = $schema->resultset('Actor')->find(1);
983 my @roles = $schema->resultset('Role')->search({ role =>
984 { '-in' => ['Fred', 'Barney'] } } );
986 $actor->set_roles(\@roles);
987 # Replaces all of $actor's previous roles with the two named
989 $actor->set_roles(\@roles, { salary => 15_000_000 });
990 # Sets a column in the link table for all roles
993 Replace all the related objects with the given reference to a list of
994 objects. This does a C<delete> B<on the link table resultset> to remove the
995 association between the current object and all related objects, then calls
996 C<add_to_$rel> repeatedly to link all the new objects.
998 Note that this means that this method will B<not> delete any objects in the
999 table on the right side of the relation, merely that it will delete the link
1002 Due to a mistake in the original implementation of this method, it will also
1003 accept a list of objects or hash references. This is B<deprecated> and will be
1004 removed in a future version.
1006 =head2 remove_from_$rel
1008 B<Currently only available for C<many_to_many> relationships.>
1012 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
1014 =item Return Value: not defined
1018 my $role = $schema->resultset('Role')->find(1);
1019 $actor->remove_from_roles($role);
1020 # removes $role's My::DBIC::Schema::ActorRoles linking table result object
1022 Removes the link between the current object and the related object. Note that
1023 the related object itself won't be deleted unless you call ->delete() on
1024 it. This method just removes the link between the two objects.
1026 =head1 FURTHER QUESTIONS?
1028 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1030 =head1 COPYRIGHT AND LICENSE
1032 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1033 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1034 redistribute it and/or modify it under the same terms as the
1035 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.