49d615fecfccd6cadcaa174a7b03db224cc70e9c
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / ResultSet.pm
1 package DBIx::Class::ResultSet;
2
3 use strict;
4 use warnings;
5 use overload
6         '0+'     => \&count,
7         'bool'   => sub { 1; },
8         fallback => 1;
9 use Data::Page;
10 use Storable;
11 use Scalar::Util qw/weaken/;
12
13 use DBIx::Class::ResultSetColumn;
14 use base qw/DBIx::Class/;
15 __PACKAGE__->load_components(qw/AccessorGroup/);
16 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
17
18 =head1 NAME
19
20 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
21
22 =head1 SYNOPSIS
23
24   my $rs   = $schema->resultset('User')->search(registered => 1);
25   my @rows = $schema->resultset('CD')->search(year => 2005);
26
27 =head1 DESCRIPTION
28
29 The resultset is also known as an iterator. It is responsible for handling
30 queries that may return an arbitrary number of rows, e.g. via L</search>
31 or a C<has_many> relationship.
32
33 In the examples below, the following table classes are used:
34
35   package MyApp::Schema::Artist;
36   use base qw/DBIx::Class/;
37   __PACKAGE__->load_components(qw/Core/);
38   __PACKAGE__->table('artist');
39   __PACKAGE__->add_columns(qw/artistid name/);
40   __PACKAGE__->set_primary_key('artistid');
41   __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
42   1;
43
44   package MyApp::Schema::CD;
45   use base qw/DBIx::Class/;
46   __PACKAGE__->load_components(qw/Core/);
47   __PACKAGE__->table('cd');
48   __PACKAGE__->add_columns(qw/cdid artist title year/);
49   __PACKAGE__->set_primary_key('cdid');
50   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
51   1;
52
53 =head1 METHODS
54
55 =head2 new
56
57 =over 4
58
59 =item Arguments: $source, \%$attrs
60
61 =item Return Value: $rs
62
63 =back
64
65 The resultset constructor. Takes a source object (usually a
66 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
67 L</ATTRIBUTES> below).  Does not perform any queries -- these are
68 executed as needed by the other methods.
69
70 Generally you won't need to construct a resultset manually.  You'll
71 automatically get one from e.g. a L</search> called in scalar context:
72
73   my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
74
75 IMPORTANT: If called on an object, proxies to new_result instead so
76
77   my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
78
79 will return a CD object, not a ResultSet.
80
81 =cut
82
83 sub new {
84   my $class = shift;
85   return $class->new_result(@_) if ref $class;
86   
87   my ($source, $attrs) = @_;
88   weaken $source;
89   $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
90   #use Data::Dumper; warn Dumper($attrs);
91   my $alias = ($attrs->{alias} ||= 'me');
92   
93   $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
94   delete $attrs->{as} if $attrs->{columns};
95   $attrs->{columns} ||= [ $source->columns ] unless $attrs->{select};
96   $attrs->{select} = [
97     map { m/\./ ? $_ : "${alias}.$_" } @{delete $attrs->{columns}}
98   ] if $attrs->{columns};
99   $attrs->{as} ||= [
100     map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
101   ];
102   if (my $include = delete $attrs->{include_columns}) {
103     push(@{$attrs->{select}}, @$include);
104     push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
105   }
106   #use Data::Dumper; warn Dumper(@{$attrs}{qw/select as/});
107
108   $attrs->{from} ||= [ { $alias => $source->from } ];
109   $attrs->{seen_join} ||= {};
110   my %seen;
111   if (my $join = delete $attrs->{join}) {
112     foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
113       if (ref $j eq 'HASH') {
114         $seen{$_} = 1 foreach keys %$j;
115       } else {
116         $seen{$j} = 1;
117       }
118     }
119     push(@{$attrs->{from}}, $source->resolve_join(
120       $join, $attrs->{alias}, $attrs->{seen_join})
121     );
122   }
123   
124   $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
125   $attrs->{order_by} = [ $attrs->{order_by} ] if
126     $attrs->{order_by} and !ref($attrs->{order_by});
127   $attrs->{order_by} ||= [];
128
129   my $collapse = $attrs->{collapse} || {};
130   if (my $prefetch = delete $attrs->{prefetch}) {
131     my @pre_order;
132     foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
133       if ( ref $p eq 'HASH' ) {
134         foreach my $key (keys %$p) {
135           push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
136             unless $seen{$key};
137         }
138       } else {
139         push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
140             unless $seen{$p};
141       }
142       my @prefetch = $source->resolve_prefetch(
143            $p, $attrs->{alias}, {}, \@pre_order, $collapse);
144       push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
145       push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
146     }
147     push(@{$attrs->{order_by}}, @pre_order);
148   }
149   $attrs->{collapse} = $collapse;
150 #  use Data::Dumper; warn Dumper($collapse) if keys %{$collapse};
151
152   if ($attrs->{page}) {
153     $attrs->{rows} ||= 10;
154     $attrs->{offset} ||= 0;
155     $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
156   }
157
158   bless {
159     result_source => $source,
160     result_class => $attrs->{result_class} || $source->result_class,
161     cond => $attrs->{where},
162     from => $attrs->{from},
163     collapse => $collapse,
164     count => undef,
165     page => delete $attrs->{page},
166     pager => undef,
167     attrs => $attrs
168   }, $class;
169 }
170
171 =head2 search
172
173 =over 4
174
175 =item Arguments: $cond, \%attrs?
176
177 =item Return Value: $resultset (scalar context), @row_objs (list context)
178
179 =back
180
181   my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
182   my $new_rs = $cd_rs->search({ year => 2005 });
183
184   my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
185                  # year = 2005 OR year = 2004
186
187 If you need to pass in additional attributes but no additional condition,
188 call it as C<search(undef, \%attrs)>.
189
190   # "SELECT name, artistid FROM $artist_table"
191   my @all_artists = $schema->resultset('Artist')->search(undef, {
192     columns => [qw/name artistid/],
193   });
194
195 =cut
196
197 sub search {
198   my $self = shift;
199   my $rs = $self->search_rs( @_ );
200   return (wantarray ? $rs->all : $rs);
201 }
202
203 =head2 search_rs
204
205 =over 4
206
207 =item Arguments: $cond, \%attrs?
208
209 =item Return Value: $resultset
210
211 =back
212
213 This method does the same exact thing as search() except it will 
214 always return a resultset, even in list context.
215
216 =cut
217
218 sub search_rs {
219   my $self = shift;
220
221   my $attrs = { %{$self->{attrs}} };
222   my $having = delete $attrs->{having};
223   $attrs = { %$attrs, %{ pop(@_) } } if @_ > 1 and ref $_[$#_] eq 'HASH';
224
225   my $where = (@_
226                 ? ((@_ == 1 || ref $_[0] eq "HASH")
227                     ? shift
228                     : ((@_ % 2)
229                         ? $self->throw_exception(
230                             "Odd number of arguments to search")
231                         : {@_}))
232                 : undef());
233   if (defined $where) {
234     $attrs->{where} = (defined $attrs->{where}
235               ? { '-and' =>
236                   [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
237                       $where, $attrs->{where} ] }
238               : $where);
239   }
240
241   if (defined $having) {
242     $attrs->{having} = (defined $attrs->{having}
243               ? { '-and' =>
244                   [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
245                       $having, $attrs->{having} ] }
246               : $having);
247   }
248
249   my $rs = (ref $self)->new($self->result_source, $attrs);
250
251   unless (@_) { # no search, effectively just a clone
252     my $rows = $self->get_cache;
253     if ($rows) {
254       $rs->set_cache($rows);
255     }
256   }
257   
258   return $rs;
259 }
260
261 =head2 search_literal
262
263 =over 4
264
265 =item Arguments: $sql_fragment, @bind_values
266
267 =item Return Value: $resultset (scalar context), @row_objs (list context)
268
269 =back
270
271   my @cds   = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
272   my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
273
274 Pass a literal chunk of SQL to be added to the conditional part of the
275 resultset query.
276
277 =cut
278
279 sub search_literal {
280   my ($self, $cond, @vals) = @_;
281   my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
282   $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
283   return $self->search(\$cond, $attrs);
284 }
285
286 =head2 find
287
288 =over 4
289
290 =item Arguments: @values | \%cols, \%attrs?
291
292 =item Return Value: $row_object
293
294 =back
295
296 Finds a row based on its primary key or unique constraint. For example, to find
297 a row by its primary key:
298
299   my $cd = $schema->resultset('CD')->find(5);
300
301 You can also find a row by a specific unique constraint using the C<key>
302 attribute. For example:
303
304   my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', { key => 'artist_title' });
305
306 Additionally, you can specify the columns explicitly by name:
307
308   my $cd = $schema->resultset('CD')->find(
309     {
310       artist => 'Massive Attack',
311       title  => 'Mezzanine',
312     },
313     { key => 'artist_title' }
314   );
315
316 If no C<key> is specified and you explicitly name columns, it searches on all
317 unique constraints defined on the source, including the primary key.
318
319 If the C<key> is specified as C<primary>, it searches only on the primary key.
320
321 See also L</find_or_create> and L</update_or_create>. For information on how to
322 declare unique constraints, see
323 L<DBIx::Class::ResultSource/add_unique_constraint>.
324
325 =cut
326
327 sub find {
328   my $self = shift;
329   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
330
331   # Parse out a hash from input
332   my @cols = exists $attrs->{key}
333     ? $self->result_source->unique_constraint_columns($attrs->{key})
334     : $self->result_source->primary_columns;
335
336   my $hash;
337   if (ref $_[0] eq 'HASH') {
338     $hash = { %{$_[0]} };
339   }
340   elsif (@_ == @cols) {
341     $hash = {};
342     @{$hash}{@cols} = @_;
343   }
344   elsif (@_) {
345     # For backwards compatibility
346     $hash = {@_};
347   }
348   else {
349     $self->throw_exception(
350       "Arguments to find must be a hashref or match the number of columns in the "
351         . (exists $attrs->{key} ? "$attrs->{key} unique constraint" : "primary key")
352     );
353   }
354
355   # Check the hash we just parsed against our source's unique constraints
356   my @constraint_names = exists $attrs->{key}
357     ? ($attrs->{key})
358     : $self->result_source->unique_constraint_names;
359   $self->throw_exception(
360     "Can't find unless a primary key or unique constraint is defined"
361   ) unless @constraint_names;
362
363   my @unique_queries;
364   foreach my $name (@constraint_names) {
365     my @unique_cols = $self->result_source->unique_constraint_columns($name);
366     my $unique_query = $self->_build_unique_query($hash, \@unique_cols);
367
368     # Add the ResultSet's alias
369     foreach my $key (grep { ! m/\./ } keys %$unique_query) {
370       $unique_query->{"$self->{attrs}{alias}.$key"} = delete $unique_query->{$key};
371     }
372
373     push @unique_queries, $unique_query if %$unique_query;
374   }
375
376   # Handle cases where the ResultSet already defines the query
377   my $query = @unique_queries ? \@unique_queries : undef;
378
379   # Run the query
380   if (keys %$attrs) {
381     my $rs = $self->search($query, $attrs);
382     return keys %{$rs->{collapse}} ? $rs->next : $rs->single;
383   }
384   else {
385     return keys %{$self->{collapse}}
386       ? $self->search($query)->next
387       : $self->single($query);
388   }
389 }
390
391 # _build_unique_query
392 #
393 # Constrain the specified query hash based on the specified column names.
394
395 sub _build_unique_query {
396   my ($self, $query, $unique_cols) = @_;
397
398   my %unique_query =
399     map  { $_ => $query->{$_} }
400     grep { exists $query->{$_} }
401     @$unique_cols;
402
403   return \%unique_query;
404 }
405
406 =head2 search_related
407
408 =over 4
409
410 =item Arguments: $cond, \%attrs?
411
412 =item Return Value: $new_resultset
413
414 =back
415
416   $new_rs = $cd_rs->search_related('artist', {
417     name => 'Emo-R-Us',
418   });
419
420 Searches the specified relationship, optionally specifying a condition and
421 attributes for matching records. See L</ATTRIBUTES> for more information.
422
423 =cut
424
425 sub search_related {
426   return shift->related_resultset(shift)->search(@_);
427 }
428
429 =head2 cursor
430
431 =over 4
432
433 =item Arguments: none
434
435 =item Return Value: $cursor
436
437 =back
438
439 Returns a storage-driven cursor to the given resultset. See
440 L<DBIx::Class::Cursor> for more information.
441
442 =cut
443
444 sub cursor {
445   my ($self) = @_;
446   my $attrs = { %{$self->{attrs}} };
447   return $self->{cursor}
448     ||= $self->result_source->storage->select($self->{from}, $attrs->{select},
449           $attrs->{where},$attrs);
450 }
451
452 =head2 single
453
454 =over 4
455
456 =item Arguments: $cond?
457
458 =item Return Value: $row_object?
459
460 =back
461
462   my $cd = $schema->resultset('CD')->single({ year => 2001 });
463
464 Inflates the first result without creating a cursor if the resultset has
465 any records in it; if not returns nothing. Used by L</find> as an optimisation.
466
467 Can optionally take an additional condition *only* - this is a fast-code-path
468 method; if you need to add extra joins or similar call ->search and then
469 ->single without a condition on the $rs returned from that.
470
471 =cut
472
473 sub single {
474   my ($self, $where) = @_;
475   my $attrs = { %{$self->{attrs}} };
476   if ($where) {
477     if (defined $attrs->{where}) {
478       $attrs->{where} = {
479         '-and' =>
480             [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
481                $where, delete $attrs->{where} ]
482       };
483     } else {
484       $attrs->{where} = $where;
485     }
486   }
487   my @data = $self->result_source->storage->select_single(
488           $self->{from}, $attrs->{select},
489           $attrs->{where},$attrs);
490   return (@data ? $self->_construct_object(@data) : ());
491 }
492
493 =head2 get_column
494
495 =over 4
496
497 =item Arguments: $cond?
498
499 =item Return Value: $resultsetcolumn
500
501 =back
502
503   my $max_length = $rs->get_column('length')->max;
504
505 Returns a ResultSetColumn instance for $column based on $self
506
507 =cut
508
509 sub get_column {
510   my ($self, $column) = @_;
511
512   my $new = DBIx::Class::ResultSetColumn->new($self, $column);
513   return $new;
514 }
515
516 =head2 search_like
517
518 =over 4
519
520 =item Arguments: $cond, \%attrs?
521
522 =item Return Value: $resultset (scalar context), @row_objs (list context)
523
524 =back
525
526   # WHERE title LIKE '%blue%'
527   $cd_rs = $rs->search_like({ title => '%blue%'});
528
529 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
530 that this is simply a convenience method. You most likely want to use
531 L</search> with specific operators.
532
533 For more information, see L<DBIx::Class::Manual::Cookbook>.
534
535 =cut
536
537 sub search_like {
538   my $class = shift;
539   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
540   my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
541   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
542   return $class->search($query, { %$attrs });
543 }
544
545 =head2 slice
546
547 =over 4
548
549 =item Arguments: $first, $last
550
551 =item Return Value: $resultset (scalar context), @row_objs (list context)
552
553 =back
554
555 Returns a resultset or object list representing a subset of elements from the
556 resultset slice is called on. Indexes are from 0, i.e., to get the first
557 three records, call:
558
559   my ($one, $two, $three) = $rs->slice(0, 2);
560
561 =cut
562
563 sub slice {
564   my ($self, $min, $max) = @_;
565   my $attrs = {}; # = { %{ $self->{attrs} || {} } };
566   $attrs->{offset} = $self->{attrs}{offset} || 0;
567   $attrs->{offset} += $min;
568   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
569   return $self->search(undef(), $attrs);
570   #my $slice = (ref $self)->new($self->result_source, $attrs);
571   #return (wantarray ? $slice->all : $slice);
572 }
573
574 =head2 next
575
576 =over 4
577
578 =item Arguments: none
579
580 =item Return Value: $result?
581
582 =back
583
584 Returns the next element in the resultset (C<undef> is there is none).
585
586 Can be used to efficiently iterate over records in the resultset:
587
588   my $rs = $schema->resultset('CD')->search;
589   while (my $cd = $rs->next) {
590     print $cd->title;
591   }
592
593 Note that you need to store the resultset object, and call C<next> on it. 
594 Calling C<< resultset('Table')->next >> repeatedly will always return the
595 first record from the resultset.
596
597 =cut
598
599 sub next {
600   my ($self) = @_;
601   if (my $cache = $self->get_cache) {
602     $self->{all_cache_position} ||= 0;
603     return $cache->[$self->{all_cache_position}++];
604   }
605   if ($self->{attrs}{cache}) {
606     $self->{all_cache_position} = 1;
607     return ($self->all)[0];
608   }
609   my @row = (exists $self->{stashed_row} ?
610                @{delete $self->{stashed_row}} :
611                $self->cursor->next
612   );
613 #  warn Dumper(\@row); use Data::Dumper;
614   return unless (@row);
615   return $self->_construct_object(@row);
616 }
617
618 sub _construct_object {
619   my ($self, @row) = @_;
620   my @as = @{ $self->{attrs}{as} };
621   
622   my $info = $self->_collapse_result(\@as, \@row);
623   
624   my $new = $self->result_class->inflate_result($self->result_source, @$info);
625   
626   $new = $self->{attrs}{record_filter}->($new)
627     if exists $self->{attrs}{record_filter};
628   return $new;
629 }
630
631 sub _collapse_result {
632   my ($self, $as, $row, $prefix) = @_;
633
634   my %const;
635
636   my @copy = @$row;
637   foreach my $this_as (@$as) {
638     my $val = shift @copy;
639     if (defined $prefix) {
640       if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
641         my $remain = $1;
642         $remain =~ /^(?:(.*)\.)?([^.]+)$/;
643         $const{$1||''}{$2} = $val;
644       }
645     } else {
646       $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
647       $const{$1||''}{$2} = $val;
648     }
649   }
650
651   my $info = [ {}, {} ];
652   foreach my $key (keys %const) {
653     if (length $key) {
654       my $target = $info;
655       my @parts = split(/\./, $key);
656       foreach my $p (@parts) {
657         $target = $target->[1]->{$p} ||= [];
658       }
659       $target->[0] = $const{$key};
660     } else {
661       $info->[0] = $const{$key};
662     }
663   }
664
665   my @collapse;
666   if (defined $prefix) {
667     @collapse = map {
668         m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
669     } keys %{$self->{collapse}}
670   } else {
671     @collapse = keys %{$self->{collapse}};
672   };
673
674   if (@collapse) {
675     my ($c) = sort { length $a <=> length $b } @collapse;
676     my $target = $info;
677     foreach my $p (split(/\./, $c)) {
678       $target = $target->[1]->{$p} ||= [];
679     }
680     my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
681     my @co_key = @{$self->{collapse}{$c_prefix}};
682     my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
683     my $tree = $self->_collapse_result($as, $row, $c_prefix);
684     my (@final, @raw);
685     while ( !(grep {
686                 !defined($tree->[0]->{$_}) ||
687                 $co_check{$_} ne $tree->[0]->{$_}
688               } @co_key) ) {
689       push(@final, $tree);
690       last unless (@raw = $self->cursor->next);
691       $row = $self->{stashed_row} = \@raw;
692       $tree = $self->_collapse_result($as, $row, $c_prefix);
693     }
694     @$target = (@final ? @final : [ {}, {} ]);
695       # single empty result to indicate an empty prefetched has_many
696   }
697
698   return $info;
699 }
700
701 =head2 result_source
702
703 =over 4
704
705 =item Arguments: $result_source?
706
707 =item Return Value: $result_source
708
709 =back
710
711 An accessor for the primary ResultSource object from which this ResultSet
712 is derived.
713
714 =cut
715
716
717 =head2 count
718
719 =over 4
720
721 =item Arguments: $cond, \%attrs??
722
723 =item Return Value: $count
724
725 =back
726
727 Performs an SQL C<COUNT> with the same query as the resultset was built
728 with to find the number of elements. If passed arguments, does a search
729 on the resultset and counts the results of that.
730
731 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
732 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
733 not support C<DISTINCT> with multiple columns. If you are using such a
734 database, you should only use columns from the main table in your C<group_by>
735 clause.
736
737 =cut
738
739 sub count {
740   my $self = shift;
741   return $self->search(@_)->count if @_ and defined $_[0];
742   return scalar @{ $self->get_cache } if $self->get_cache;
743
744   my $count = $self->_count;
745   return 0 unless $count;
746
747   $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
748   $count = $self->{attrs}{rows} if
749     $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
750   return $count;
751 }
752
753 sub _count { # Separated out so pager can get the full count
754   my $self = shift;
755   my $select = { count => '*' };
756   my $attrs = { %{ $self->{attrs} } };
757   if (my $group_by = delete $attrs->{group_by}) {
758     delete $attrs->{having};
759     my @distinct = (ref $group_by ?  @$group_by : ($group_by));
760     # todo: try CONCAT for multi-column pk
761     my @pk = $self->result_source->primary_columns;
762     if (@pk == 1) {
763       foreach my $column (@distinct) {
764         if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
765           @distinct = ($column);
766           last;
767         }
768       }
769     }
770
771     $select = { count => { distinct => \@distinct } };
772     #use Data::Dumper; die Dumper $select;
773   }
774
775   $attrs->{select} = $select;
776   $attrs->{as} = [qw/count/];
777
778   # offset, order by and page are not needed to count. record_filter is cdbi
779   delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
780         
781   my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
782   return $count;
783 }
784
785 =head2 count_literal
786
787 =over 4
788
789 =item Arguments: $sql_fragment, @bind_values
790
791 =item Return Value: $count
792
793 =back
794
795 Counts the results in a literal query. Equivalent to calling L</search_literal>
796 with the passed arguments, then L</count>.
797
798 =cut
799
800 sub count_literal { shift->search_literal(@_)->count; }
801
802 =head2 all
803
804 =over 4
805
806 =item Arguments: none
807
808 =item Return Value: @objects
809
810 =back
811
812 Returns all elements in the resultset. Called implicitly if the resultset
813 is returned in list context.
814
815 =cut
816
817 sub all {
818   my ($self) = @_;
819   return @{ $self->get_cache } if $self->get_cache;
820
821   my @obj;
822
823   if (keys %{$self->{collapse}}) {
824       # Using $self->cursor->all is really just an optimisation.
825       # If we're collapsing has_many prefetches it probably makes
826       # very little difference, and this is cleaner than hacking
827       # _construct_object to survive the approach
828     $self->cursor->reset;
829     my @row = $self->cursor->next;
830     while (@row) {
831       push(@obj, $self->_construct_object(@row));
832       @row = (exists $self->{stashed_row}
833                ? @{delete $self->{stashed_row}}
834                : $self->cursor->next);
835     }
836   } else {
837     @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
838   }
839
840   $self->set_cache(\@obj) if $self->{attrs}{cache};
841   return @obj;
842 }
843
844 =head2 reset
845
846 =over 4
847
848 =item Arguments: none
849
850 =item Return Value: $self
851
852 =back
853
854 Resets the resultset's cursor, so you can iterate through the elements again.
855
856 =cut
857
858 sub reset {
859   my ($self) = @_;
860   $self->{all_cache_position} = 0;
861   $self->cursor->reset;
862   return $self;
863 }
864
865 =head2 first
866
867 =over 4
868
869 =item Arguments: none
870
871 =item Return Value: $object?
872
873 =back
874
875 Resets the resultset and returns an object for the first result (if the
876 resultset returns anything).
877
878 =cut
879
880 sub first {
881   return $_[0]->reset->next;
882 }
883
884 # _cond_for_update_delete
885 #
886 # update/delete require the condition to be modified to handle
887 # the differing SQL syntax available.  This transforms the $self->{cond}
888 # appropriately, returning the new condition.
889
890 sub _cond_for_update_delete {
891   my ($self) = @_;
892   my $cond = {};
893
894   if (!ref($self->{cond})) {
895     # No-op. No condition, we're updating/deleting everything
896   }
897   elsif (ref $self->{cond} eq 'ARRAY') {
898     $cond = [
899       map {
900         my %hash;
901         foreach my $key (keys %{$_}) {
902           $key =~ /([^.]+)$/;
903           $hash{$1} = $_->{$key};
904         }
905         \%hash;
906       } @{$self->{cond}}
907     ];
908   }
909   elsif (ref $self->{cond} eq 'HASH') {
910     if ((keys %{$self->{cond}})[0] eq '-and') {
911       $cond->{-and} = [];
912
913       my @cond = @{$self->{cond}{-and}};
914       for (my $i = 0; $i < @cond - 1; $i++) {
915         my $entry = $cond[$i];
916
917         my %hash;
918         if (ref $entry eq 'HASH') {
919           foreach my $key (keys %{$entry}) {
920             $key =~ /([^.]+)$/;
921             $hash{$1} = $entry->{$key};
922           }
923         }
924         else {
925           $entry =~ /([^.]+)$/;
926           $hash{$entry} = $cond[++$i];
927         }
928
929         push @{$cond->{-and}}, \%hash;
930       }
931     }
932     else {
933       foreach my $key (keys %{$self->{cond}}) {
934         $key =~ /([^.]+)$/;
935         $cond->{$1} = $self->{cond}{$key};
936       }
937     }
938   }
939   else {
940     $self->throw_exception(
941       "Can't update/delete on resultset with condition unless hash or array"
942     );
943   }
944
945   return $cond;
946 }
947
948
949 =head2 update
950
951 =over 4
952
953 =item Arguments: \%values
954
955 =item Return Value: $storage_rv
956
957 =back
958
959 Sets the specified columns in the resultset to the supplied values in a
960 single query. Return value will be true if the update succeeded or false
961 if no records were updated; exact type of success value is storage-dependent.
962
963 =cut
964
965 sub update {
966   my ($self, $values) = @_;
967   $self->throw_exception("Values for update must be a hash")
968     unless ref $values eq 'HASH';
969
970   my $cond = $self->_cond_for_update_delete;
971
972   return $self->result_source->storage->update(
973     $self->result_source->from, $values, $cond
974   );
975 }
976
977 =head2 update_all
978
979 =over 4
980
981 =item Arguments: \%values
982
983 =item Return Value: 1
984
985 =back
986
987 Fetches all objects and updates them one at a time. Note that C<update_all>
988 will run DBIC cascade triggers, while L</update> will not.
989
990 =cut
991
992 sub update_all {
993   my ($self, $values) = @_;
994   $self->throw_exception("Values for update must be a hash")
995     unless ref $values eq 'HASH';
996   foreach my $obj ($self->all) {
997     $obj->set_columns($values)->update;
998   }
999   return 1;
1000 }
1001
1002 =head2 delete
1003
1004 =over 4
1005
1006 =item Arguments: none
1007
1008 =item Return Value: 1
1009
1010 =back
1011
1012 Deletes the contents of the resultset from its result source. Note that this
1013 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1014 to run.
1015
1016 =cut
1017
1018 sub delete {
1019   my ($self) = @_;
1020   my $del = {};
1021
1022   my $cond = $self->_cond_for_update_delete;
1023
1024   $self->result_source->storage->delete($self->result_source->from, $cond);
1025   return 1;
1026 }
1027
1028 =head2 delete_all
1029
1030 =over 4
1031
1032 =item Arguments: none
1033
1034 =item Return Value: 1
1035
1036 =back
1037
1038 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1039 will run DBIC cascade triggers, while L</delete> will not.
1040
1041 =cut
1042
1043 sub delete_all {
1044   my ($self) = @_;
1045   $_->delete for $self->all;
1046   return 1;
1047 }
1048
1049 =head2 pager
1050
1051 =over 4
1052
1053 =item Arguments: none
1054
1055 =item Return Value: $pager
1056
1057 =back
1058
1059 Return Value a L<Data::Page> object for the current resultset. Only makes
1060 sense for queries with a C<page> attribute.
1061
1062 =cut
1063
1064 sub pager {
1065   my ($self) = @_;
1066   my $attrs = $self->{attrs};
1067   $self->throw_exception("Can't create pager for non-paged rs")
1068     unless $self->{page};
1069   $attrs->{rows} ||= 10;
1070   return $self->{pager} ||= Data::Page->new(
1071     $self->_count, $attrs->{rows}, $self->{page});
1072 }
1073
1074 =head2 page
1075
1076 =over 4
1077
1078 =item Arguments: $page_number
1079
1080 =item Return Value: $rs
1081
1082 =back
1083
1084 Returns a resultset for the $page_number page of the resultset on which page
1085 is called, where each page contains a number of rows equal to the 'rows'
1086 attribute set on the resultset (10 by default).
1087
1088 =cut
1089
1090 sub page {
1091   my ($self, $page) = @_;
1092   my $attrs = { %{$self->{attrs}} };
1093   $attrs->{page} = $page;
1094   return (ref $self)->new($self->result_source, $attrs);
1095 }
1096
1097 =head2 new_result
1098
1099 =over 4
1100
1101 =item Arguments: \%vals
1102
1103 =item Return Value: $object
1104
1105 =back
1106
1107 Creates an object in the resultset's result class and returns it.
1108
1109 =cut
1110
1111 sub new_result {
1112   my ($self, $values) = @_;
1113   $self->throw_exception( "new_result needs a hash" )
1114     unless (ref $values eq 'HASH');
1115   $self->throw_exception(
1116     "Can't abstract implicit construct, condition not a hash"
1117   ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1118   my %new = %$values;
1119   my $alias = $self->{attrs}{alias};
1120   foreach my $key (keys %{$self->{cond}||{}}) {
1121     $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1122   }
1123   my $obj = $self->result_class->new(\%new);
1124   $obj->result_source($self->result_source) if $obj->can('result_source');
1125   return $obj;
1126 }
1127
1128 =head2 find_or_new
1129
1130 =over 4
1131
1132 =item Arguments: \%vals, \%attrs?
1133
1134 =item Return Value: $object
1135
1136 =back
1137
1138 Find an existing record from this resultset. If none exists, instantiate a new
1139 result object and return it. The object will not be saved into your storage
1140 until you call L<DBIx::Class::Row/insert> on it.
1141
1142 If you want objects to be saved immediately, use L</find_or_create> instead.
1143
1144 =cut
1145
1146 sub find_or_new {
1147   my $self     = shift;
1148   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1149   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1150   my $exists   = $self->find($hash, $attrs);
1151   return defined $exists ? $exists : $self->new_result($hash);
1152 }
1153
1154 =head2 create
1155
1156 =over 4
1157
1158 =item Arguments: \%vals
1159
1160 =item Return Value: $object
1161
1162 =back
1163
1164 Inserts a record into the resultset and returns the object representing it.
1165
1166 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1167
1168 =cut
1169
1170 sub create {
1171   my ($self, $attrs) = @_;
1172   $self->throw_exception( "create needs a hashref" )
1173     unless ref $attrs eq 'HASH';
1174   return $self->new_result($attrs)->insert;
1175 }
1176
1177 =head2 find_or_create
1178
1179 =over 4
1180
1181 =item Arguments: \%vals, \%attrs?
1182
1183 =item Return Value: $object
1184
1185 =back
1186
1187   $class->find_or_create({ key => $val, ... });
1188
1189 Searches for a record matching the search condition; if it doesn't find one,
1190 creates one and returns that instead.
1191
1192   my $cd = $schema->resultset('CD')->find_or_create({
1193     cdid   => 5,
1194     artist => 'Massive Attack',
1195     title  => 'Mezzanine',
1196     year   => 2005,
1197   });
1198
1199 Also takes an optional C<key> attribute, to search by a specific key or unique
1200 constraint. For example:
1201
1202   my $cd = $schema->resultset('CD')->find_or_create(
1203     {
1204       artist => 'Massive Attack',
1205       title  => 'Mezzanine',
1206     },
1207     { key => 'artist_title' }
1208   );
1209
1210 See also L</find> and L</update_or_create>. For information on how to declare
1211 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1212
1213 =cut
1214
1215 sub find_or_create {
1216   my $self     = shift;
1217   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1218   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1219   my $exists   = $self->find($hash, $attrs);
1220   return defined $exists ? $exists : $self->create($hash);
1221 }
1222
1223 =head2 update_or_create
1224
1225 =over 4
1226
1227 =item Arguments: \%col_values, { key => $unique_constraint }?
1228
1229 =item Return Value: $object
1230
1231 =back
1232
1233   $class->update_or_create({ col => $val, ... });
1234
1235 First, searches for an existing row matching one of the unique constraints
1236 (including the primary key) on the source of this resultset. If a row is
1237 found, updates it with the other given column values. Otherwise, creates a new
1238 row.
1239
1240 Takes an optional C<key> attribute to search on a specific unique constraint.
1241 For example:
1242
1243   # In your application
1244   my $cd = $schema->resultset('CD')->update_or_create(
1245     {
1246       artist => 'Massive Attack',
1247       title  => 'Mezzanine',
1248       year   => 1998,
1249     },
1250     { key => 'artist_title' }
1251   );
1252
1253 If no C<key> is specified, it searches on all unique constraints defined on the
1254 source, including the primary key.
1255
1256 If the C<key> is specified as C<primary>, it searches only on the primary key.
1257
1258 See also L</find> and L</find_or_create>. For information on how to declare
1259 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1260
1261 =cut
1262
1263 sub update_or_create {
1264   my $self = shift;
1265   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1266   my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1267
1268   my $row = $self->find($hash, $attrs);
1269   if (defined $row) {
1270     $row->update($hash);
1271     return $row;
1272   }
1273
1274   return $self->create($hash);
1275 }
1276
1277 =head2 get_cache
1278
1279 =over 4
1280
1281 =item Arguments: none
1282
1283 =item Return Value: \@cache_objects?
1284
1285 =back
1286
1287 Gets the contents of the cache for the resultset, if the cache is set.
1288
1289 =cut
1290
1291 sub get_cache {
1292   shift->{all_cache};
1293 }
1294
1295 =head2 set_cache
1296
1297 =over 4
1298
1299 =item Arguments: \@cache_objects
1300
1301 =item Return Value: \@cache_objects
1302
1303 =back
1304
1305 Sets the contents of the cache for the resultset. Expects an arrayref
1306 of objects of the same class as those produced by the resultset. Note that
1307 if the cache is set the resultset will return the cached objects rather
1308 than re-querying the database even if the cache attr is not set.
1309
1310 =cut
1311
1312 sub set_cache {
1313   my ( $self, $data ) = @_;
1314   $self->throw_exception("set_cache requires an arrayref")
1315     if defined($data) && (ref $data ne 'ARRAY');
1316   $self->{all_cache} = $data;
1317 }
1318
1319 =head2 clear_cache
1320
1321 =over 4
1322
1323 =item Arguments: none
1324
1325 =item Return Value: []
1326
1327 =back
1328
1329 Clears the cache for the resultset.
1330
1331 =cut
1332
1333 sub clear_cache {
1334   shift->set_cache(undef);
1335 }
1336
1337 =head2 related_resultset
1338
1339 =over 4
1340
1341 =item Arguments: $relationship_name
1342
1343 =item Return Value: $resultset
1344
1345 =back
1346
1347 Returns a related resultset for the supplied relationship name.
1348
1349   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1350
1351 =cut
1352
1353 sub related_resultset {
1354   my ( $self, $rel ) = @_;
1355   $self->{related_resultsets} ||= {};
1356   return $self->{related_resultsets}{$rel} ||= do {
1357       #warn "fetching related resultset for rel '$rel'";
1358       my $rel_obj = $self->result_source->relationship_info($rel);
1359       $self->throw_exception(
1360         "search_related: result source '" . $self->result_source->name .
1361         "' has no such relationship ${rel}")
1362         unless $rel_obj; #die Dumper $self->{attrs};
1363
1364       my $rs = $self->search(undef, { join => $rel });
1365       my $alias = defined $rs->{attrs}{seen_join}{$rel}
1366                     && $rs->{attrs}{seen_join}{$rel} > 1
1367                   ? join('_', $rel, $rs->{attrs}{seen_join}{$rel})
1368                   : $rel;
1369
1370       $self->result_source->schema->resultset($rel_obj->{class}
1371            )->search( undef,
1372              { %{$rs->{attrs}},
1373                alias => $alias,
1374                select => undef,
1375                as => undef }
1376            );
1377   };
1378 }
1379
1380 =head2 throw_exception
1381
1382 See L<DBIx::Class::Schema/throw_exception> for details.
1383
1384 =cut
1385
1386 sub throw_exception {
1387   my $self=shift;
1388   $self->result_source->schema->throw_exception(@_);
1389 }
1390
1391 # XXX: FIXME: Attributes docs need clearing up
1392
1393 =head1 ATTRIBUTES
1394
1395 The resultset takes various attributes that modify its behavior. Here's an
1396 overview of them:
1397
1398 =head2 order_by
1399
1400 =over 4
1401
1402 =item Value: ($order_by | \@order_by)
1403
1404 =back
1405
1406 Which column(s) to order the results by. This is currently passed
1407 through directly to SQL, so you can give e.g. C<year DESC> for a
1408 descending order on the column `year'.
1409
1410 =head2 columns
1411
1412 =over 4
1413
1414 =item Value: \@columns
1415
1416 =back
1417
1418 Shortcut to request a particular set of columns to be retrieved.  Adds
1419 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1420 from that, then auto-populates C<as> from C<select> as normal. (You may also
1421 use the C<cols> attribute, as in earlier versions of DBIC.)
1422
1423 =head2 include_columns
1424
1425 =over 4
1426
1427 =item Value: \@columns
1428
1429 =back
1430
1431 Shortcut to include additional columns in the returned results - for example
1432
1433   $schema->resultset('CD')->search(undef, {
1434     include_columns => ['artist.name'],
1435     join => ['artist']
1436   });
1437
1438 would return all CDs and include a 'name' column to the information
1439 passed to object inflation
1440
1441 =head2 select
1442
1443 =over 4
1444
1445 =item Value: \@select_columns
1446
1447 =back
1448
1449 Indicates which columns should be selected from the storage. You can use
1450 column names, or in the case of RDBMS back ends, function or stored procedure
1451 names:
1452
1453   $rs = $schema->resultset('Employee')->search(undef, {
1454     select => [
1455       'name',
1456       { count => 'employeeid' },
1457       { sum => 'salary' }
1458     ]
1459   });
1460
1461 When you use function/stored procedure names and do not supply an C<as>
1462 attribute, the column names returned are storage-dependent. E.g. MySQL would
1463 return a column named C<count(employeeid)> in the above example.
1464
1465 =head2 as
1466
1467 =over 4
1468
1469 =item Value: \@inflation_names
1470
1471 =back
1472
1473 Indicates column names for object inflation. This is used in conjunction with
1474 C<select>, usually when C<select> contains one or more function or stored
1475 procedure names:
1476
1477   $rs = $schema->resultset('Employee')->search(undef, {
1478     select => [
1479       'name',
1480       { count => 'employeeid' }
1481     ],
1482     as => ['name', 'employee_count'],
1483   });
1484
1485   my $employee = $rs->first(); # get the first Employee
1486
1487 If the object against which the search is performed already has an accessor
1488 matching a column name specified in C<as>, the value can be retrieved using
1489 the accessor as normal:
1490
1491   my $name = $employee->name();
1492
1493 If on the other hand an accessor does not exist in the object, you need to
1494 use C<get_column> instead:
1495
1496   my $employee_count = $employee->get_column('employee_count');
1497
1498 You can create your own accessors if required - see
1499 L<DBIx::Class::Manual::Cookbook> for details.
1500
1501 Please note: This will NOT insert an C<AS employee_count> into the SQL statement
1502 produced, it is used for internal access only. Thus attempting to use the accessor
1503 in an C<order_by> clause or similar will fail misrably.
1504
1505 =head2 join
1506
1507 =over 4
1508
1509 =item Value: ($rel_name | \@rel_names | \%rel_names)
1510
1511 =back
1512
1513 Contains a list of relationships that should be joined for this query.  For
1514 example:
1515
1516   # Get CDs by Nine Inch Nails
1517   my $rs = $schema->resultset('CD')->search(
1518     { 'artist.name' => 'Nine Inch Nails' },
1519     { join => 'artist' }
1520   );
1521
1522 Can also contain a hash reference to refer to the other relation's relations.
1523 For example:
1524
1525   package MyApp::Schema::Track;
1526   use base qw/DBIx::Class/;
1527   __PACKAGE__->table('track');
1528   __PACKAGE__->add_columns(qw/trackid cd position title/);
1529   __PACKAGE__->set_primary_key('trackid');
1530   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1531   1;
1532
1533   # In your application
1534   my $rs = $schema->resultset('Artist')->search(
1535     { 'track.title' => 'Teardrop' },
1536     {
1537       join     => { cd => 'track' },
1538       order_by => 'artist.name',
1539     }
1540   );
1541
1542 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1543 similarly for a third time). For e.g.
1544
1545   my $rs = $schema->resultset('Artist')->search({
1546     'cds.title'   => 'Down to Earth',
1547     'cds_2.title' => 'Popular',
1548   }, {
1549     join => [ qw/cds cds/ ],
1550   });
1551
1552 will return a set of all artists that have both a cd with title 'Down
1553 to Earth' and a cd with title 'Popular'.
1554
1555 If you want to fetch related objects from other tables as well, see C<prefetch>
1556 below.
1557
1558 =head2 prefetch
1559
1560 =over 4
1561
1562 =item Value: ($rel_name | \@rel_names | \%rel_names)
1563
1564 =back
1565
1566 Contains one or more relationships that should be fetched along with the main
1567 query (when they are accessed afterwards they will have already been
1568 "prefetched").  This is useful for when you know you will need the related
1569 objects, because it saves at least one query:
1570
1571   my $rs = $schema->resultset('Tag')->search(
1572     undef,
1573     {
1574       prefetch => {
1575         cd => 'artist'
1576       }
1577     }
1578   );
1579
1580 The initial search results in SQL like the following:
1581
1582   SELECT tag.*, cd.*, artist.* FROM tag
1583   JOIN cd ON tag.cd = cd.cdid
1584   JOIN artist ON cd.artist = artist.artistid
1585
1586 L<DBIx::Class> has no need to go back to the database when we access the
1587 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1588 case.
1589
1590 Simple prefetches will be joined automatically, so there is no need
1591 for a C<join> attribute in the above search. If you're prefetching to
1592 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1593 specify the join as well.
1594
1595 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1596 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1597 with an accessor type of 'single' or 'filter').
1598
1599 =head2 page
1600
1601 =over 4
1602
1603 =item Value: $page
1604
1605 =back
1606
1607 Makes the resultset paged and specifies the page to retrieve. Effectively
1608 identical to creating a non-pages resultset and then calling ->page($page)
1609 on it.
1610
1611 =head2 rows
1612
1613 =over 4
1614
1615 =item Value: $rows
1616
1617 =back
1618
1619 Specifes the maximum number of rows for direct retrieval or the number of
1620 rows per page if the page attribute or method is used.
1621
1622 =head2 group_by
1623
1624 =over 4
1625
1626 =item Value: \@columns
1627
1628 =back
1629
1630 A arrayref of columns to group by. Can include columns of joined tables.
1631
1632   group_by => [qw/ column1 column2 ... /]
1633
1634 =head2 having
1635
1636 =over 4
1637
1638 =item Value: $condition
1639
1640 =back
1641
1642 HAVING is a select statement attribute that is applied between GROUP BY and
1643 ORDER BY. It is applied to the after the grouping calculations have been
1644 done. 
1645
1646   having => { 'count(employee)' => { '>=', 100 } }
1647
1648 =head2 distinct
1649
1650 =over 4
1651
1652 =item Value: (0 | 1)
1653
1654 =back
1655
1656 Set to 1 to group by all columns.
1657
1658 =head2 cache
1659
1660 Set to 1 to cache search results. This prevents extra SQL queries if you
1661 revisit rows in your ResultSet:
1662
1663   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1664   
1665   while( my $artist = $resultset->next ) {
1666     ... do stuff ...
1667   }
1668
1669   $rs->first; # without cache, this would issue a query
1670
1671 By default, searches are not cached.
1672
1673 For more examples of using these attributes, see
1674 L<DBIx::Class::Manual::Cookbook>.
1675
1676 =head2 from
1677
1678 =over 4
1679
1680 =item Value: \@from_clause
1681
1682 =back
1683
1684 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1685 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1686 clauses.
1687
1688 NOTE: Use this on your own risk.  This allows you to shoot off your foot!
1689
1690 C<join> will usually do what you need and it is strongly recommended that you
1691 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1692 And we really do mean "cannot", not just tried and failed. Attempting to use
1693 this because you're having problems with C<join> is like trying to use x86
1694 ASM because you've got a syntax error in your C. Trust us on this.
1695
1696 Now, if you're still really, really sure you need to use this (and if you're
1697 not 100% sure, ask the mailing list first), here's an explanation of how this
1698 works.
1699
1700 The syntax is as follows -
1701
1702   [
1703     { <alias1> => <table1> },
1704     [
1705       { <alias2> => <table2>, -join_type => 'inner|left|right' },
1706       [], # nested JOIN (optional)
1707       { <table1.column1> => <table2.column2>, ... (more conditions) },
1708     ],
1709     # More of the above [ ] may follow for additional joins
1710   ]
1711
1712   <table1> <alias1>
1713   JOIN
1714     <table2> <alias2>
1715     [JOIN ...]
1716   ON <table1.column1> = <table2.column2>
1717   <more joins may follow>
1718
1719 An easy way to follow the examples below is to remember the following:
1720
1721     Anything inside "[]" is a JOIN
1722     Anything inside "{}" is a condition for the enclosing JOIN
1723
1724 The following examples utilize a "person" table in a family tree application.
1725 In order to express parent->child relationships, this table is self-joined:
1726
1727     # Person->belongs_to('father' => 'Person');
1728     # Person->belongs_to('mother' => 'Person');
1729
1730 C<from> can be used to nest joins. Here we return all children with a father,
1731 then search against all mothers of those children:
1732
1733   $rs = $schema->resultset('Person')->search(
1734       undef,
1735       {
1736           alias => 'mother', # alias columns in accordance with "from"
1737           from => [
1738               { mother => 'person' },
1739               [
1740                   [
1741                       { child => 'person' },
1742                       [
1743                           { father => 'person' },
1744                           { 'father.person_id' => 'child.father_id' }
1745                       ]
1746                   ],
1747                   { 'mother.person_id' => 'child.mother_id' }
1748               ],
1749           ]
1750       },
1751   );
1752
1753   # Equivalent SQL:
1754   # SELECT mother.* FROM person mother
1755   # JOIN (
1756   #   person child
1757   #   JOIN person father
1758   #   ON ( father.person_id = child.father_id )
1759   # )
1760   # ON ( mother.person_id = child.mother_id )
1761
1762 The type of any join can be controlled manually. To search against only people
1763 with a father in the person table, we could explicitly use C<INNER JOIN>:
1764
1765     $rs = $schema->resultset('Person')->search(
1766         undef,
1767         {
1768             alias => 'child', # alias columns in accordance with "from"
1769             from => [
1770                 { child => 'person' },
1771                 [
1772                     { father => 'person', -join_type => 'inner' },
1773                     { 'father.id' => 'child.father_id' }
1774                 ],
1775             ]
1776         },
1777     );
1778
1779     # Equivalent SQL:
1780     # SELECT child.* FROM person child
1781     # INNER JOIN person father ON child.father_id = father.id
1782
1783 =cut
1784
1785 1;