| DBIx::Class::Relationship::Base(3) | User Contributed Perl Documentation | DBIx::Class::Relationship::Base(3) |
DBIx::Class::Relationship::Base - Inter-table relationships
__PACKAGE__->add_relationship(
spiders => 'My::DB::Result::Creatures',
sub {
my $args = shift;
return {
"$args->{foreign_alias}.id" => { -ident => "$args->{self_alias}.id" },
"$args->{foreign_alias}.type" => 'arachnid'
};
},
);
This class provides methods to describe the relationships between the tables in your database model. These are the "bare bones" relationships methods, for predefined ones, look in DBIx::Class::Relationship.
__PACKAGE__->add_relationship('rel_name',
'Foreign::Class',
$condition, $attrs);
Create a custom relationship between one result source and another source, indicated by its class name.
condition
The condition argument describes the "ON" clause of the "JOIN" expression used to connect the two sources when creating SQL queries.
Simple equality
To create simple equality joins, supply a hashref containing the remote table column name as the key(s) prefixed by 'foreign.', and the corresponding local table column name as the value(s) prefixed by 'self.'. Both "foreign" and "self" are pseudo aliases and must be entered literally. They will be replaced with the actual correct table alias when the SQL is produced.
For example given:
My::Schema::Author->has_many(
books => 'My::Schema::Book',
{ 'foreign.author_id' => 'self.id' }
);
A query like:
$author_rs->search_related('books')->next
will result in the following "JOIN" clause:
... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
This describes a relationship between the "Author" table and the "Book" table where the "Book" table has a column "author_id" containing the ID value of the "Author".
Similarly:
My::Schema::Book->has_many(
editions => 'My::Schema::Edition',
{
'foreign.publisher_id' => 'self.publisher_id',
'foreign.type_id' => 'self.type_id',
}
);
...
$book_rs->search_related('editions')->next
will result in the "JOIN" clause:
... FROM book me
LEFT JOIN edition editions ON
editions.publisher_id = me.publisher_id
AND editions.type_id = me.type_id ...
This describes the relationship from "Book" to "Edition", where the "Edition" table refers to a publisher and a type (e.g. "paperback"):
Multiple groups of simple equality conditions
As is the default in SQL::Abstract, the key-value pairs will be "AND"ed in the resulting "JOIN" clause. An "OR" can be achieved with an arrayref. For example a condition like:
My::Schema::Item->has_many(
related_item_links => My::Schema::Item::Links,
[
{ 'foreign.left_itemid' => 'self.id' },
{ 'foreign.right_itemid' => 'self.id' },
],
);
will translate to the following "JOIN" clause:
... FROM item me JOIN item_relations related_item_links ON
related_item_links.left_itemid = me.id
OR related_item_links.right_itemid = me.id ...
This describes the relationship from "Item" to "Item::Links", where "Item::Links" is a many-to-many linking table, linking items back to themselves in a peer fashion (without a "parent-child" designation)
Custom join conditions
NOTE: The custom join condition specification mechanism is capable of generating JOIN clauses of virtually unlimited complexity. This may limit your ability to traverse some of the more involved relationship chains the way you expect, *and* may bring your RDBMS to its knees. Exercise care when declaring relationships as described here.
To specify joins which describe more than a simple equality of column values, the custom join condition coderef syntax can be used. For example:
My::Schema::Artist->has_many(
cds_80s => 'My::Schema::CD',
sub {
my $args = shift;
return {
"$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
"$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
};
}
);
...
$artist_rs->search_related('cds_80s')->next;
will result in the "JOIN" clause:
... FROM artist me LEFT JOIN cd cds_80s ON
cds_80s.artist = me.artistid
AND cds_80s.year < ?
AND cds_80s.year > ?
with the bind values:
'1990', '1979'
"$args->{foreign_alias}" and "$args->{self_alias}" are supplied the same values that would be otherwise substituted for "foreign" and "self" in the simple hashref syntax case.
The coderef is expected to return a valid SQL::Abstract query-structure, just like what one would supply as the first argument to "search" in DBIx::Class::ResultSet. The return value will be passed directly to SQL::Abstract and the resulting SQL will be used verbatim as the "ON" clause of the "JOIN" statement associated with this relationship.
While every coderef-based condition must return a valid "ON" clause, it may elect to additionally return a simplified optional join-free condition consisting of a hashref with all keys being fully qualified names of columns declared on the corresponding result source. This boils down to two scenarios:
Note that the above scenarios are mutually exclusive, that is you will be supplied none or only one of "self_result_object" and "foreign_values". In other words if you define your condition coderef as:
sub {
my $args = shift;
return (
{
"$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
"$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
},
! $args->{self_result_object} ? () : {
"$args->{foreign_alias}.artist" => $args->{self_result_object}->artistid,
"$args->{foreign_alias}.year" => { '>', "1979", '<', "1990" },
},
! $args->{foreign_values} ? () : {
"$args->{self_alias}.artistid" => $args->{foreign_values}{artist},
}
);
}
Then this code:
my $artist = $schema->resultset("Artist")->find({ id => 4 });
$artist->cds_80s->all;
Can skip a "JOIN" altogether and instead produce:
SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
FROM cd cds_80s
WHERE cds_80s.artist = ?
AND cds_80s.year < ?
AND cds_80s.year > ?
With the bind values:
'4', '1990', '1979'
While this code:
my $cd = $schema->resultset("CD")->search({ artist => 1 }, { rows => 1 })->single;
my $artist = $schema->resultset("Artist")->new({});
$artist->set_from_related('cds_80s');
Will properly set the "$artist->artistid" field of this new object to 1
Note that in order to be able to use "set_from_related" (and by extension $result->create_related), the returned join free condition must contain only plain values/deflatable objects. For instance the "year" constraint in the above example prevents the relationship from being used to create related objects using "$artst->create_related( cds_80s => { title => 'blah' } )" (an exception will be thrown).
In order to allow the user to go truly crazy when generating a custom "ON" clause, the $args hashref passed to the subroutine contains some extra metadata. Currently the supplied coderef is executed as:
$relationship_info->{cond}->({
self_resultsource => The resultsource instance on which rel_name is registered
rel_name => The relationship name (does *NOT* always match foreign_alias)
self_alias => The alias of the invoking resultset
foreign_alias => The alias of the to-be-joined resultset (does *NOT* always match rel_name)
# only one of these (or none at all) will ever be supplied to aid in the
# construction of a join-free condition
self_result_object => The invocant *object* itself in case of a call like
$result_object->$rel_name( ... )
foreign_values => A *hashref* of related data: may be passed in directly or
derived via ->get_columns() from a related object in case of
$result_object->set_from_related( $rel_name, $foreign_result_object )
# deprecated inconsistent names, will be forever available for legacy code
self_rowobj => Old deprecated slot for self_result_object
foreign_relname => Old deprecated slot for rel_name
});
attributes
The standard ResultSet attributes may be used as relationship attributes. In particular, the 'where' attribute is useful for filtering relationships:
__PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
{ 'foreign.user_id' => 'self.user_id' },
{ where => { valid => 1 } }
);
The following attributes are also valid:
MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
undef, {
proxy => [ qw/notes/ ],
});
Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
my $cd = MyApp::Schema::CD->find(1);
$cd->notes('Notes go here'); # set notes -- LinerNotes object is
# created if it doesn't exist
For a 'belongs_to relationship, note the 'cascade_update':
MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
{ proxy => ['title'], cascade_update => 1 }
);
$track->title('New Title');
$track->update; # updates title in CD
MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
proxy => { cd_title => 'title' },
});
This will create an accessor named "cd_title" on the $track result object.
NOTE: you can pass a nested struct too, for example:
MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
proxy => [ 'year', { cd_title => 'title' } ],
});
The behaviour defaults to "cascade_copy => 1" for "has_many" relationships.
The cascaded operations are performed after the requested delete, so if your database has a constraint on the relationship, it will have deleted/updated the related records or raised an exception before DBIx::Class gets to perform the cascaded operation.
The "belongs_to" relationship does not update across relationships by default, so if you have a 'proxy' attribute on a belongs_to and want to use 'update' on it, you must set "cascade_update => 1".
This is not a RDMS style cascade update - it purely means that when an object has update called on it, all the related objects also have update called. It will not change foreign keys automatically - you must arrange to do this yourself.
Registers a relationship on the class. This is called internally by DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
$rs = $cd->related_resultset('artist');
Returns a DBIx::Class::ResultSet for the relationship named $rel_name.
# These pairs do the same thing
$result = $cd->related_resultset('artist')->single; # has_one relationship
$result = $cd->artist;
$rs = $cd->related_resultset('tracks'); # has_many relationship
$rs = $cd->tracks;
This is the recommended way to traverse through relationships, based on the "accessor" name given in the relationship definition.
This will return either a Result or a ResultSet, depending on if the relationship is "single" (returns only one row) or "multi" (returns many rows). The method may also return "undef" if the relationship doesn't exist for this instance (like in the case of "might_have" relationships).
Run a search on a related resultset. The search will be restricted to the results represented by the DBIx::Class::ResultSet it was called upon.
See "search_related" in DBIx::Class::ResultSet for more information.
This method works exactly the same as search_related, except that it guarantees a resultset, even in list context.
Returns the count of all the rows in the related resultset, restricted by the current result or where conditions.
Create a new result object of the related foreign class. It will magically set any foreign key columns of the new object to the related primary key columns of the source object for you. The newly created result will not be saved into your storage until you call "insert" in DBIx::Class::Row on it.
my $result = $obj->create_related($rel_name, \%col_data);
Creates a new result object, similarly to new_related, and also inserts the result's data into your storage medium. See the distinction between "create" and "new" in DBIx::Class::ResultSet for details.
my $result = $obj->find_related($rel_name, \%col_data);
Attempt to find a related object using its primary key or unique constraints. See "find" in DBIx::Class::ResultSet for details.
Find a result object of a related class. See "find_or_new" in DBIx::Class::ResultSet for details.
Find or create a result object of a related class. See "find_or_create" in DBIx::Class::ResultSet for details.
Update or create a result object of a related class. See "update_or_create" in DBIx::Class::ResultSet for details.
$book->set_from_related('author', $author_obj);
$book->author($author_obj); ## same thing
Set column values on the current object, using related values from the given related object. This is used to associate previously separate objects, for example, to set the correct author for a book, find the Author object, then call set_from_related on the book.
This is called internally when you pass existing objects as values to "create" in DBIx::Class::ResultSet, or pass an object to a belongs_to accessor.
The columns are only set in the local copy of the object, call update to update them in the storage.
$book->update_from_related('author', $author_obj);
The same as "set_from_related", but the changes are immediately updated in storage.
Delete any related row, subject to the given conditions. Internally, this calls:
$self->search_related(@_)->delete
And returns the result of that.
Currently only available for "has_many", "many_to_many" and 'multi' type relationships.
has_many / multi
Creates/inserts a new result object. Internally, this calls:
$self->create_related($rel, @_)
And returns the result of that.
many_to_many
my $role = $schema->resultset('Role')->find(1);
$actor->add_to_roles($role);
# creates a My::DBIC::Schema::ActorRoles linking table result object
$actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
# creates a new My::DBIC::Schema::Role result object and the linking table
# object with an extra column in the link
Adds a linking table object. If the first argument is a hash reference, the related object is created first with the column values in the hash. If an object reference is given, just the linking table object is created. In either case, any additional column values for the linking table object can be specified in "\%link_col_data".
See "many_to_many" in DBIx::Class::Relationship for additional details.
Currently only available for "many_to_many" relationships.
my $actor = $schema->resultset('Actor')->find(1);
my @roles = $schema->resultset('Role')->search({ role =>
{ '-in' => ['Fred', 'Barney'] } } );
$actor->set_roles(\@roles);
# Replaces all of $actor's previous roles with the two named
$actor->set_roles(\@roles, { salary => 15_000_000 });
# Sets a column in the link table for all roles
Replace all the related objects with the given reference to a list of objects. This does a "delete" on the link table resultset to remove the association between the current object and all related objects, then calls "add_to_$rel" repeatedly to link all the new objects.
Note that this means that this method will not delete any objects in the table on the right side of the relation, merely that it will delete the link between them.
Due to a mistake in the original implementation of this method, it will also accept a list of objects or hash references. This is deprecated and will be removed in a future version.
Currently only available for "many_to_many" relationships.
my $role = $schema->resultset('Role')->find(1);
$actor->remove_from_roles($role);
# removes $role's My::DBIC::Schema::ActorRoles linking table result object
Removes the link between the current object and the related object. Note that the related object itself won't be deleted unless you call ->delete() on it. This method just removes the link between the two objects.
Check the list of additional DBIC resources.
This module is free software copyright by the DBIx::Class (DBIC) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class library.
| 2018-01-29 | perl v5.34.0 |