lib/DBIx/Class/Manual/Joining.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::Joining - Manual on joining tables with DBIx::Class
   4
   5 =head1 DESCRIPTION
   6
   7 This document should help you to use L<DBIx::Class> if you are trying
   8 to convert your normal SQL queries into DBIx::Class based queries, if
   9 you use joins extensively (and also probably if you don't).
  10
  11 =head1 WHAT ARE JOINS
  12
  13 If you ended up here and you don't actually know what joins are yet,
  14 then you should likely try the L<DBIx::Class::Manual::Intro>
  15 instead. Skip this part if you know what joins are..
  16
  17 But I'll explain anyway. Assuming you have created your database in a
  18 more or less sensible way, you will end up with several tables that
  19 contain C<related> information. For example, you may have a table
  20 containing information about C<CDs>, containing the CD title and it's
  21 year of publication, and another table containing all the C<Track>s
  22 for the CDs, one track per row.
  23
  24 When you wish to extract information about a particular CD and all
  25 it's tracks, You can either fetch the CD row, then make another query
  26 to fetch the tracks, or you can use a join. Compare:
  27
  28   SELECT ID, Title, Year FROM CD WHERE Title = 'Funky CD';
  29   # .. Extract the ID, which is 10
  30   SELECT Name, Artist FROM Tracks WHERE CDID = 10;
  31
  32   SELECT cd.ID, cd.Title, cd.Year, tracks.Name, tracks.Artist FROM CD JOIN Tracks ON CD.ID = tracks.CDID WHERE cd.Title = 'Funky CD';
  33
  34 So, joins are a way of extending simple select statements to include
  35 fields from other, related, tables. There are various types of joins,
  36 depending on which combination of the data you wish to retrieve, see
  37 L<MySQL's doc on JOINs|http://dev.mysql.com/doc/refman/5.0/en/join.html>.
  38
  39 =head1 DEFINING JOINS AND RELATIONSHIPS
  40
  41 In L<DBIx::Class> each relationship between two tables needs to first
  42 be defined in the L<ResultSource|DBIx::Class::Manual::Glossary/ResultSource> for the
  43 table. If the relationship needs to be accessed in both directions
  44 (i.e. Fetch all tracks of a CD, and fetch the CD data for a Track),
  45 then it needs to be defined in both tables.
  46
  47 For the CDs/Tracks example, that means writing, in C<MySchema::CD>:
  48
  49   MySchema::CD->has_many('tracks', 'MySchema::Tracks');
  50
  51 And in C<MySchema::Tracks>:
  52
  53   MySchema::Tracks->belongs_to('cd', 'MySchema::CD', 'CDID');
  54
  55 There are several other types of relationships, they are more
  56 comprehensively described in L<DBIx::Class::Relationship>.
  57
  58 =head1 USING JOINS
  59
  60 Once you have defined all your relationships, using them in actual
  61 joins is fairly simple. The type of relationship that you chose
  62 e.g. C<has_many>, already indicates what sort of join will be
  63 performed. C<has_many> produces a C<LEFT JOIN> for example, which will
  64 fetch all the rows on the left side, whether there are matching rows
  65 on the right (table being joined to), or not. You can force other
  66 types of joins in your relationship, see the
  67 L<DBIx::Class::Relationship> docs.
  68
  69 When performing either a L<search|DBIx::Class::ResultSet/search> or a
  70 L<find|DBIx::Class::ResultSet/find> operation, you can specify which
  71 C<relations> to also fetch data from (or sort by), using the
  72 L<join|DBIx::Class::ResultSet/join> attribute, like this:
  73
  74   $schema->resultset('CD')->search(
  75     { 'Title' => 'Funky CD' },
  76     { join      => 'tracks',
  77       '+select' => [ 'tracks.Name', 'tracks.Artist' ],
  78       '+as'     => [ 'TrackName', 'ArtistName' ]
  79     }
  80   );
  81
  82 If you don't recognise most of this syntax, you should probably go
  83 read L<DBIx::Class::ResultSet/search> and
  84 L<DBIx::Class::ResultSet/ATTRIBUTES>, but here's a quick break down:
  85
  86 The first argument to search is a hashref of the WHERE attributes, in
  87 this case a simple restriction on the Title column. The second
  88 argument is a hashref of attributes to the search, '+select' adds
  89 extra columns to the select (from the joined table(s) or from
  90 calculations), and '+as' gives aliases to those fields.
  91
  92 'join' specifies which C<relationships> to include in the query. The
  93 distinction between C<relationships> and C<tables> is important here,
  94 only the C<relationship> names are valid.
  95
  96 This example should magically produce SQL like the second select in
  97 L</WHAT ARE JOINS> above.
  98
  99 =head1 COMPLEX JOINS AND STUFF
 100
 101 =head2 Across multiple relations
 102
 103 For simplicity in the example above, the C<Artist> was shown as a
 104 simple text field in the C<Tracks> table, in reality, you'll want to
 105 have the artists in their own table as well, thus to fetch the
 106 complete set of data we'll need to join to the Artist table too.
 107
 108 In C<MySchema::Tracks>:
 109
 110   MySchema::Tracks->belongs_to('artist', 'MySchema::Artist', 'ArtistID');
 111
 112 The search:
 113
 114   $schema->resultset('CD')->search(
 115     { 'Title' => 'Funky CD' },
 116     { join      => { 'tracks' => 'artist' },
 117       '+select' => [ 'tracks.Name', 'artist.Artist' ],
 118       '+as'     => [ 'TrackName', 'ArtistName' ]
 119     }
 120   );
 121
 122 Which is:
 123
 124   SELECT me.ID, me.Title, me.Year, tracks.Name, artist.Artist FROM CD me JOIN Tracks tracks ON CD.ID = tracks.CDID JOIN Artists artist ON tracks.ArtistID = artist.ID WHERE me.Title = 'Funky CD';
 125
 126 To perform joins using relations of the tables you are joining to, use
 127 a hashref to indicate the join depth. This can theoretically go as
 128 deep as you like (warning, contrived examples!):
 129
 130   join => { room => { table => 'leg' } }
 131
 132 To join two relations at the same level, use an arrayref instead:
 133
 134   join => { room => [ 'chair', 'table' ] }
 135
 136 Or combine the two:
 137
 138   join => { room => [ 'chair', { table => 'leg' } ]
 139
 140 =head2 Table aliases
 141
 142 As an aside to all the discussion on joins, note that L<DBIx::Class>
 143 uses the C<relation names> as table aliases. This is important when
 144 you need to add grouping or ordering to your queries:
 145
 146   $schema->resultset('CD')->search(
 147     { 'Title' => 'Funky CD' },
 148     { join      => { 'tracks' => 'artist' },
 149       order_by  => [ 'tracks.Name', 'artist.Artist' ],
 150       '+select' => [ 'tracks.Name', 'artist.Artist' ],
 151       '+as'     => [ 'TrackName', 'ArtistName' ]
 152     }
 153   );
 154
 155   SELECT me.ID, me.Title, me.Year, tracks.Name, artist.Artist FROM CD me JOIN Tracks tracks ON CD.ID = tracks.CDID JOIN Artists artist ON tracks.ArtistID = artist.ID WHERE me.Title = 'Funky CD' ORDER BY tracks.Name, artist.Artist;
 156
 157 This is essential if any of your tables have columns with the same names.
 158
 159 Note that the table of the resultsource the search was performed on, is always aliased to C<me>.
 160
 161 =head2 Joining to the same table twice
 162
 163 There is no magic to this, just do it. The table aliases will
 164 automatically be numbered:
 165
 166   join => [ 'room', 'room' ]
 167
 168 The aliases are: C<room> and C<room_2>.
 169
 170 =cut
 171