document group by and having clauses

[scpubgit/Q-Branch.git] / lib / SQL / Abstract / ExtraClauses.pm

diff --git a/lib/SQL/Abstract/ExtraClauses.pm b/lib/SQL/Abstract/ExtraClauses.pm
index 9c27845..e16f927 100644 (file)
--- a/lib/SQL/Abstract/ExtraClauses.pm
+++ b/lib/SQL/Abstract/ExtraClauses.pm
@@ -5,7 +5,7 @@ use Moo;
 has sqla => (
   is => 'ro', init_arg => undef,
   handles => [ qw(
-    expand_expr expand_maybe_list_expr render_aqt join_query_parts
+    expand_expr render_aqt join_query_parts
   ) ],
 );
 
@@ -79,7 +79,7 @@ sub register_extensions {
     clause_expanders => [
       "select.from", '_expand_from_list',
       'select.group_by'
-        => sub { $_[0]->expand_maybe_list_expr($_[2], -ident) },
+        => sub { $_[0]->expand_expr({ -list => $_[2] }, -ident) },
       'select.having'
         => sub { $_[0]->expand_expr($_[2]) },
       'update.from' => '_expand_from_list',
@@ -377,6 +377,11 @@ SQL::Abstract::ExtraClauses - new/experimental additions to L<SQL::Abstract>
   my $sqla = SQL::Abstract->new;
   SQL::Abstract::ExtraClauses->apply_to($sqla);
 
+=head1 WARNING
+
+This module is basically a nursery for things that seem like a good idea
+to live in until we figure out if we were right about that.
+
 =head1 METHODS
 
 =head2 apply_to
@@ -575,4 +580,44 @@ With oddities:
   x LEFT JOIN ( y LEFT JOIN z )
   []
 
+=head1 STATEMENT EXTENSIONS
+
+=head2 group by clause for select
+
+Expanded as a list with an ident default:
+
+  # expr
+  { -select => { group_by => [ 'foo', 'bar' ] } }
+
+  # aqt
+  { -select => { group_by =>
+        {
+          -op => [ ',', { -ident => [ 'foo' ] }, { -ident => [ 'bar' ] } ]
+        }
+  } }
+
+  # query
+  GROUP BY foo, bar
+  []
+
+=head2 having clause for select
+
+Basic expr, just like where, given having is pretty much post-group-by
+where clause:
+
+  # expr
+  { -select =>
+      { having => { '>' => [ { -count => { -ident => 'foo' } }, 3 ] } }
+  }
+
+  # aqt
+  { -select => { having => { -op => [
+          '>', { -func => [ 'count', { -ident => [ 'foo' ] } ] },
+          { -bind => [ undef, 3 ] },
+  ] } } }
+
+  # query
+  HAVING COUNT(foo) > ?
+  [ 3 ]
+
 =cut