From: Will Hawes <wdhawes@gmail.com>
Date: Mon, 23 Jan 2006 17:48:39 +0000 (+0000)
Subject: flesh out doc for 'from', 'select', 'as' and 'group_by'
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=4a28c3401397f015e833a802ddab5d341693f7dd;p=dbsrgits%2FDBIx-Class-Historic.git

flesh out doc for 'from', 'select', 'as' and 'group_by'
---

diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm
index ff876b1..4df3d58 100644
--- a/lib/DBIx/Class/ResultSet.pm
+++ b/lib/DBIx/Class/ResultSet.pm
@@ -657,11 +657,57 @@ from that, then auto-populates C<as> from C<select> as normal.
 
 =head2 select (arrayref)
 
-Indicates which columns should be selected from the storage.
+Indicates which columns should be selected from the storage. You can use
+column names, or in the case of RDBMS back ends, function or stored procedure
+names:
+
+  $rs = $schema->resultset('Foo')->search(
+    {},
+    {
+      select => {
+        'column_name',
+        { count => 'column_to_count' },
+        { sum => 'column_to_sum' }
+      }
+    }
+  );
+
+When you use function/stored procedure names and do not supply an C<as>
+attribute, the column names returned are storage-dependent. E.g. MySQL would
+return a column named C<count(column_to_count)> in the above example.
 
 =head2 as (arrayref)
 
-Indicates column names for object inflation.
+Indicates column names for object inflation. This is used in conjunction with
+C<select>, usually when C<select> contains one or more function or stored
+procedure names:
+
+  $rs = $schema->resultset('Foo')->search(
+    {},
+    {
+      select => {
+        'column1',
+        { count => 'column2' }
+      },
+      as => [qw/ column1 column2_count /]
+    }
+  );
+
+  my $foo = $rs->first(); # get the first Foo
+
+If the object against which the search is performed already has an accessor
+matching a column name specified in C<as>, the value can be retrieved using
+the accessor as normal:
+
+  my $column1 = $foo->column1();
+
+If on the other hand an accessor does not exist in the object, you need to
+use C<get_column> instead:
+
+  my $column2_count = $foo->get_column('column2_count');
+
+You can create your own accessors if required - see
+L<DBIx::Class::Manual::Cookbook> for details.
 
 =head2 join
 
@@ -705,13 +751,92 @@ query (when they are accessed afterwards they will have already been
 objects, because it saves a query.  Currently limited to prefetching
 one relationship deep, so unlike C<join>, prefetch must be an arrayref.
 
-=head2 from 
+=head2 from (arrayref)
 
-This attribute can contain a arrayref of elements.  Each element can be another
-arrayref, to nest joins, or it can be a hash which represents the two sides
-of the join. 
+The C<from> attribute gives you manual control over the C<FROM> clause of SQL
+statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
+clauses.
 
 NOTE: Use this on your own risk.  This allows you to shoot off your foot!
+C<join> will usually do what you need and it is strongly recommended that you
+avoid using C<from> unless you cannot achieve the desired result using C<join>.
+
+In simple terms, C<from> works as follows:
+
+    [
+        { <alias> => <table>, -join-type => 'inner|left|right' }
+        [] # nested JOIN (optional)
+        { <table.column> = <foreign_table.foreign_key> }
+    ]
+
+    JOIN
+        <alias> <table>
+        [JOIN ...]
+    ON <table.column> = <foreign_table.foreign_key>
+
+An easy way to follow the examples below is to remember the following:
+
+    Anything inside "[]" is a JOIN
+    Anything inside "{}" is a condition for the enclosing JOIN
+
+The following examples utilize a "person" table in a family tree application.
+In order to express parent->child relationships, this table is self-joined:
+
+    # Person->belongs_to('father' => 'Person');
+    # Person->belongs_to('mother' => 'Person');
+
+C<from> can be used to nest joins. Here we return all children with a father,
+then search against all mothers of those children:
+
+  $rs = $schema->resultset('Person')->search(
+      {},
+      {
+          alias => 'mother', # alias columns in accordance with "from"
+          from => [
+              { mother => 'person' },
+              [
+                  [
+                      { child => 'person' },
+                      [
+                          { father => 'person' },
+                          { 'father.person_id' => 'child.father_id' }
+                      ]
+                  ],
+                  { 'mother.person_id' => 'child.mother_id' }
+              ],                
+          ]
+      },
+  );
+
+  # Equivalent SQL:
+  # SELECT mother.* FROM person mother
+  # JOIN (
+  #   person child
+  #   JOIN person father
+  #   ON ( father.person_id = child.father_id )
+  # )
+  # ON ( mother.person_id = child.mother_id )
+
+The type of any join can be controlled manually. To search against only people
+with a father in the person table, we could explicitly use C<INNER JOIN>:
+
+    $rs = $schema->resultset('Person')->search(
+        {},
+        {
+            alias => 'child', # alias columns in accordance with "from"
+            from => [
+                { child => 'person' },
+                [
+                    { father => 'person', -join-type => 'inner' },
+                    { 'father.id' => 'child.father_id' }
+                ],
+            ]
+        },
+    );
+
+    # Equivalent SQL:
+    # SELECT child.* FROM person child
+    # INNER JOIN person father ON child.father_id = father.id
 
 =head2 page
 
@@ -720,13 +845,16 @@ for an unpaged resultset.
 
 =head2 rows
 
-For a paged resultset, how many rows per page.  Can also be used to simulate an
-SQL C<LIMIT>.
+For a paged resultset, how many rows per page:
+
+  rows => 10
+
+Can also be used to simulate an SQL C<LIMIT>.
 
 =head2 group_by (arrayref)
 
-A arrayref of columns to group by (note that L</count> doesn't work on grouped
-resultsets).
+A arrayref of columns to group by. Can include columns of joined tables. Note
+note that L</count> doesn't work on grouped resultsets.
 
   group_by => [qw/ column1 column2 ... /]