lib/DBIx/Class/ResultSet.pm

   1 package DBIx::Class::ResultSet;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/DBIx::Class/;
   6 use DBIx::Class::Carp;
   7 use DBIx::Class::ResultSetColumn;
   8 use Scalar::Util qw/blessed weaken/;
   9 use Try::Tiny;
  10 use Data::Compare (); # no imports!!! guard against insane architecture
  11
  12 # not importing first() as it will clash with our own method
  13 use List::Util ();
  14
  15 BEGIN {
  16   # De-duplication in _merge_attr() is disabled, but left in for reference
  17   # (the merger is used for other things that ought not to be de-duped)
  18   *__HM_DEDUP = sub () { 0 };
  19 }
  20
  21 use namespace::clean;
  22
  23 use overload
  24         '0+'     => "count",
  25         'bool'   => "_bool",
  26         fallback => 1;
  27
  28 __PACKAGE__->mk_group_accessors('simple' => qw/_result_class result_source/);
  29
  30 =head1 NAME
  31
  32 DBIx::Class::ResultSet - Represents a query used for fetching a set of results.
  33
  34 =head1 SYNOPSIS
  35
  36   my $users_rs = $schema->resultset('User');
  37   while( $user = $users_rs->next) {
  38     print $user->username;
  39   }
  40
  41   my $registered_users_rs = $schema->resultset('User')->search({ registered => 1 });
  42   my @cds_in_2005 = $schema->resultset('CD')->search({ year => 2005 })->all();
  43
  44 =head1 DESCRIPTION
  45
  46 A ResultSet is an object which stores a set of conditions representing
  47 a query. It is the backbone of DBIx::Class (i.e. the really
  48 important/useful bit).
  49
  50 No SQL is executed on the database when a ResultSet is created, it
  51 just stores all the conditions needed to create the query.
  52
  53 A basic ResultSet representing the data of an entire table is returned
  54 by calling C<resultset> on a L<DBIx::Class::Schema> and passing in a
  55 L<Source|DBIx::Class::Manual::Glossary/Source> name.
  56
  57   my $users_rs = $schema->resultset('User');
  58
  59 A new ResultSet is returned from calling L</search> on an existing
  60 ResultSet. The new one will contain all the conditions of the
  61 original, plus any new conditions added in the C<search> call.
  62
  63 A ResultSet also incorporates an implicit iterator. L</next> and L</reset>
  64 can be used to walk through all the L<DBIx::Class::Row>s the ResultSet
  65 represents.
  66
  67 The query that the ResultSet represents is B<only> executed against
  68 the database when these methods are called:
  69 L</find>, L</next>, L</all>, L</first>, L</single>, L</count>.
  70
  71 If a resultset is used in a numeric context it returns the L</count>.
  72 However, if it is used in a boolean context it is B<always> true.  So if
  73 you want to check if a resultset has any results, you must use C<if $rs
  74 != 0>.
  75
  76 =head1 CUSTOM ResultSet CLASSES THAT USE Moose
  77
  78 If you want to make your custom ResultSet classes with L<Moose>, use a template
  79 similar to:
  80
  81     package MyApp::Schema::ResultSet::User;
  82
  83     use Moose;
  84     use namespace::autoclean;
  85     use MooseX::NonMoose;
  86     extends 'DBIx::Class::ResultSet';
  87
  88     sub BUILDARGS { $_[2] }
  89
  90     ...your code...
  91
  92     __PACKAGE__->meta->make_immutable;
  93
  94     1;
  95
  96 The L<MooseX::NonMoose> is necessary so that the L<Moose> constructor does not
  97 clash with the regular ResultSet constructor. Alternatively, you can use:
  98
  99     __PACKAGE__->meta->make_immutable(inline_constructor => 0);
 100
 101 The L<BUILDARGS|Moose::Manual::Construction/BUILDARGS> is necessary because the
 102 signature of the ResultSet C<new> is C<< ->new($source, \%args) >>.
 103
 104 =head1 EXAMPLES
 105
 106 =head2 Chaining resultsets
 107
 108 Let's say you've got a query that needs to be run to return some data
 109 to the user. But, you have an authorization system in place that
 110 prevents certain users from seeing certain information. So, you want
 111 to construct the basic query in one method, but add constraints to it in
 112 another.
 113
 114   sub get_data {
 115     my $self = shift;
 116     my $request = $self->get_request; # Get a request object somehow.
 117     my $schema = $self->result_source->schema;
 118
 119     my $cd_rs = $schema->resultset('CD')->search({
 120       title => $request->param('title'),
 121       year => $request->param('year'),
 122     });
 123
 124     $cd_rs = $self->apply_security_policy( $cd_rs );
 125
 126     return $cd_rs->all();
 127   }
 128
 129   sub apply_security_policy {
 130     my $self = shift;
 131     my ($rs) = @_;
 132
 133     return $rs->search({
 134       subversive => 0,
 135     });
 136   }
 137
 138 =head3 Resolving conditions and attributes
 139
 140 When a resultset is chained from another resultset, conditions and
 141 attributes with the same keys need resolving.
 142
 143 L</join>, L</prefetch>, L</+select>, L</+as> attributes are merged
 144 into the existing ones from the original resultset.
 145
 146 The L</where> and L</having> attributes, and any search conditions, are
 147 merged with an SQL C<AND> to the existing condition from the original
 148 resultset.
 149
 150 All other attributes are overridden by any new ones supplied in the
 151 search attributes.
 152
 153 =head2 Multiple queries
 154
 155 Since a resultset just defines a query, you can do all sorts of
 156 things with it with the same object.
 157
 158   # Don't hit the DB yet.
 159   my $cd_rs = $schema->resultset('CD')->search({
 160     title => 'something',
 161     year => 2009,
 162   });
 163
 164   # Each of these hits the DB individually.
 165   my $count = $cd_rs->count;
 166   my $most_recent = $cd_rs->get_column('date_released')->max();
 167   my @records = $cd_rs->all;
 168
 169 And it's not just limited to SELECT statements.
 170
 171   $cd_rs->delete();
 172
 173 This is even cooler:
 174
 175   $cd_rs->create({ artist => 'Fred' });
 176
 177 Which is the same as:
 178
 179   $schema->resultset('CD')->create({
 180     title => 'something',
 181     year => 2009,
 182     artist => 'Fred'
 183   });
 184
 185 See: L</search>, L</count>, L</get_column>, L</all>, L</create>.
 186
 187 =head1 METHODS
 188
 189 =head2 new
 190
 191 =over 4
 192
 193 =item Arguments: L<$source|DBIx::Class::ResultSource>, L<\%attrs?|/ATTRIBUTES>
 194
 195 =item Return Value: L<$resultset|/search>
 196
 197 =back
 198
 199 The resultset constructor. Takes a source object (usually a
 200 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
 201 L</ATTRIBUTES> below).  Does not perform any queries -- these are
 202 executed as needed by the other methods.
 203
 204 Generally you never construct a resultset manually. Instead you get one
 205 from e.g. a
 206 C<< $schema->L<resultset|DBIx::Class::Schema/resultset>('$source_name') >>
 207 or C<< $another_resultset->L<search|/search>(...) >> (the later called in
 208 scalar context):
 209
 210   my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
 211
 212 =over
 213
 214 =item WARNING
 215
 216 If called on an object, proxies to L</new_result> instead, so
 217
 218   my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 219
 220 will return a CD object, not a ResultSet, and is equivalent to:
 221
 222   my $cd = $schema->resultset('CD')->new_result({ title => 'Spoon' });
 223
 224 Please also keep in mind that many internals call L</new_result> directly,
 225 so overloading this method with the idea of intercepting new result object
 226 creation B<will not work>. See also warning pertaining to L</create>.
 227
 228 =back
 229
 230 =cut
 231
 232 sub new {
 233   my $class = shift;
 234   return $class->new_result(@_) if ref $class;
 235
 236   my ($source, $attrs) = @_;
 237   $source = $source->resolve
 238     if $source->isa('DBIx::Class::ResultSourceHandle');
 239   $attrs = { %{$attrs||{}} };
 240
 241   if ($attrs->{page}) {
 242     $attrs->{rows} ||= 10;
 243   }
 244
 245   $attrs->{alias} ||= 'me';
 246
 247   my $self = bless {
 248     result_source => $source,
 249     cond => $attrs->{where},
 250     pager => undef,
 251     attrs => $attrs,
 252   }, $class;
 253
 254   # if there is a dark selector, this means we are already in a
 255   # chain and the cleanup/sanification was taken care of by
 256   # _search_rs already
 257   $self->_normalize_selection($attrs)
 258     unless $attrs->{_dark_selector};
 259
 260   $self->result_class(
 261     $attrs->{result_class} || $source->result_class
 262   );
 263
 264   $self;
 265 }
 266
 267 =head2 search
 268
 269 =over 4
 270
 271 =item Arguments: L<$cond|DBIx::Class::SQLMaker> | undef, L<\%attrs?|/ATTRIBUTES>
 272
 273 =item Return Value: $resultset (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 274
 275 =back
 276
 277   my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
 278   my $new_rs = $cd_rs->search({ year => 2005 });
 279
 280   my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
 281                  # year = 2005 OR year = 2004
 282
 283 In list context, C<< ->all() >> is called implicitly on the resultset, thus
 284 returning a list of L<result|DBIx::Class::Manual::ResultClass> objects instead.
 285 To avoid that, use L</search_rs>.
 286
 287 If you need to pass in additional attributes but no additional condition,
 288 call it as C<search(undef, \%attrs)>.
 289
 290   # "SELECT name, artistid FROM $artist_table"
 291   my @all_artists = $schema->resultset('Artist')->search(undef, {
 292     columns => [qw/name artistid/],
 293   });
 294
 295 For a list of attributes that can be passed to C<search>, see
 296 L</ATTRIBUTES>. For more examples of using this function, see
 297 L<Searching|DBIx::Class::Manual::Cookbook/Searching>. For a complete
 298 documentation for the first argument, see L<SQL::Abstract>
 299 and its extension L<DBIx::Class::SQLMaker>.
 300
 301 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
 302
 303 =head3 CAVEAT
 304
 305 Note that L</search> does not process/deflate any of the values passed in the
 306 L<SQL::Abstract>-compatible search condition structure. This is unlike other
 307 condition-bound methods L</new_result>, L</create> and L</find>. The user must ensure
 308 manually that any value passed to this method will stringify to something the
 309 RDBMS knows how to deal with. A notable example is the handling of L<DateTime>
 310 objects, for more info see:
 311 L<DBIx::Class::Manual::Cookbook/Formatting DateTime objects in queries>.
 312
 313 =cut
 314
 315 sub search {
 316   my $self = shift;
 317   my $rs = $self->search_rs( @_ );
 318
 319   if (wantarray) {
 320     return $rs->all;
 321   }
 322   elsif (defined wantarray) {
 323     return $rs;
 324   }
 325   else {
 326     # we can be called by a relationship helper, which in
 327     # turn may be called in void context due to some braindead
 328     # overload or whatever else the user decided to be clever
 329     # at this particular day. Thus limit the exception to
 330     # external code calls only
 331     $self->throw_exception ('->search is *not* a mutator, calling it in void context makes no sense')
 332       if (caller)[0] !~ /^\QDBIx::Class::/;
 333
 334     return ();
 335   }
 336 }
 337
 338 =head2 search_rs
 339
 340 =over 4
 341
 342 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
 343
 344 =item Return Value: L<$resultset|/search>
 345
 346 =back
 347
 348 This method does the same exact thing as search() except it will
 349 always return a resultset, even in list context.
 350
 351 =cut
 352
 353 sub search_rs {
 354   my $self = shift;
 355
 356   my $rsrc = $self->result_source;
 357   my ($call_cond, $call_attrs);
 358
 359   # Special-case handling for (undef, undef) or (undef)
 360   # Note that (foo => undef) is valid deprecated syntax
 361   @_ = () if not scalar grep { defined $_ } @_;
 362
 363   # just a cond
 364   if (@_ == 1) {
 365     $call_cond = shift;
 366   }
 367   # fish out attrs in the ($condref, $attr) case
 368   elsif (@_ == 2 and ( ! defined $_[0] or (ref $_[0]) ne '') ) {
 369     ($call_cond, $call_attrs) = @_;
 370   }
 371   elsif (@_ % 2) {
 372     $self->throw_exception('Odd number of arguments to search')
 373   }
 374   # legacy search
 375   elsif (@_) {
 376     carp_unique 'search( %condition ) is deprecated, use search( \%condition ) instead'
 377       unless $rsrc->result_class->isa('DBIx::Class::CDBICompat');
 378
 379     for my $i (0 .. $#_) {
 380       next if $i % 2;
 381       $self->throw_exception ('All keys in condition key/value pairs must be plain scalars')
 382         if (! defined $_[$i] or ref $_[$i] ne '');
 383     }
 384
 385     $call_cond = { @_ };
 386   }
 387
 388   # see if we can keep the cache (no $rs changes)
 389   my $cache;
 390   my %safe = (alias => 1, cache => 1);
 391   if ( ! List::Util::first { !$safe{$_} } keys %$call_attrs and (
 392     ! defined $_[0]
 393       or
 394     ref $_[0] eq 'HASH' && ! keys %{$_[0]}
 395       or
 396     ref $_[0] eq 'ARRAY' && ! @{$_[0]}
 397   )) {
 398     $cache = $self->get_cache;
 399   }
 400
 401   my $old_attrs = { %{$self->{attrs}} };
 402   my $old_having = delete $old_attrs->{having};
 403   my $old_where = delete $old_attrs->{where};
 404
 405   my $new_attrs = { %$old_attrs };
 406
 407   # take care of call attrs (only if anything is changing)
 408   if ($call_attrs and keys %$call_attrs) {
 409
 410     # copy for _normalize_selection
 411     $call_attrs = { %$call_attrs };
 412
 413     my @selector_attrs = qw/select as columns cols +select +as +columns include_columns/;
 414
 415     # reset the current selector list if new selectors are supplied
 416     if (List::Util::first { exists $call_attrs->{$_} } qw/columns cols select as/) {
 417       delete @{$old_attrs}{(@selector_attrs, '_dark_selector')};
 418     }
 419
 420     # Normalize the new selector list (operates on the passed-in attr structure)
 421     # Need to do it on every chain instead of only once on _resolved_attrs, in
 422     # order to allow detection of empty vs partial 'as'
 423     $call_attrs->{_dark_selector} = $old_attrs->{_dark_selector}
 424       if $old_attrs->{_dark_selector};
 425     $self->_normalize_selection ($call_attrs);
 426
 427     # start with blind overwriting merge, exclude selector attrs
 428     $new_attrs = { %{$old_attrs}, %{$call_attrs} };
 429     delete @{$new_attrs}{@selector_attrs};
 430
 431     for (@selector_attrs) {
 432       $new_attrs->{$_} = $self->_merge_attr($old_attrs->{$_}, $call_attrs->{$_})
 433         if ( exists $old_attrs->{$_} or exists $call_attrs->{$_} );
 434     }
 435
 436     # older deprecated name, use only if {columns} is not there
 437     if (my $c = delete $new_attrs->{cols}) {
 438       if ($new_attrs->{columns}) {
 439         carp "Resultset specifies both the 'columns' and the legacy 'cols' attributes - ignoring 'cols'";
 440       }
 441       else {
 442         $new_attrs->{columns} = $c;
 443       }
 444     }
 445
 446
 447     # join/prefetch use their own crazy merging heuristics
 448     foreach my $key (qw/join prefetch/) {
 449       $new_attrs->{$key} = $self->_merge_joinpref_attr($old_attrs->{$key}, $call_attrs->{$key})
 450         if exists $call_attrs->{$key};
 451     }
 452
 453     # stack binds together
 454     $new_attrs->{bind} = [ @{ $old_attrs->{bind} || [] }, @{ $call_attrs->{bind} || [] } ];
 455   }
 456
 457
 458   for ($old_where, $call_cond) {
 459     if (defined $_) {
 460       $new_attrs->{where} = $self->_stack_cond (
 461         $_, $new_attrs->{where}
 462       );
 463     }
 464   }
 465
 466   if (defined $old_having) {
 467     $new_attrs->{having} = $self->_stack_cond (
 468       $old_having, $new_attrs->{having}
 469     )
 470   }
 471
 472   my $rs = (ref $self)->new($rsrc, $new_attrs);
 473
 474   $rs->set_cache($cache) if ($cache);
 475
 476   return $rs;
 477 }
 478
 479 my $dark_sel_dumper;
 480 sub _normalize_selection {
 481   my ($self, $attrs) = @_;
 482
 483   # legacy syntax
 484   $attrs->{'+columns'} = $self->_merge_attr($attrs->{'+columns'}, delete $attrs->{include_columns})
 485     if exists $attrs->{include_columns};
 486
 487   # columns are always placed first, however
 488
 489   # Keep the X vs +X separation until _resolved_attrs time - this allows to
 490   # delay the decision on whether to use a default select list ($rsrc->columns)
 491   # allowing stuff like the remove_columns helper to work
 492   #
 493   # select/as +select/+as pairs need special handling - the amount of select/as
 494   # elements in each pair does *not* have to be equal (think multicolumn
 495   # selectors like distinct(foo, bar) ). If the selector is bare (no 'as'
 496   # supplied at all) - try to infer the alias, either from the -as parameter
 497   # of the selector spec, or use the parameter whole if it looks like a column
 498   # name (ugly legacy heuristic). If all fails - leave the selector bare (which
 499   # is ok as well), but make sure no more additions to the 'as' chain take place
 500   for my $pref ('', '+') {
 501
 502     my ($sel, $as) = map {
 503       my $key = "${pref}${_}";
 504
 505       my $val = [ ref $attrs->{$key} eq 'ARRAY'
 506         ? @{$attrs->{$key}}
 507         : $attrs->{$key} || ()
 508       ];
 509       delete $attrs->{$key};
 510       $val;
 511     } qw/select as/;
 512
 513     if (! @$as and ! @$sel ) {
 514       next;
 515     }
 516     elsif (@$as and ! @$sel) {
 517       $self->throw_exception(
 518         "Unable to handle ${pref}as specification (@$as) without a corresponding ${pref}select"
 519       );
 520     }
 521     elsif( ! @$as ) {
 522       # no as part supplied at all - try to deduce (unless explicit end of named selection is declared)
 523       # if any @$as has been supplied we assume the user knows what (s)he is doing
 524       # and blindly keep stacking up pieces
 525       unless ($attrs->{_dark_selector}) {
 526         SELECTOR:
 527         for (@$sel) {
 528           if ( ref $_ eq 'HASH' and exists $_->{-as} ) {
 529             push @$as, $_->{-as};
 530           }
 531           # assume any plain no-space, no-parenthesis string to be a column spec
 532           # FIXME - this is retarded but is necessary to support shit like 'count(foo)'
 533           elsif ( ! ref $_ and $_ =~ /^ [^\s\(\)]+ $/x) {
 534             push @$as, $_;
 535           }
 536           # if all else fails - raise a flag that no more aliasing will be allowed
 537           else {
 538             $attrs->{_dark_selector} = {
 539               plus_stage => $pref,
 540               string => ($dark_sel_dumper ||= do {
 541                   require Data::Dumper::Concise;
 542                   Data::Dumper::Concise::DumperObject()->Indent(0);
 543                 })->Values([$_])->Dump
 544               ,
 545             };
 546             last SELECTOR;
 547           }
 548         }
 549       }
 550     }
 551     elsif (@$as < @$sel) {
 552       $self->throw_exception(
 553         "Unable to handle an ${pref}as specification (@$as) with less elements than the corresponding ${pref}select"
 554       );
 555     }
 556     elsif ($pref and $attrs->{_dark_selector}) {
 557       $self->throw_exception(
 558         "Unable to process named '+select', resultset contains an unnamed selector $attrs->{_dark_selector}{string}"
 559       );
 560     }
 561
 562
 563     # merge result
 564     $attrs->{"${pref}select"} = $self->_merge_attr($attrs->{"${pref}select"}, $sel);
 565     $attrs->{"${pref}as"} = $self->_merge_attr($attrs->{"${pref}as"}, $as);
 566   }
 567 }
 568
 569 sub _stack_cond {
 570   my ($self, $left, $right) = @_;
 571
 572   # collapse single element top-level conditions
 573   # (single pass only, unlikely to need recursion)
 574   for ($left, $right) {
 575     if (ref $_ eq 'ARRAY') {
 576       if (@$_ == 0) {
 577         $_ = undef;
 578       }
 579       elsif (@$_ == 1) {
 580         $_ = $_->[0];
 581       }
 582     }
 583     elsif (ref $_ eq 'HASH') {
 584       my ($first, $more) = keys %$_;
 585
 586       # empty hash
 587       if (! defined $first) {
 588         $_ = undef;
 589       }
 590       # one element hash
 591       elsif (! defined $more) {
 592         if ($first eq '-and' and ref $_->{'-and'} eq 'HASH') {
 593           $_ = $_->{'-and'};
 594         }
 595         elsif ($first eq '-or' and ref $_->{'-or'} eq 'ARRAY') {
 596           $_ = $_->{'-or'};
 597         }
 598       }
 599     }
 600   }
 601
 602   # merge hashes with weeding out of duplicates (simple cases only)
 603   if (ref $left eq 'HASH' and ref $right eq 'HASH') {
 604
 605     # shallow copy to destroy
 606     $right = { %$right };
 607     for (grep { exists $right->{$_} } keys %$left) {
 608       # the use of eq_deeply here is justified - the rhs of an
 609       # expression can contain a lot of twisted weird stuff
 610       delete $right->{$_} if Data::Compare::Compare( $left->{$_}, $right->{$_} );
 611     }
 612
 613     $right = undef unless keys %$right;
 614   }
 615
 616
 617   if (defined $left xor defined $right) {
 618     return defined $left ? $left : $right;
 619   }
 620   elsif (! defined $left) {
 621     return undef;
 622   }
 623   else {
 624     return { -and => [ $left, $right ] };
 625   }
 626 }
 627
 628 =head2 search_literal
 629
 630 B<CAVEAT>: C<search_literal> is provided for Class::DBI compatibility and
 631 should only be used in that context. C<search_literal> is a convenience
 632 method. It is equivalent to calling C<< $schema->search(\[]) >>, but if you
 633 want to ensure columns are bound correctly, use L</search>.
 634
 635 See L<DBIx::Class::Manual::Cookbook/Searching> and
 636 L<DBIx::Class::Manual::FAQ/Searching> for searching techniques that do not
 637 require C<search_literal>.
 638
 639 =over 4
 640
 641 =item Arguments: $sql_fragment, @standalone_bind_values
 642
 643 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 644
 645 =back
 646
 647   my @cds   = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
 648   my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
 649
 650 Pass a literal chunk of SQL to be added to the conditional part of the
 651 resultset query.
 652
 653 Example of how to use C<search> instead of C<search_literal>
 654
 655   my @cds = $cd_rs->search_literal('cdid = ? AND (artist = ? OR artist = ?)', (2, 1, 2));
 656   my @cds = $cd_rs->search(\[ 'cdid = ? AND (artist = ? OR artist = ?)', [ 'cdid', 2 ], [ 'artist', 1 ], [ 'artist', 2 ] ]);
 657
 658 =cut
 659
 660 sub search_literal {
 661   my ($self, $sql, @bind) = @_;
 662   my $attr;
 663   if ( @bind && ref($bind[-1]) eq 'HASH' ) {
 664     $attr = pop @bind;
 665   }
 666   return $self->search(\[ $sql, map [ {} => $_ ], @bind ], ($attr || () ));
 667 }
 668
 669 =head2 find
 670
 671 =over 4
 672
 673 =item Arguments: \%columns_values | @pk_values, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
 674
 675 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
 676
 677 =back
 678
 679 Finds and returns a single row based on supplied criteria. Takes either a
 680 hashref with the same format as L</create> (including inference of foreign
 681 keys from related objects), or a list of primary key values in the same
 682 order as the L<primary columns|DBIx::Class::ResultSource/primary_columns>
 683 declaration on the L</result_source>.
 684
 685 In either case an attempt is made to combine conditions already existing on
 686 the resultset with the condition passed to this method.
 687
 688 To aid with preparing the correct query for the storage you may supply the
 689 C<key> attribute, which is the name of a
 690 L<unique constraint|DBIx::Class::ResultSource/add_unique_constraint> (the
 691 unique constraint corresponding to the
 692 L<primary columns|DBIx::Class::ResultSource/primary_columns> is always named
 693 C<primary>). If the C<key> attribute has been supplied, and DBIC is unable
 694 to construct a query that satisfies the named unique constraint fully (
 695 non-NULL values for each column member of the constraint) an exception is
 696 thrown.
 697
 698 If no C<key> is specified, the search is carried over all unique constraints
 699 which are fully defined by the available condition.
 700
 701 If no such constraint is found, C<find> currently defaults to a simple
 702 C<< search->(\%column_values) >> which may or may not do what you expect.
 703 Note that this fallback behavior may be deprecated in further versions. If
 704 you need to search with arbitrary conditions - use L</search>. If the query
 705 resulting from this fallback produces more than one row, a warning to the
 706 effect is issued, though only the first row is constructed and returned as
 707 C<$result_object>.
 708
 709 In addition to C<key>, L</find> recognizes and applies standard
 710 L<resultset attributes|/ATTRIBUTES> in the same way as L</search> does.
 711
 712 Note that if you have extra concerns about the correctness of the resulting
 713 query you need to specify the C<key> attribute and supply the entire condition
 714 as an argument to find (since it is not always possible to perform the
 715 combination of the resultset condition with the supplied one, especially if
 716 the resultset condition contains literal sql).
 717
 718 For example, to find a row by its primary key:
 719
 720   my $cd = $schema->resultset('CD')->find(5);
 721
 722 You can also find a row by a specific unique constraint:
 723
 724   my $cd = $schema->resultset('CD')->find(
 725     {
 726       artist => 'Massive Attack',
 727       title  => 'Mezzanine',
 728     },
 729     { key => 'cd_artist_title' }
 730   );
 731
 732 See also L</find_or_create> and L</update_or_create>.
 733
 734 =cut
 735
 736 sub find {
 737   my $self = shift;
 738   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 739
 740   my $rsrc = $self->result_source;
 741
 742   my $constraint_name;
 743   if (exists $attrs->{key}) {
 744     $constraint_name = defined $attrs->{key}
 745       ? $attrs->{key}
 746       : $self->throw_exception("An undefined 'key' resultset attribute makes no sense")
 747     ;
 748   }
 749
 750   # Parse out the condition from input
 751   my $call_cond;
 752
 753   if (ref $_[0] eq 'HASH') {
 754     $call_cond = { %{$_[0]} };
 755   }
 756   else {
 757     # if only values are supplied we need to default to 'primary'
 758     $constraint_name = 'primary' unless defined $constraint_name;
 759
 760     my @c_cols = $rsrc->unique_constraint_columns($constraint_name);
 761
 762     $self->throw_exception(
 763       "No constraint columns, maybe a malformed '$constraint_name' constraint?"
 764     ) unless @c_cols;
 765
 766     $self->throw_exception (
 767       'find() expects either a column/value hashref, or a list of values '
 768     . "corresponding to the columns of the specified unique constraint '$constraint_name'"
 769     ) unless @c_cols == @_;
 770
 771     $call_cond = {};
 772     @{$call_cond}{@c_cols} = @_;
 773   }
 774
 775   my %related;
 776   for my $key (keys %$call_cond) {
 777     if (
 778       my $keyref = ref($call_cond->{$key})
 779         and
 780       my $relinfo = $rsrc->relationship_info($key)
 781     ) {
 782       my $val = delete $call_cond->{$key};
 783
 784       next if $keyref eq 'ARRAY'; # has_many for multi_create
 785
 786       my $rel_q = $rsrc->_resolve_condition(
 787         $relinfo->{cond}, $val, $key, $key
 788       );
 789       die "Can't handle complex relationship conditions in find" if ref($rel_q) ne 'HASH';
 790       @related{keys %$rel_q} = values %$rel_q;
 791     }
 792   }
 793
 794   # relationship conditions take precedence (?)
 795   @{$call_cond}{keys %related} = values %related;
 796
 797   my $alias = exists $attrs->{alias} ? $attrs->{alias} : $self->{attrs}{alias};
 798   my $final_cond;
 799   if (defined $constraint_name) {
 800     $final_cond = $self->_qualify_cond_columns (
 801
 802       $self->_build_unique_cond (
 803         $constraint_name,
 804         $call_cond,
 805       ),
 806
 807       $alias,
 808     );
 809   }
 810   elsif ($self->{attrs}{accessor} and $self->{attrs}{accessor} eq 'single') {
 811     # This means that we got here after a merger of relationship conditions
 812     # in ::Relationship::Base::search_related (the row method), and furthermore
 813     # the relationship is of the 'single' type. This means that the condition
 814     # provided by the relationship (already attached to $self) is sufficient,
 815     # as there can be only one row in the database that would satisfy the
 816     # relationship
 817   }
 818   else {
 819     # no key was specified - fall down to heuristics mode:
 820     # run through all unique queries registered on the resultset, and
 821     # 'OR' all qualifying queries together
 822     my (@unique_queries, %seen_column_combinations);
 823     for my $c_name ($rsrc->unique_constraint_names) {
 824       next if $seen_column_combinations{
 825         join "\x00", sort $rsrc->unique_constraint_columns($c_name)
 826       }++;
 827
 828       push @unique_queries, try {
 829         $self->_build_unique_cond ($c_name, $call_cond, 'croak_on_nulls')
 830       } || ();
 831     }
 832
 833     $final_cond = @unique_queries
 834       ? [ map { $self->_qualify_cond_columns($_, $alias) } @unique_queries ]
 835       : $self->_non_unique_find_fallback ($call_cond, $attrs)
 836     ;
 837   }
 838
 839   # Run the query, passing the result_class since it should propagate for find
 840   my $rs = $self->search ($final_cond, {result_class => $self->result_class, %$attrs});
 841   if ($rs->_resolved_attrs->{collapse}) {
 842     my $row = $rs->next;
 843     carp "Query returned more than one row" if $rs->next;
 844     return $row;
 845   }
 846   else {
 847     return $rs->single;
 848   }
 849 }
 850
 851 # This is a stop-gap method as agreed during the discussion on find() cleanup:
 852 # http://lists.scsys.co.uk/pipermail/dbix-class/2010-October/009535.html
 853 #
 854 # It is invoked when find() is called in legacy-mode with insufficiently-unique
 855 # condition. It is provided for overrides until a saner way forward is devised
 856 #
 857 # *NOTE* This is not a public method, and it's *GUARANTEED* to disappear down
 858 # the road. Please adjust your tests accordingly to catch this situation early
 859 # DBIx::Class::ResultSet->can('_non_unique_find_fallback') is reasonable
 860 #
 861 # The method will not be removed without an adequately complete replacement
 862 # for strict-mode enforcement
 863 sub _non_unique_find_fallback {
 864   my ($self, $cond, $attrs) = @_;
 865
 866   return $self->_qualify_cond_columns(
 867     $cond,
 868     exists $attrs->{alias}
 869       ? $attrs->{alias}
 870       : $self->{attrs}{alias}
 871   );
 872 }
 873
 874
 875 sub _qualify_cond_columns {
 876   my ($self, $cond, $alias) = @_;
 877
 878   my %aliased = %$cond;
 879   for (keys %aliased) {
 880     $aliased{"$alias.$_"} = delete $aliased{$_}
 881       if $_ !~ /\./;
 882   }
 883
 884   return \%aliased;
 885 }
 886
 887 sub _build_unique_cond {
 888   my ($self, $constraint_name, $extra_cond, $croak_on_null) = @_;
 889
 890   my @c_cols = $self->result_source->unique_constraint_columns($constraint_name);
 891
 892   # combination may fail if $self->{cond} is non-trivial
 893   my ($final_cond) = try {
 894     $self->_merge_with_rscond ($extra_cond)
 895   } catch {
 896     +{ %$extra_cond }
 897   };
 898
 899   # trim out everything not in $columns
 900   $final_cond = { map {
 901     exists $final_cond->{$_}
 902       ? ( $_ => $final_cond->{$_} )
 903       : ()
 904   } @c_cols };
 905
 906   if (my @missing = grep
 907     { ! ($croak_on_null ? defined $final_cond->{$_} : exists $final_cond->{$_}) }
 908     (@c_cols)
 909   ) {
 910     $self->throw_exception( sprintf ( "Unable to satisfy requested constraint '%s', no values for column(s): %s",
 911       $constraint_name,
 912       join (', ', map { "'$_'" } @missing),
 913     ) );
 914   }
 915
 916   if (
 917     !$croak_on_null
 918       and
 919     !$ENV{DBIC_NULLABLE_KEY_NOWARN}
 920       and
 921     my @undefs = sort grep { ! defined $final_cond->{$_} } (keys %$final_cond)
 922   ) {
 923     carp_unique ( sprintf (
 924       "NULL/undef values supplied for requested unique constraint '%s' (NULL "
 925     . 'values in column(s): %s). This is almost certainly not what you wanted, '
 926     . 'though you can set DBIC_NULLABLE_KEY_NOWARN to disable this warning.',
 927       $constraint_name,
 928       join (', ', map { "'$_'" } @undefs),
 929     ));
 930   }
 931
 932   return $final_cond;
 933 }
 934
 935 =head2 search_related
 936
 937 =over 4
 938
 939 =item Arguments: $rel_name, $cond?, L<\%attrs?|/ATTRIBUTES>
 940
 941 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 942
 943 =back
 944
 945   $new_rs = $cd_rs->search_related('artist', {
 946     name => 'Emo-R-Us',
 947   });
 948
 949 Searches the specified relationship, optionally specifying a condition and
 950 attributes for matching records. See L</ATTRIBUTES> for more information.
 951
 952 In list context, C<< ->all() >> is called implicitly on the resultset, thus
 953 returning a list of result objects instead. To avoid that, use L</search_related_rs>.
 954
 955 See also L</search_related_rs>.
 956
 957 =cut
 958
 959 sub search_related {
 960   return shift->related_resultset(shift)->search(@_);
 961 }
 962
 963 =head2 search_related_rs
 964
 965 This method works exactly the same as search_related, except that
 966 it guarantees a resultset, even in list context.
 967
 968 =cut
 969
 970 sub search_related_rs {
 971   return shift->related_resultset(shift)->search_rs(@_);
 972 }
 973
 974 =head2 cursor
 975
 976 =over 4
 977
 978 =item Arguments: none
 979
 980 =item Return Value: L<$cursor|DBIx::Class::Cursor>
 981
 982 =back
 983
 984 Returns a storage-driven cursor to the given resultset. See
 985 L<DBIx::Class::Cursor> for more information.
 986
 987 =cut
 988
 989 sub cursor {
 990   my $self = shift;
 991
 992   return $self->{cursor} ||= do {
 993     my $attrs = { %{$self->_resolved_attrs } };
 994     $self->result_source->storage->select(
 995       $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
 996     );
 997   };
 998 }
 999
1000 =head2 single
1001
1002 =over 4
1003
1004 =item Arguments: L<$cond?|DBIx::Class::SQLMaker>
1005
1006 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1007
1008 =back
1009
1010   my $cd = $schema->resultset('CD')->single({ year => 2001 });
1011
1012 Inflates the first result without creating a cursor if the resultset has
1013 any records in it; if not returns C<undef>. Used by L</find> as a lean version
1014 of L</search>.
1015
1016 While this method can take an optional search condition (just like L</search>)
1017 being a fast-code-path it does not recognize search attributes. If you need to
1018 add extra joins or similar, call L</search> and then chain-call L</single> on the
1019 L<DBIx::Class::ResultSet> returned.
1020
1021 =over
1022
1023 =item B<Note>
1024
1025 As of 0.08100, this method enforces the assumption that the preceding
1026 query returns only one row. If more than one row is returned, you will receive
1027 a warning:
1028
1029   Query returned more than one row
1030
1031 In this case, you should be using L</next> or L</find> instead, or if you really
1032 know what you are doing, use the L</rows> attribute to explicitly limit the size
1033 of the resultset.
1034
1035 This method will also throw an exception if it is called on a resultset prefetching
1036 has_many, as such a prefetch implies fetching multiple rows from the database in
1037 order to assemble the resulting object.
1038
1039 =back
1040
1041 =cut
1042
1043 sub single {
1044   my ($self, $where) = @_;
1045   if(@_ > 2) {
1046       $self->throw_exception('single() only takes search conditions, no attributes. You want ->search( $cond, $attrs )->single()');
1047   }
1048
1049   my $attrs = { %{$self->_resolved_attrs} };
1050
1051   $self->throw_exception(
1052     'single() can not be used on resultsets prefetching has_many. Use find( \%cond ) or next() instead'
1053   ) if $attrs->{collapse};
1054
1055   if ($where) {
1056     if (defined $attrs->{where}) {
1057       $attrs->{where} = {
1058         '-and' =>
1059             [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
1060                $where, delete $attrs->{where} ]
1061       };
1062     } else {
1063       $attrs->{where} = $where;
1064     }
1065   }
1066
1067   my $data = [ $self->result_source->storage->select_single(
1068     $attrs->{from}, $attrs->{select},
1069     $attrs->{where}, $attrs
1070   )];
1071   return undef unless @$data;
1072   $self->{stashed_rows} = [ $data ];
1073   $self->_construct_objects->[0];
1074 }
1075
1076
1077 # _collapse_query
1078 #
1079 # Recursively collapse the query, accumulating values for each column.
1080
1081 sub _collapse_query {
1082   my ($self, $query, $collapsed) = @_;
1083
1084   $collapsed ||= {};
1085
1086   if (ref $query eq 'ARRAY') {
1087     foreach my $subquery (@$query) {
1088       next unless ref $subquery;  # -or
1089       $collapsed = $self->_collapse_query($subquery, $collapsed);
1090     }
1091   }
1092   elsif (ref $query eq 'HASH') {
1093     if (keys %$query and (keys %$query)[0] eq '-and') {
1094       foreach my $subquery (@{$query->{-and}}) {
1095         $collapsed = $self->_collapse_query($subquery, $collapsed);
1096       }
1097     }
1098     else {
1099       foreach my $col (keys %$query) {
1100         my $value = $query->{$col};
1101         $collapsed->{$col}{$value}++;
1102       }
1103     }
1104   }
1105
1106   return $collapsed;
1107 }
1108
1109 =head2 get_column
1110
1111 =over 4
1112
1113 =item Arguments: L<$cond?|DBIx::Class::SQLMaker>
1114
1115 =item Return Value: L<$resultsetcolumn|DBIx::Class::ResultSetColumn>
1116
1117 =back
1118
1119   my $max_length = $rs->get_column('length')->max;
1120
1121 Returns a L<DBIx::Class::ResultSetColumn> instance for a column of the ResultSet.
1122
1123 =cut
1124
1125 sub get_column {
1126   my ($self, $column) = @_;
1127   my $new = DBIx::Class::ResultSetColumn->new($self, $column);
1128   return $new;
1129 }
1130
1131 =head2 search_like
1132
1133 =over 4
1134
1135 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1136
1137 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
1138
1139 =back
1140
1141   # WHERE title LIKE '%blue%'
1142   $cd_rs = $rs->search_like({ title => '%blue%'});
1143
1144 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
1145 that this is simply a convenience method retained for ex Class::DBI users.
1146 You most likely want to use L</search> with specific operators.
1147
1148 For more information, see L<DBIx::Class::Manual::Cookbook>.
1149
1150 This method is deprecated and will be removed in 0.09. Use L</search()>
1151 instead. An example conversion is:
1152
1153   ->search_like({ foo => 'bar' });
1154
1155   # Becomes
1156
1157   ->search({ foo => { like => 'bar' } });
1158
1159 =cut
1160
1161 sub search_like {
1162   my $class = shift;
1163   carp_unique (
1164     'search_like() is deprecated and will be removed in DBIC version 0.09.'
1165    .' Instead use ->search({ x => { -like => "y%" } })'
1166    .' (note the outer pair of {}s - they are important!)'
1167   );
1168   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1169   my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
1170   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
1171   return $class->search($query, { %$attrs });
1172 }
1173
1174 =head2 slice
1175
1176 =over 4
1177
1178 =item Arguments: $first, $last
1179
1180 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
1181
1182 =back
1183
1184 Returns a resultset or object list representing a subset of elements from the
1185 resultset slice is called on. Indexes are from 0, i.e., to get the first
1186 three records, call:
1187
1188   my ($one, $two, $three) = $rs->slice(0, 2);
1189
1190 =cut
1191
1192 sub slice {
1193   my ($self, $min, $max) = @_;
1194   my $attrs = {}; # = { %{ $self->{attrs} || {} } };
1195   $attrs->{offset} = $self->{attrs}{offset} || 0;
1196   $attrs->{offset} += $min;
1197   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
1198   return $self->search(undef, $attrs);
1199   #my $slice = (ref $self)->new($self->result_source, $attrs);
1200   #return (wantarray ? $slice->all : $slice);
1201 }
1202
1203 =head2 next
1204
1205 =over 4
1206
1207 =item Arguments: none
1208
1209 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1210
1211 =back
1212
1213 Returns the next element in the resultset (C<undef> is there is none).
1214
1215 Can be used to efficiently iterate over records in the resultset:
1216
1217   my $rs = $schema->resultset('CD')->search;
1218   while (my $cd = $rs->next) {
1219     print $cd->title;
1220   }
1221
1222 Note that you need to store the resultset object, and call C<next> on it.
1223 Calling C<< resultset('Table')->next >> repeatedly will always return the
1224 first record from the resultset.
1225
1226 =cut
1227
1228 sub next {
1229   my ($self) = @_;
1230
1231   if (my $cache = $self->get_cache) {
1232     $self->{all_cache_position} ||= 0;
1233     return $cache->[$self->{all_cache_position}++];
1234   }
1235
1236   if ($self->{attrs}{cache}) {
1237     delete $self->{pager};
1238     $self->{all_cache_position} = 1;
1239     return ($self->all)[0];
1240   }
1241
1242   return shift(@{$self->{stashed_objects}}) if @{ $self->{stashed_objects}||[] };
1243
1244   $self->{stashed_objects} = $self->_construct_objects
1245     or return undef;
1246
1247   return shift @{$self->{stashed_objects}};
1248 }
1249
1250 # Constructs as many objects as it can in one pass while respecting
1251 # cursor laziness. Several modes of operation:
1252 #
1253 # * Always builds everything present in @{$self->{stashed_rows}}
1254 # * If called with $fetch_all true - pulls everything off the cursor and
1255 #   builds all objects in one pass
1256 # * If $self->_resolved_attrs->{collapse} is true, checks the order_by
1257 #   and if the resultset is ordered properly by the left side:
1258 #   * Fetches stuff off the cursor until the "master object" changes,
1259 #     and saves the last extra row (if any) in @{$self->{stashed_rows}}
1260 #   OR
1261 #   * Just fetches, and collapses/constructs everything as if $fetch_all
1262 #     was requested (there is no other way to collapse except for an
1263 #     eager cursor)
1264 # * If no collapse is requested - just get the next row, construct and
1265 #   return
1266 sub _construct_objects {
1267   my ($self, $fetch_all) = @_;
1268
1269   my $rsrc = $self->result_source;
1270   my $attrs = $self->_resolved_attrs;
1271   my $cursor = $self->cursor;
1272
1273   # this will be used as both initial raw-row collector AND as a RV of
1274   # _construct_objects. Not regrowing the array twice matters a lot...
1275   # a suprising amount actually
1276   my $rows = (delete $self->{stashed_rows}) || [];
1277   if ($fetch_all) {
1278     # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1279     $rows = [ @$rows, $cursor->all ];
1280   }
1281   elsif (!$attrs->{collapse}) {
1282     # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1283     push @$rows, do { my @r = $cursor->next; @r ? \@r : () }
1284       unless @$rows;
1285   }
1286   else {
1287     $attrs->{_ordered_for_collapse} ||= (!$attrs->{order_by}) ? undef : do {
1288       my $st = $rsrc->schema->storage;
1289       my @ord_cols = map
1290         { $_->[0] }
1291         ( $st->_extract_order_criteria($attrs->{order_by}) )
1292       ;
1293
1294       my $colinfos = $st->_resolve_column_info($attrs->{from}, \@ord_cols);
1295
1296       for (0 .. $#ord_cols) {
1297         if (
1298           ! $colinfos->{$ord_cols[$_]}
1299             or
1300           $colinfos->{$ord_cols[$_]}{-result_source} != $rsrc
1301         ) {
1302           splice @ord_cols, $_;
1303           last;
1304         }
1305       }
1306
1307       # since all we check here are the start of the order_by belonging to the
1308       # top level $rsrc, a present identifying set will mean that the resultset
1309       # is ordered by its leftmost table in a tsable manner
1310       (@ord_cols and $rsrc->_identifying_column_set({ map
1311         { $colinfos->{$_}{-colname} => $colinfos->{$_} }
1312         @ord_cols
1313       })) ? 1 : 0;
1314     };
1315
1316     if ($attrs->{_ordered_for_collapse}) {
1317       push @$rows, do { my @r = $cursor->next; @r ? \@r : () };
1318     }
1319     # instead of looping over ->next, use ->all in stealth mode
1320     # *without* calling a ->reset afterwards
1321     # FIXME - encapsulation breach, got to be a better way
1322     elsif (! $cursor->{_done}) {
1323       push @$rows, $cursor->all;
1324       $cursor->{_done} = 1;
1325       $fetch_all = 1;
1326     }
1327   }
1328
1329   return undef unless @$rows;
1330
1331   my $res_class = $self->result_class;
1332   my $inflator = $res_class->can ('inflate_result')
1333     or $self->throw_exception("Inflator $res_class does not provide an inflate_result() method");
1334
1335   my $infmap = $attrs->{as};
1336
1337   if (!$attrs->{collapse} and $attrs->{_single_object_inflation}) {
1338     # construct a much simpler array->hash folder for the one-table cases right here
1339
1340     # FIXME SUBOPTIMAL this is a very very very hot spot
1341     # while rather optimal we can *still* do much better, by
1342     # building a smarter [Row|HRI]::inflate_result(), and
1343     # switch to feeding it data via a much leaner interface
1344     #
1345     # crude unscientific benchmarking indicated the shortcut eval is not worth it for
1346     # this particular resultset size
1347     if (@$rows < 60) {
1348       my @as_idx = 0..$#$infmap;
1349       for my $r (@$rows) {
1350         $r = $inflator->($res_class, $rsrc, { map { $infmap->[$_] => $r->[$_] } @as_idx } );
1351       }
1352     }
1353     else {
1354       eval sprintf (
1355         '$_ = $inflator->($res_class, $rsrc, { %s }) for @$rows',
1356         join (', ', map { "\$infmap->[$_] => \$_->[$_]" } 0..$#$infmap )
1357       );
1358     }
1359   }
1360   else {
1361     $self->{_row_parser} ||= eval sprintf 'sub { %s }', $rsrc->_mk_row_parser({
1362       inflate_map => $infmap,
1363       selection => $attrs->{select},
1364       collapse => $attrs->{collapse},
1365       premultiplied => $attrs->{_main_source_premultiplied},
1366     }) or die $@;
1367
1368     # modify $rows in-place, shrinking/extending as necessary
1369     $self->{_row_parser}->($rows, $fetch_all ? () : (
1370       # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1371       sub { my @r = $cursor->next or return; \@r }, # how the collapser gets more rows
1372       ($self->{stashed_rows} = []),                 # where does it stuff excess
1373     ));
1374
1375     $_ = $inflator->($res_class, $rsrc, @$_) for @$rows;
1376   }
1377
1378   # CDBI compat stuff
1379   if ($attrs->{record_filter}) {
1380     $_ = $attrs->{record_filter}->($_) for @$rows;
1381   }
1382
1383   return $rows;
1384 }
1385
1386 =head2 result_source
1387
1388 =over 4
1389
1390 =item Arguments: L<$result_source?|DBIx::Class::ResultSource>
1391
1392 =item Return Value: L<$result_source|DBIx::Class::ResultSource>
1393
1394 =back
1395
1396 An accessor for the primary ResultSource object from which this ResultSet
1397 is derived.
1398
1399 =head2 result_class
1400
1401 =over 4
1402
1403 =item Arguments: $result_class?
1404
1405 =item Return Value: $result_class
1406
1407 =back
1408
1409 An accessor for the class to use when creating result objects. Defaults to
1410 C<< result_source->result_class >> - which in most cases is the name of the
1411 L<"table"|DBIx::Class::Manual::Glossary/"ResultSource"> class.
1412
1413 Note that changing the result_class will also remove any components
1414 that were originally loaded in the source class via
1415 L<DBIx::Class::ResultSource/load_components>. Any overloaded methods
1416 in the original source class will not run.
1417
1418 =cut
1419
1420 sub result_class {
1421   my ($self, $result_class) = @_;
1422   if ($result_class) {
1423     unless (ref $result_class) { # don't fire this for an object
1424       $self->ensure_class_loaded($result_class);
1425     }
1426     $self->_result_class($result_class);
1427     # THIS LINE WOULD BE A BUG - this accessor specifically exists to
1428     # permit the user to set result class on one result set only; it only
1429     # chains if provided to search()
1430     #$self->{attrs}{result_class} = $result_class if ref $self;
1431   }
1432   $self->_result_class;
1433 }
1434
1435 =head2 count
1436
1437 =over 4
1438
1439 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1440
1441 =item Return Value: $count
1442
1443 =back
1444
1445 Performs an SQL C<COUNT> with the same query as the resultset was built
1446 with to find the number of elements. Passing arguments is equivalent to
1447 C<< $rs->search ($cond, \%attrs)->count >>
1448
1449 =cut
1450
1451 sub count {
1452   my $self = shift;
1453   return $self->search(@_)->count if @_ and defined $_[0];
1454   return scalar @{ $self->get_cache } if $self->get_cache;
1455
1456   my $attrs = { %{ $self->_resolved_attrs } };
1457
1458   # this is a little optimization - it is faster to do the limit
1459   # adjustments in software, instead of a subquery
1460   my ($rows, $offset) = delete @{$attrs}{qw/rows offset/};
1461
1462   my $crs;
1463   if ($self->_has_resolved_attr (qw/collapse group_by/)) {
1464     $crs = $self->_count_subq_rs ($attrs);
1465   }
1466   else {
1467     $crs = $self->_count_rs ($attrs);
1468   }
1469   my $count = $crs->next;
1470
1471   $count -= $offset if $offset;
1472   $count = $rows if $rows and $rows < $count;
1473   $count = 0 if ($count < 0);
1474
1475   return $count;
1476 }
1477
1478 =head2 count_rs
1479
1480 =over 4
1481
1482 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1483
1484 =item Return Value: L<$count_rs|DBIx::Class::ResultSetColumn>
1485
1486 =back
1487
1488 Same as L</count> but returns a L<DBIx::Class::ResultSetColumn> object.
1489 This can be very handy for subqueries:
1490
1491   ->search( { amount => $some_rs->count_rs->as_query } )
1492
1493 As with regular resultsets the SQL query will be executed only after
1494 the resultset is accessed via L</next> or L</all>. That would return
1495 the same single value obtainable via L</count>.
1496
1497 =cut
1498
1499 sub count_rs {
1500   my $self = shift;
1501   return $self->search(@_)->count_rs if @_;
1502
1503   # this may look like a lack of abstraction (count() does about the same)
1504   # but in fact an _rs *must* use a subquery for the limits, as the
1505   # software based limiting can not be ported if this $rs is to be used
1506   # in a subquery itself (i.e. ->as_query)
1507   if ($self->_has_resolved_attr (qw/collapse group_by offset rows/)) {
1508     return $self->_count_subq_rs;
1509   }
1510   else {
1511     return $self->_count_rs;
1512   }
1513 }
1514
1515 #
1516 # returns a ResultSetColumn object tied to the count query
1517 #
1518 sub _count_rs {
1519   my ($self, $attrs) = @_;
1520
1521   my $rsrc = $self->result_source;
1522   $attrs ||= $self->_resolved_attrs;
1523
1524   my $tmp_attrs = { %$attrs };
1525   # take off any limits, record_filter is cdbi, and no point of ordering nor locking a count
1526   delete @{$tmp_attrs}{qw/rows offset order_by record_filter for/};
1527
1528   # overwrite the selector (supplied by the storage)
1529   $tmp_attrs->{select} = $rsrc->storage->_count_select ($rsrc, $attrs);
1530   $tmp_attrs->{as} = 'count';
1531
1532   my $tmp_rs = $rsrc->resultset_class->new($rsrc, $tmp_attrs)->get_column ('count');
1533
1534   return $tmp_rs;
1535 }
1536
1537 #
1538 # same as above but uses a subquery
1539 #
1540 sub _count_subq_rs {
1541   my ($self, $attrs) = @_;
1542
1543   my $rsrc = $self->result_source;
1544   $attrs ||= $self->_resolved_attrs;
1545
1546   my $sub_attrs = { %$attrs };
1547   # extra selectors do not go in the subquery and there is no point of ordering it, nor locking it
1548   delete @{$sub_attrs}{qw/collapse columns as select _prefetch_selector_range order_by for/};
1549
1550   # if we multi-prefetch we group_by something unique, as this is what we would
1551   # get out of the rs via ->next/->all. We *DO WANT* to clobber old group_by regardless
1552   if ( $attrs->{collapse}  ) {
1553     $sub_attrs->{group_by} = [ map { "$attrs->{alias}.$_" } @{
1554       $rsrc->_identifying_column_set || $self->throw_exception(
1555         'Unable to construct a unique group_by criteria properly collapsing the '
1556       . 'has_many prefetch before count()'
1557       );
1558     } ]
1559   }
1560
1561   # Calculate subquery selector
1562   if (my $g = $sub_attrs->{group_by}) {
1563
1564     my $sql_maker = $rsrc->storage->sql_maker;
1565
1566     # necessary as the group_by may refer to aliased functions
1567     my $sel_index;
1568     for my $sel (@{$attrs->{select}}) {
1569       $sel_index->{$sel->{-as}} = $sel
1570         if (ref $sel eq 'HASH' and $sel->{-as});
1571     }
1572
1573     # anything from the original select mentioned on the group-by needs to make it to the inner selector
1574     # also look for named aggregates referred in the having clause
1575     # having often contains scalarrefs - thus parse it out entirely
1576     my @parts = @$g;
1577     if ($attrs->{having}) {
1578       local $sql_maker->{having_bind};
1579       local $sql_maker->{quote_char} = $sql_maker->{quote_char};
1580       local $sql_maker->{name_sep} = $sql_maker->{name_sep};
1581       unless (defined $sql_maker->{quote_char} and length $sql_maker->{quote_char}) {
1582         $sql_maker->{quote_char} = [ "\x00", "\xFF" ];
1583         # if we don't unset it we screw up retarded but unfortunately working
1584         # 'MAX(foo.bar)' => { '>', 3 }
1585         $sql_maker->{name_sep} = '';
1586       }
1587
1588       my ($lquote, $rquote, $sep) = map { quotemeta $_ } ($sql_maker->_quote_chars, $sql_maker->name_sep);
1589
1590       my $having_sql = $sql_maker->_parse_rs_attrs ({ having => $attrs->{having} });
1591       my %seen_having;
1592
1593       # search for both a proper quoted qualified string, for a naive unquoted scalarref
1594       # and if all fails for an utterly naive quoted scalar-with-function
1595       while ($having_sql =~ /
1596         $rquote $sep $lquote (.+?) $rquote
1597           |
1598         [\s,] \w+ \. (\w+) [\s,]
1599           |
1600         [\s,] $lquote (.+?) $rquote [\s,]
1601       /gx) {
1602         my $part = $1 || $2 || $3;  # one of them matched if we got here
1603         unless ($seen_having{$part}++) {
1604           push @parts, $part;
1605         }
1606       }
1607     }
1608
1609     for (@parts) {
1610       my $colpiece = $sel_index->{$_} || $_;
1611
1612       # unqualify join-based group_by's. Arcane but possible query
1613       # also horrible horrible hack to alias a column (not a func.)
1614       # (probably need to introduce SQLA syntax)
1615       if ($colpiece =~ /\./ && $colpiece !~ /^$attrs->{alias}\./) {
1616         my $as = $colpiece;
1617         $as =~ s/\./__/;
1618         $colpiece = \ sprintf ('%s AS %s', map { $sql_maker->_quote ($_) } ($colpiece, $as) );
1619       }
1620       push @{$sub_attrs->{select}}, $colpiece;
1621     }
1622   }
1623   else {
1624     my @pcols = map { "$attrs->{alias}.$_" } ($rsrc->primary_columns);
1625     $sub_attrs->{select} = @pcols ? \@pcols : [ 1 ];
1626   }
1627
1628   return $rsrc->resultset_class
1629                ->new ($rsrc, $sub_attrs)
1630                 ->as_subselect_rs
1631                  ->search ({}, { columns => { count => $rsrc->storage->_count_select ($rsrc, $attrs) } })
1632                   ->get_column ('count');
1633 }
1634
1635 sub _bool {
1636   return 1;
1637 }
1638
1639 =head2 count_literal
1640
1641 B<CAVEAT>: C<count_literal> is provided for Class::DBI compatibility and
1642 should only be used in that context. See L</search_literal> for further info.
1643
1644 =over 4
1645
1646 =item Arguments: $sql_fragment, @standalone_bind_values
1647
1648 =item Return Value: $count
1649
1650 =back
1651
1652 Counts the results in a literal query. Equivalent to calling L</search_literal>
1653 with the passed arguments, then L</count>.
1654
1655 =cut
1656
1657 sub count_literal { shift->search_literal(@_)->count; }
1658
1659 =head2 all
1660
1661 =over 4
1662
1663 =item Arguments: none
1664
1665 =item Return Value: L<@result_objs|DBIx::Class::Manual::ResultClass>
1666
1667 =back
1668
1669 Returns all elements in the resultset.
1670
1671 =cut
1672
1673 sub all {
1674   my $self = shift;
1675   if(@_) {
1676     $self->throw_exception("all() doesn't take any arguments, you probably wanted ->search(...)->all()");
1677   }
1678
1679   delete @{$self}{qw/stashed_rows stashed_objects/};
1680
1681   if (my $c = $self->get_cache) {
1682     return @$c;
1683   }
1684
1685   $self->cursor->reset;
1686
1687   my $objs = $self->_construct_objects('fetch_all') || [];
1688
1689   $self->set_cache($objs) if $self->{attrs}{cache};
1690
1691   return @$objs;
1692 }
1693
1694 =head2 reset
1695
1696 =over 4
1697
1698 =item Arguments: none
1699
1700 =item Return Value: $self
1701
1702 =back
1703
1704 Resets the resultset's cursor, so you can iterate through the elements again.
1705 Implicitly resets the storage cursor, so a subsequent L</next> will trigger
1706 another query.
1707
1708 =cut
1709
1710 sub reset {
1711   my ($self) = @_;
1712
1713   delete @{$self}{qw/stashed_rows stashed_objects/};
1714   $self->{all_cache_position} = 0;
1715   $self->cursor->reset;
1716   return $self;
1717 }
1718
1719 =head2 first
1720
1721 =over 4
1722
1723 =item Arguments: none
1724
1725 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1726
1727 =back
1728
1729 L<Resets|/reset> the resultset (causing a fresh query to storage) and returns
1730 an object for the first result (or C<undef> if the resultset is empty).
1731
1732 =cut
1733
1734 sub first {
1735   return $_[0]->reset->next;
1736 }
1737
1738
1739 # _rs_update_delete
1740 #
1741 # Determines whether and what type of subquery is required for the $rs operation.
1742 # If grouping is necessary either supplies its own, or verifies the current one
1743 # After all is done delegates to the proper storage method.
1744
1745 sub _rs_update_delete {
1746   my ($self, $op, $values) = @_;
1747
1748   my $rsrc = $self->result_source;
1749   my $storage = $rsrc->schema->storage;
1750
1751   my $attrs = { %{$self->_resolved_attrs} };
1752
1753   my $join_classifications;
1754   my $existing_group_by = delete $attrs->{group_by};
1755
1756   # do we need a subquery for any reason?
1757   my $needs_subq = (
1758     defined $existing_group_by
1759       or
1760     # if {from} is unparseable wrap a subq
1761     ref($attrs->{from}) ne 'ARRAY'
1762       or
1763     # limits call for a subq
1764     $self->_has_resolved_attr(qw/rows offset/)
1765   );
1766
1767   # simplify the joinmap, so we can further decide if a subq is necessary
1768   if (!$needs_subq and @{$attrs->{from}} > 1) {
1769     $attrs->{from} = $storage->_prune_unused_joins ($attrs->{from}, $attrs->{select}, $self->{cond}, $attrs);
1770
1771     # check if there are any joins left after the prune
1772     if ( @{$attrs->{from}} > 1 ) {
1773       $join_classifications = $storage->_resolve_aliastypes_from_select_args (
1774         [ @{$attrs->{from}}[1 .. $#{$attrs->{from}}] ],
1775         $attrs->{select},
1776         $self->{cond},
1777         $attrs
1778       );
1779
1780       # any non-pruneable joins imply subq
1781       $needs_subq = scalar keys %{ $join_classifications->{restricting} || {} };
1782     }
1783   }
1784
1785   # check if the head is composite (by now all joins are thrown out unless $needs_subq)
1786   $needs_subq ||= (
1787     (ref $attrs->{from}[0]) ne 'HASH'
1788       or
1789     ref $attrs->{from}[0]{ $attrs->{from}[0]{-alias} }
1790   );
1791
1792   my ($cond, $guard);
1793   # do we need anything like a subquery?
1794   if (! $needs_subq) {
1795     # Most databases do not allow aliasing of tables in UPDATE/DELETE. Thus
1796     # a condition containing 'me' or other table prefixes will not work
1797     # at all. Tell SQLMaker to dequalify idents via a gross hack.
1798     $cond = do {
1799       my $sqla = $rsrc->storage->sql_maker;
1800       local $sqla->{_dequalify_idents} = 1;
1801       \[ $sqla->_recurse_where($self->{cond}) ];
1802     };
1803   }
1804   else {
1805     # we got this far - means it is time to wrap a subquery
1806     my $idcols = $rsrc->_identifying_column_set || $self->throw_exception(
1807       sprintf(
1808         "Unable to perform complex resultset %s() without an identifying set of columns on source '%s'",
1809         $op,
1810         $rsrc->source_name,
1811       )
1812     );
1813
1814     # make a new $rs selecting only the PKs (that's all we really need for the subq)
1815     delete $attrs->{$_} for qw/collapse select _prefetch_selector_range as/;
1816     $attrs->{columns} = [ map { "$attrs->{alias}.$_" } @$idcols ];
1817     $attrs->{group_by} = \ '';  # FIXME - this is an evil hack, it causes the optimiser to kick in and throw away the LEFT joins
1818     my $subrs = (ref $self)->new($rsrc, $attrs);
1819
1820     if (@$idcols == 1) {
1821       $cond = { $idcols->[0] => { -in => $subrs->as_query } };
1822     }
1823     elsif ($storage->_use_multicolumn_in) {
1824       # no syntax for calling this properly yet
1825       # !!! EXPERIMENTAL API !!! WILL CHANGE !!!
1826       $cond = $storage->sql_maker->_where_op_multicolumn_in (
1827         $idcols, # how do I convey a list of idents...? can binds reside on lhs?
1828         $subrs->as_query
1829       ),
1830     }
1831     else {
1832       # if all else fails - get all primary keys and operate over a ORed set
1833       # wrap in a transaction for consistency
1834       # this is where the group_by/multiplication starts to matter
1835       if (
1836         $existing_group_by
1837           or
1838         keys %{ $join_classifications->{multiplying} || {} }
1839       ) {
1840         # make sure if there is a supplied group_by it matches the columns compiled above
1841         # perfectly. Anything else can not be sanely executed on most databases so croak
1842         # right then and there
1843         if ($existing_group_by) {
1844           my @current_group_by = map
1845             { $_ =~ /\./ ? $_ : "$attrs->{alias}.$_" }
1846             @$existing_group_by
1847           ;
1848
1849           if (
1850             join ("\x00", sort @current_group_by)
1851               ne
1852             join ("\x00", sort @{$attrs->{columns}} )
1853           ) {
1854             $self->throw_exception (
1855               "You have just attempted a $op operation on a resultset which does group_by"
1856               . ' on columns other than the primary keys, while DBIC internally needs to retrieve'
1857               . ' the primary keys in a subselect. All sane RDBMS engines do not support this'
1858               . ' kind of queries. Please retry the operation with a modified group_by or'
1859               . ' without using one at all.'
1860             );
1861           }
1862         }
1863
1864         $subrs = $subrs->search({}, { group_by => $attrs->{columns} });
1865       }
1866
1867       $guard = $storage->txn_scope_guard;
1868
1869       $cond = [];
1870       for my $row ($subrs->cursor->all) {
1871         push @$cond, { map
1872           { $idcols->[$_] => $row->[$_] }
1873           (0 .. $#$idcols)
1874         };
1875       }
1876     }
1877   }
1878
1879   my $res = $storage->$op (
1880     $rsrc,
1881     $op eq 'update' ? $values : (),
1882     $cond,
1883   );
1884
1885   $guard->commit if $guard;
1886
1887   return $res;
1888 }
1889
1890 =head2 update
1891
1892 =over 4
1893
1894 =item Arguments: \%values
1895
1896 =item Return Value: $underlying_storage_rv
1897
1898 =back
1899
1900 Sets the specified columns in the resultset to the supplied values in a
1901 single query. Note that this will not run any accessor/set_column/update
1902 triggers, nor will it update any result object instances derived from this
1903 resultset (this includes the contents of the L<resultset cache|/set_cache>
1904 if any). See L</update_all> if you need to execute any on-update
1905 triggers or cascades defined either by you or a
1906 L<result component|DBIx::Class::Manual::Component/WHAT IS A COMPONENT>.
1907
1908 The return value is a pass through of what the underlying
1909 storage backend returned, and may vary. See L<DBI/execute> for the most
1910 common case.
1911
1912 =head3 CAVEAT
1913
1914 Note that L</update> does not process/deflate any of the values passed in.
1915 This is unlike the corresponding L<DBIx::Class::Row/update>. The user must
1916 ensure manually that any value passed to this method will stringify to
1917 something the RDBMS knows how to deal with. A notable example is the
1918 handling of L<DateTime> objects, for more info see:
1919 L<DBIx::Class::Manual::Cookbook/Formatting DateTime objects in queries>.
1920
1921 =cut
1922
1923 sub update {
1924   my ($self, $values) = @_;
1925   $self->throw_exception('Values for update must be a hash')
1926     unless ref $values eq 'HASH';
1927
1928   return $self->_rs_update_delete ('update', $values);
1929 }
1930
1931 =head2 update_all
1932
1933 =over 4
1934
1935 =item Arguments: \%values
1936
1937 =item Return Value: 1
1938
1939 =back
1940
1941 Fetches all objects and updates them one at a time via
1942 L<DBIx::Class::Row/update>. Note that C<update_all> will run DBIC defined
1943 triggers, while L</update> will not.
1944
1945 =cut
1946
1947 sub update_all {
1948   my ($self, $values) = @_;
1949   $self->throw_exception('Values for update_all must be a hash')
1950     unless ref $values eq 'HASH';
1951
1952   my $guard = $self->result_source->schema->txn_scope_guard;
1953   $_->update({%$values}) for $self->all;  # shallow copy - update will mangle it
1954   $guard->commit;
1955   return 1;
1956 }
1957
1958 =head2 delete
1959
1960 =over 4
1961
1962 =item Arguments: none
1963
1964 =item Return Value: $underlying_storage_rv
1965
1966 =back
1967
1968 Deletes the rows matching this resultset in a single query. Note that this
1969 will not run any delete triggers, nor will it alter the
1970 L<in_storage|DBIx::Class::Row/in_storage> status of any result object instances
1971 derived from this resultset (this includes the contents of the
1972 L<resultset cache|/set_cache> if any). See L</delete_all> if you need to
1973 execute any on-delete triggers or cascades defined either by you or a
1974 L<result component|DBIx::Class::Manual::Component/WHAT IS A COMPONENT>.
1975
1976 The return value is a pass through of what the underlying storage backend
1977 returned, and may vary. See L<DBI/execute> for the most common case.
1978
1979 =cut
1980
1981 sub delete {
1982   my $self = shift;
1983   $self->throw_exception('delete does not accept any arguments')
1984     if @_;
1985
1986   return $self->_rs_update_delete ('delete');
1987 }
1988
1989 =head2 delete_all
1990
1991 =over 4
1992
1993 =item Arguments: none
1994
1995 =item Return Value: 1
1996
1997 =back
1998
1999 Fetches all objects and deletes them one at a time via
2000 L<DBIx::Class::Row/delete>. Note that C<delete_all> will run DBIC defined
2001 triggers, while L</delete> will not.
2002
2003 =cut
2004
2005 sub delete_all {
2006   my $self = shift;
2007   $self->throw_exception('delete_all does not accept any arguments')
2008     if @_;
2009
2010   my $guard = $self->result_source->schema->txn_scope_guard;
2011   $_->delete for $self->all;
2012   $guard->commit;
2013   return 1;
2014 }
2015
2016 =head2 populate
2017
2018 =over 4
2019
2020 =item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ]
2021
2022 =item Return Value: L<\@result_objects|DBIx::Class::Manual::ResultClass> (scalar context) | L<@result_objects|DBIx::Class::Manual::ResultClass> (list context)
2023
2024 =back
2025
2026 Accepts either an arrayref of hashrefs or alternatively an arrayref of
2027 arrayrefs.
2028
2029 =over
2030
2031 =item NOTE
2032
2033 The context of this method call has an important effect on what is
2034 submitted to storage. In void context data is fed directly to fastpath
2035 insertion routines provided by the underlying storage (most often
2036 L<DBI/execute_for_fetch>), bypassing the L<new|DBIx::Class::Row/new> and
2037 L<insert|DBIx::Class::Row/insert> calls on the
2038 L<Result|DBIx::Class::Manual::ResultClass> class, including any
2039 augmentation of these methods provided by components. For example if you
2040 are using something like L<DBIx::Class::UUIDColumns> to create primary
2041 keys for you, you will find that your PKs are empty.  In this case you
2042 will have to explicitly force scalar or list context in order to create
2043 those values.
2044
2045 =back
2046
2047 In non-void (scalar or list) context, this method is simply a wrapper
2048 for L</create>. Depending on list or scalar context either a list of
2049 L<Result|DBIx::Class::Manual::ResultClass> objects or an arrayref
2050 containing these objects is returned.
2051
2052 When supplying data in "arrayref of arrayrefs" invocation style, the
2053 first element should be a list of column names and each subsequent
2054 element should be a data value in the earlier specified column order.
2055 For example:
2056
2057   $Arstist_rs->populate([
2058     [ qw( artistid name ) ],
2059     [ 100, 'A Formally Unknown Singer' ],
2060     [ 101, 'A singer that jumped the shark two albums ago' ],
2061     [ 102, 'An actually cool singer' ],
2062   ]);
2063
2064 For the arrayref of hashrefs style each hashref should be a structure
2065 suitable for passing to L</create>. Multi-create is also permitted with
2066 this syntax.
2067
2068   $schema->resultset("Artist")->populate([
2069      { artistid => 4, name => 'Manufactured Crap', cds => [
2070         { title => 'My First CD', year => 2006 },
2071         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
2072       ],
2073      },
2074      { artistid => 5, name => 'Angsty-Whiny Girl', cds => [
2075         { title => 'My parents sold me to a record company', year => 2005 },
2076         { title => 'Why Am I So Ugly?', year => 2006 },
2077         { title => 'I Got Surgery and am now Popular', year => 2007 }
2078       ],
2079      },
2080   ]);
2081
2082 If you attempt a void-context multi-create as in the example above (each
2083 Artist also has the related list of CDs), and B<do not> supply the
2084 necessary autoinc foreign key information, this method will proxy to the
2085 less efficient L</create>, and then throw the Result objects away. In this
2086 case there are obviously no benefits to using this method over L</create>.
2087
2088 =cut
2089
2090 sub populate {
2091   my $self = shift;
2092
2093   # cruft placed in standalone method
2094   my $data = $self->_normalize_populate_args(@_);
2095
2096   return unless @$data;
2097
2098   if(defined wantarray) {
2099     my @created = map { $self->create($_) } @$data;
2100     return wantarray ? @created : \@created;
2101   }
2102   else {
2103     my $first = $data->[0];
2104
2105     # if a column is a registered relationship, and is a non-blessed hash/array, consider
2106     # it relationship data
2107     my (@rels, @columns);
2108     my $rsrc = $self->result_source;
2109     my $rels = { map { $_ => $rsrc->relationship_info($_) } $rsrc->relationships };
2110     for (keys %$first) {
2111       my $ref = ref $first->{$_};
2112       $rels->{$_} && ($ref eq 'ARRAY' or $ref eq 'HASH')
2113         ? push @rels, $_
2114         : push @columns, $_
2115       ;
2116     }
2117
2118     my @pks = $rsrc->primary_columns;
2119
2120     ## do the belongs_to relationships
2121     foreach my $index (0..$#$data) {
2122
2123       # delegate to create() for any dataset without primary keys with specified relationships
2124       if (grep { !defined $data->[$index]->{$_} } @pks ) {
2125         for my $r (@rels) {
2126           if (grep { ref $data->[$index]{$r} eq $_ } qw/HASH ARRAY/) {  # a related set must be a HASH or AoH
2127             my @ret = $self->populate($data);
2128             return;
2129           }
2130         }
2131       }
2132
2133       foreach my $rel (@rels) {
2134         next unless ref $data->[$index]->{$rel} eq "HASH";
2135         my $result = $self->related_resultset($rel)->create($data->[$index]->{$rel});
2136         my ($reverse_relname, $reverse_relinfo) = %{$rsrc->reverse_relationship_info($rel)};
2137         my $related = $result->result_source->_resolve_condition(
2138           $reverse_relinfo->{cond},
2139           $self,
2140           $result,
2141           $rel,
2142         );
2143
2144         delete $data->[$index]->{$rel};
2145         $data->[$index] = {%{$data->[$index]}, %$related};
2146
2147         push @columns, keys %$related if $index == 0;
2148       }
2149     }
2150
2151     ## inherit the data locked in the conditions of the resultset
2152     my ($rs_data) = $self->_merge_with_rscond({});
2153     delete @{$rs_data}{@columns};
2154
2155     ## do bulk insert on current row
2156     $rsrc->storage->insert_bulk(
2157       $rsrc,
2158       [@columns, keys %$rs_data],
2159       [ map { [ @$_{@columns}, values %$rs_data ] } @$data ],
2160     );
2161
2162     ## do the has_many relationships
2163     foreach my $item (@$data) {
2164
2165       my $main_row;
2166
2167       foreach my $rel (@rels) {
2168         next unless ref $item->{$rel} eq "ARRAY" && @{ $item->{$rel} };
2169
2170         $main_row ||= $self->new_result({map { $_ => $item->{$_} } @pks});
2171
2172         my $child = $main_row->$rel;
2173
2174         my $related = $child->result_source->_resolve_condition(
2175           $rels->{$rel}{cond},
2176           $child,
2177           $main_row,
2178           $rel,
2179         );
2180
2181         my @rows_to_add = ref $item->{$rel} eq 'ARRAY' ? @{$item->{$rel}} : ($item->{$rel});
2182         my @populate = map { {%$_, %$related} } @rows_to_add;
2183
2184         $child->populate( \@populate );
2185       }
2186     }
2187   }
2188 }
2189
2190
2191 # populate() argumnets went over several incarnations
2192 # What we ultimately support is AoH
2193 sub _normalize_populate_args {
2194   my ($self, $arg) = @_;
2195
2196   if (ref $arg eq 'ARRAY') {
2197     if (!@$arg) {
2198       return [];
2199     }
2200     elsif (ref $arg->[0] eq 'HASH') {
2201       return $arg;
2202     }
2203     elsif (ref $arg->[0] eq 'ARRAY') {
2204       my @ret;
2205       my @colnames = @{$arg->[0]};
2206       foreach my $values (@{$arg}[1 .. $#$arg]) {
2207         push @ret, { map { $colnames[$_] => $values->[$_] } (0 .. $#colnames) };
2208       }
2209       return \@ret;
2210     }
2211   }
2212
2213   $self->throw_exception('Populate expects an arrayref of hashrefs or arrayref of arrayrefs');
2214 }
2215
2216 =head2 pager
2217
2218 =over 4
2219
2220 =item Arguments: none
2221
2222 =item Return Value: L<$pager|Data::Page>
2223
2224 =back
2225
2226 Returns a L<Data::Page> object for the current resultset. Only makes
2227 sense for queries with a C<page> attribute.
2228
2229 To get the full count of entries for a paged resultset, call
2230 C<total_entries> on the L<Data::Page> object.
2231
2232 =cut
2233
2234 sub pager {
2235   my ($self) = @_;
2236
2237   return $self->{pager} if $self->{pager};
2238
2239   my $attrs = $self->{attrs};
2240   if (!defined $attrs->{page}) {
2241     $self->throw_exception("Can't create pager for non-paged rs");
2242   }
2243   elsif ($attrs->{page} <= 0) {
2244     $self->throw_exception('Invalid page number (page-numbers are 1-based)');
2245   }
2246   $attrs->{rows} ||= 10;
2247
2248   # throw away the paging flags and re-run the count (possibly
2249   # with a subselect) to get the real total count
2250   my $count_attrs = { %$attrs };
2251   delete @{$count_attrs}{qw/rows offset page pager/};
2252
2253   my $total_rs = (ref $self)->new($self->result_source, $count_attrs);
2254
2255   require DBIx::Class::ResultSet::Pager;
2256   return $self->{pager} = DBIx::Class::ResultSet::Pager->new(
2257     sub { $total_rs->count },  #lazy-get the total
2258     $attrs->{rows},
2259     $self->{attrs}{page},
2260   );
2261 }
2262
2263 =head2 page
2264
2265 =over 4
2266
2267 =item Arguments: $page_number
2268
2269 =item Return Value: L<$resultset|/search>
2270
2271 =back
2272
2273 Returns a resultset for the $page_number page of the resultset on which page
2274 is called, where each page contains a number of rows equal to the 'rows'
2275 attribute set on the resultset (10 by default).
2276
2277 =cut
2278
2279 sub page {
2280   my ($self, $page) = @_;
2281   return (ref $self)->new($self->result_source, { %{$self->{attrs}}, page => $page });
2282 }
2283
2284 =head2 new_result
2285
2286 =over 4
2287
2288 =item Arguments: \%col_data
2289
2290 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2291
2292 =back
2293
2294 Creates a new result object in the resultset's result class and returns
2295 it. The row is not inserted into the database at this point, call
2296 L<DBIx::Class::Row/insert> to do that. Calling L<DBIx::Class::Row/in_storage>
2297 will tell you whether the result object has been inserted or not.
2298
2299 Passes the hashref of input on to L<DBIx::Class::Row/new>.
2300
2301 =cut
2302
2303 sub new_result {
2304   my ($self, $values) = @_;
2305
2306   $self->throw_exception( "new_result takes only one argument - a hashref of values" )
2307     if @_ > 2;
2308
2309   $self->throw_exception( "new_result expects a hashref" )
2310     unless (ref $values eq 'HASH');
2311
2312   my ($merged_cond, $cols_from_relations) = $self->_merge_with_rscond($values);
2313
2314   my %new = (
2315     %$merged_cond,
2316     @$cols_from_relations
2317       ? (-cols_from_relations => $cols_from_relations)
2318       : (),
2319     -result_source => $self->result_source, # DO NOT REMOVE THIS, REQUIRED
2320   );
2321
2322   return $self->result_class->new(\%new);
2323 }
2324
2325 # _merge_with_rscond
2326 #
2327 # Takes a simple hash of K/V data and returns its copy merged with the
2328 # condition already present on the resultset. Additionally returns an
2329 # arrayref of value/condition names, which were inferred from related
2330 # objects (this is needed for in-memory related objects)
2331 sub _merge_with_rscond {
2332   my ($self, $data) = @_;
2333
2334   my (%new_data, @cols_from_relations);
2335
2336   my $alias = $self->{attrs}{alias};
2337
2338   if (! defined $self->{cond}) {
2339     # just massage $data below
2340   }
2341   elsif ($self->{cond} eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
2342     %new_data = %{ $self->{attrs}{related_objects} || {} };  # nothing might have been inserted yet
2343     @cols_from_relations = keys %new_data;
2344   }
2345   elsif (ref $self->{cond} ne 'HASH') {
2346     $self->throw_exception(
2347       "Can't abstract implicit construct, resultset condition not a hash"
2348     );
2349   }
2350   else {
2351     # precendence must be given to passed values over values inherited from
2352     # the cond, so the order here is important.
2353     my $collapsed_cond = $self->_collapse_cond($self->{cond});
2354     my %implied = %{$self->_remove_alias($collapsed_cond, $alias)};
2355
2356     while ( my($col, $value) = each %implied ) {
2357       my $vref = ref $value;
2358       if (
2359         $vref eq 'HASH'
2360           and
2361         keys(%$value) == 1
2362           and
2363         (keys %$value)[0] eq '='
2364       ) {
2365         $new_data{$col} = $value->{'='};
2366       }
2367       elsif( !$vref or $vref eq 'SCALAR' or blessed($value) ) {
2368         $new_data{$col} = $value;
2369       }
2370     }
2371   }
2372
2373   %new_data = (
2374     %new_data,
2375     %{ $self->_remove_alias($data, $alias) },
2376   );
2377
2378   return (\%new_data, \@cols_from_relations);
2379 }
2380
2381 # _has_resolved_attr
2382 #
2383 # determines if the resultset defines at least one
2384 # of the attributes supplied
2385 #
2386 # used to determine if a subquery is neccessary
2387 #
2388 # supports some virtual attributes:
2389 #   -join
2390 #     This will scan for any joins being present on the resultset.
2391 #     It is not a mere key-search but a deep inspection of {from}
2392 #
2393
2394 sub _has_resolved_attr {
2395   my ($self, @attr_names) = @_;
2396
2397   my $attrs = $self->_resolved_attrs;
2398
2399   my %extra_checks;
2400
2401   for my $n (@attr_names) {
2402     if (grep { $n eq $_ } (qw/-join/) ) {
2403       $extra_checks{$n}++;
2404       next;
2405     }
2406
2407     my $attr =  $attrs->{$n};
2408
2409     next if not defined $attr;
2410
2411     if (ref $attr eq 'HASH') {
2412       return 1 if keys %$attr;
2413     }
2414     elsif (ref $attr eq 'ARRAY') {
2415       return 1 if @$attr;
2416     }
2417     else {
2418       return 1 if $attr;
2419     }
2420   }
2421
2422   # a resolved join is expressed as a multi-level from
2423   return 1 if (
2424     $extra_checks{-join}
2425       and
2426     ref $attrs->{from} eq 'ARRAY'
2427       and
2428     @{$attrs->{from}} > 1
2429   );
2430
2431   return 0;
2432 }
2433
2434 # _collapse_cond
2435 #
2436 # Recursively collapse the condition.
2437
2438 sub _collapse_cond {
2439   my ($self, $cond, $collapsed) = @_;
2440
2441   $collapsed ||= {};
2442
2443   if (ref $cond eq 'ARRAY') {
2444     foreach my $subcond (@$cond) {
2445       next unless ref $subcond;  # -or
2446       $collapsed = $self->_collapse_cond($subcond, $collapsed);
2447     }
2448   }
2449   elsif (ref $cond eq 'HASH') {
2450     if (keys %$cond and (keys %$cond)[0] eq '-and') {
2451       foreach my $subcond (@{$cond->{-and}}) {
2452         $collapsed = $self->_collapse_cond($subcond, $collapsed);
2453       }
2454     }
2455     else {
2456       foreach my $col (keys %$cond) {
2457         my $value = $cond->{$col};
2458         $collapsed->{$col} = $value;
2459       }
2460     }
2461   }
2462
2463   return $collapsed;
2464 }
2465
2466 # _remove_alias
2467 #
2468 # Remove the specified alias from the specified query hash. A copy is made so
2469 # the original query is not modified.
2470
2471 sub _remove_alias {
2472   my ($self, $query, $alias) = @_;
2473
2474   my %orig = %{ $query || {} };
2475   my %unaliased;
2476
2477   foreach my $key (keys %orig) {
2478     if ($key !~ /\./) {
2479       $unaliased{$key} = $orig{$key};
2480       next;
2481     }
2482     $unaliased{$1} = $orig{$key}
2483       if $key =~ m/^(?:\Q$alias\E\.)?([^.]+)$/;
2484   }
2485
2486   return \%unaliased;
2487 }
2488
2489 =head2 as_query
2490
2491 =over 4
2492
2493 =item Arguments: none
2494
2495 =item Return Value: \[ $sql, L<@bind_values|/DBIC BIND VALUES> ]
2496
2497 =back
2498
2499 Returns the SQL query and bind vars associated with the invocant.
2500
2501 This is generally used as the RHS for a subquery.
2502
2503 =cut
2504
2505 sub as_query {
2506   my $self = shift;
2507
2508   my $attrs = { %{ $self->_resolved_attrs } };
2509
2510   # For future use:
2511   #
2512   # in list ctx:
2513   # my ($sql, \@bind, \%dbi_bind_attrs) = _select_args_to_query (...)
2514   # $sql also has no wrapping parenthesis in list ctx
2515   #
2516   my $sqlbind = $self->result_source->storage
2517     ->_select_args_to_query ($attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs);
2518
2519   return $sqlbind;
2520 }
2521
2522 =head2 find_or_new
2523
2524 =over 4
2525
2526 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2527
2528 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2529
2530 =back
2531
2532   my $artist = $schema->resultset('Artist')->find_or_new(
2533     { artist => 'fred' }, { key => 'artists' });
2534
2535   $cd->cd_to_producer->find_or_new({ producer => $producer },
2536                                    { key => 'primary });
2537
2538 Find an existing record from this resultset using L</find>. if none exists,
2539 instantiate a new result object and return it. The object will not be saved
2540 into your storage until you call L<DBIx::Class::Row/insert> on it.
2541
2542 You most likely want this method when looking for existing rows using a unique
2543 constraint that is not the primary key, or looking for related rows.
2544
2545 If you want objects to be saved immediately, use L</find_or_create> instead.
2546
2547 B<Note>: Make sure to read the documentation of L</find> and understand the
2548 significance of the C<key> attribute, as its lack may skew your search, and
2549 subsequently result in spurious new objects.
2550
2551 B<Note>: Take care when using C<find_or_new> with a table having
2552 columns with default values that you intend to be automatically
2553 supplied by the database (e.g. an auto_increment primary key column).
2554 In normal usage, the value of such columns should NOT be included at
2555 all in the call to C<find_or_new>, even when set to C<undef>.
2556
2557 =cut
2558
2559 sub find_or_new {
2560   my $self     = shift;
2561   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2562   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2563   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2564     return $row;
2565   }
2566   return $self->new_result($hash);
2567 }
2568
2569 =head2 create
2570
2571 =over 4
2572
2573 =item Arguments: \%col_data
2574
2575 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2576
2577 =back
2578
2579 Attempt to create a single new row or a row with multiple related rows
2580 in the table represented by the resultset (and related tables). This
2581 will not check for duplicate rows before inserting, use
2582 L</find_or_create> to do that.
2583
2584 To create one row for this resultset, pass a hashref of key/value
2585 pairs representing the columns of the table and the values you wish to
2586 store. If the appropriate relationships are set up, foreign key fields
2587 can also be passed an object representing the foreign row, and the
2588 value will be set to its primary key.
2589
2590 To create related objects, pass a hashref of related-object column values
2591 B<keyed on the relationship name>. If the relationship is of type C<multi>
2592 (L<DBIx::Class::Relationship/has_many>) - pass an arrayref of hashrefs.
2593 The process will correctly identify columns holding foreign keys, and will
2594 transparently populate them from the keys of the corresponding relation.
2595 This can be applied recursively, and will work correctly for a structure
2596 with an arbitrary depth and width, as long as the relationships actually
2597 exists and the correct column data has been supplied.
2598
2599 Instead of hashrefs of plain related data (key/value pairs), you may
2600 also pass new or inserted objects. New objects (not inserted yet, see
2601 L</new_result>), will be inserted into their appropriate tables.
2602
2603 Effectively a shortcut for C<< ->new_result(\%col_data)->insert >>.
2604
2605 Example of creating a new row.
2606
2607   $person_rs->create({
2608     name=>"Some Person",
2609     email=>"somebody@someplace.com"
2610   });
2611
2612 Example of creating a new row and also creating rows in a related C<has_many>
2613 or C<has_one> resultset.  Note Arrayref.
2614
2615   $artist_rs->create(
2616      { artistid => 4, name => 'Manufactured Crap', cds => [
2617         { title => 'My First CD', year => 2006 },
2618         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
2619       ],
2620      },
2621   );
2622
2623 Example of creating a new row and also creating a row in a related
2624 C<belongs_to> resultset. Note Hashref.
2625
2626   $cd_rs->create({
2627     title=>"Music for Silly Walks",
2628     year=>2000,
2629     artist => {
2630       name=>"Silly Musician",
2631     }
2632   });
2633
2634 =over
2635
2636 =item WARNING
2637
2638 When subclassing ResultSet never attempt to override this method. Since
2639 it is a simple shortcut for C<< $self->new_result($attrs)->insert >>, a
2640 lot of the internals simply never call it, so your override will be
2641 bypassed more often than not. Override either L<DBIx::Class::Row/new>
2642 or L<DBIx::Class::Row/insert> depending on how early in the
2643 L</create> process you need to intervene. See also warning pertaining to
2644 L</new>.
2645
2646 =back
2647
2648 =cut
2649
2650 sub create {
2651   my ($self, $attrs) = @_;
2652   $self->throw_exception( "create needs a hashref" )
2653     unless ref $attrs eq 'HASH';
2654   return $self->new_result($attrs)->insert;
2655 }
2656
2657 =head2 find_or_create
2658
2659 =over 4
2660
2661 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2662
2663 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2664
2665 =back
2666
2667   $cd->cd_to_producer->find_or_create({ producer => $producer },
2668                                       { key => 'primary' });
2669
2670 Tries to find a record based on its primary key or unique constraints; if none
2671 is found, creates one and returns that instead.
2672
2673   my $cd = $schema->resultset('CD')->find_or_create({
2674     cdid   => 5,
2675     artist => 'Massive Attack',
2676     title  => 'Mezzanine',
2677     year   => 2005,
2678   });
2679
2680 Also takes an optional C<key> attribute, to search by a specific key or unique
2681 constraint. For example:
2682
2683   my $cd = $schema->resultset('CD')->find_or_create(
2684     {
2685       artist => 'Massive Attack',
2686       title  => 'Mezzanine',
2687     },
2688     { key => 'cd_artist_title' }
2689   );
2690
2691 B<Note>: Make sure to read the documentation of L</find> and understand the
2692 significance of the C<key> attribute, as its lack may skew your search, and
2693 subsequently result in spurious row creation.
2694
2695 B<Note>: Because find_or_create() reads from the database and then
2696 possibly inserts based on the result, this method is subject to a race
2697 condition. Another process could create a record in the table after
2698 the find has completed and before the create has started. To avoid
2699 this problem, use find_or_create() inside a transaction.
2700
2701 B<Note>: Take care when using C<find_or_create> with a table having
2702 columns with default values that you intend to be automatically
2703 supplied by the database (e.g. an auto_increment primary key column).
2704 In normal usage, the value of such columns should NOT be included at
2705 all in the call to C<find_or_create>, even when set to C<undef>.
2706
2707 See also L</find> and L</update_or_create>. For information on how to declare
2708 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
2709
2710 If you need to know if an existing row was found or a new one created use
2711 L</find_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
2712 to call L<DBIx::Class::Row/insert> to save the newly created row to the
2713 database!
2714
2715   my $cd = $schema->resultset('CD')->find_or_new({
2716     cdid   => 5,
2717     artist => 'Massive Attack',
2718     title  => 'Mezzanine',
2719     year   => 2005,
2720   });
2721
2722   if( !$cd->in_storage ) {
2723       # do some stuff
2724       $cd->insert;
2725   }
2726
2727 =cut
2728
2729 sub find_or_create {
2730   my $self     = shift;
2731   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2732   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2733   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2734     return $row;
2735   }
2736   return $self->create($hash);
2737 }
2738
2739 =head2 update_or_create
2740
2741 =over 4
2742
2743 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2744
2745 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2746
2747 =back
2748
2749   $resultset->update_or_create({ col => $val, ... });
2750
2751 Like L</find_or_create>, but if a row is found it is immediately updated via
2752 C<< $found_row->update (\%col_data) >>.
2753
2754
2755 Takes an optional C<key> attribute to search on a specific unique constraint.
2756 For example:
2757
2758   # In your application
2759   my $cd = $schema->resultset('CD')->update_or_create(
2760     {
2761       artist => 'Massive Attack',
2762       title  => 'Mezzanine',
2763       year   => 1998,
2764     },
2765     { key => 'cd_artist_title' }
2766   );
2767
2768   $cd->cd_to_producer->update_or_create({
2769     producer => $producer,
2770     name => 'harry',
2771   }, {
2772     key => 'primary',
2773   });
2774
2775 B<Note>: Make sure to read the documentation of L</find> and understand the
2776 significance of the C<key> attribute, as its lack may skew your search, and
2777 subsequently result in spurious row creation.
2778
2779 B<Note>: Take care when using C<update_or_create> with a table having
2780 columns with default values that you intend to be automatically
2781 supplied by the database (e.g. an auto_increment primary key column).
2782 In normal usage, the value of such columns should NOT be included at
2783 all in the call to C<update_or_create>, even when set to C<undef>.
2784
2785 See also L</find> and L</find_or_create>. For information on how to declare
2786 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
2787
2788 If you need to know if an existing row was updated or a new one created use
2789 L</update_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
2790 to call L<DBIx::Class::Row/insert> to save the newly created row to the
2791 database!
2792
2793 =cut
2794
2795 sub update_or_create {
2796   my $self = shift;
2797   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2798   my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
2799
2800   my $row = $self->find($cond, $attrs);
2801   if (defined $row) {
2802     $row->update($cond);
2803     return $row;
2804   }
2805
2806   return $self->create($cond);
2807 }
2808
2809 =head2 update_or_new
2810
2811 =over 4
2812
2813 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2814
2815 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2816
2817 =back
2818
2819   $resultset->update_or_new({ col => $val, ... });
2820
2821 Like L</find_or_new> but if a row is found it is immediately updated via
2822 C<< $found_row->update (\%col_data) >>.
2823
2824 For example:
2825
2826   # In your application
2827   my $cd = $schema->resultset('CD')->update_or_new(
2828     {
2829       artist => 'Massive Attack',
2830       title  => 'Mezzanine',
2831       year   => 1998,
2832     },
2833     { key => 'cd_artist_title' }
2834   );
2835
2836   if ($cd->in_storage) {
2837       # the cd was updated
2838   }
2839   else {
2840       # the cd is not yet in the database, let's insert it
2841       $cd->insert;
2842   }
2843
2844 B<Note>: Make sure to read the documentation of L</find> and understand the
2845 significance of the C<key> attribute, as its lack may skew your search, and
2846 subsequently result in spurious new objects.
2847
2848 B<Note>: Take care when using C<update_or_new> with a table having
2849 columns with default values that you intend to be automatically
2850 supplied by the database (e.g. an auto_increment primary key column).
2851 In normal usage, the value of such columns should NOT be included at
2852 all in the call to C<update_or_new>, even when set to C<undef>.
2853
2854 See also L</find>, L</find_or_create> and L</find_or_new>.
2855
2856 =cut
2857
2858 sub update_or_new {
2859     my $self  = shift;
2860     my $attrs = ( @_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {} );
2861     my $cond  = ref $_[0] eq 'HASH' ? shift : {@_};
2862
2863     my $row = $self->find( $cond, $attrs );
2864     if ( defined $row ) {
2865         $row->update($cond);
2866         return $row;
2867     }
2868
2869     return $self->new_result($cond);
2870 }
2871
2872 =head2 get_cache
2873
2874 =over 4
2875
2876 =item Arguments: none
2877
2878 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass> | undef
2879
2880 =back
2881
2882 Gets the contents of the cache for the resultset, if the cache is set.
2883
2884 The cache is populated either by using the L</prefetch> attribute to
2885 L</search> or by calling L</set_cache>.
2886
2887 =cut
2888
2889 sub get_cache {
2890   shift->{all_cache};
2891 }
2892
2893 =head2 set_cache
2894
2895 =over 4
2896
2897 =item Arguments: L<\@result_objs|DBIx::Class::Manual::ResultClass>
2898
2899 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass>
2900
2901 =back
2902
2903 Sets the contents of the cache for the resultset. Expects an arrayref
2904 of objects of the same class as those produced by the resultset. Note that
2905 if the cache is set, the resultset will return the cached objects rather
2906 than re-querying the database even if the cache attr is not set.
2907
2908 The contents of the cache can also be populated by using the
2909 L</prefetch> attribute to L</search>.
2910
2911 =cut
2912
2913 sub set_cache {
2914   my ( $self, $data ) = @_;
2915   $self->throw_exception("set_cache requires an arrayref")
2916       if defined($data) && (ref $data ne 'ARRAY');
2917   $self->{all_cache} = $data;
2918 }
2919
2920 =head2 clear_cache
2921
2922 =over 4
2923
2924 =item Arguments: none
2925
2926 =item Return Value: undef
2927
2928 =back
2929
2930 Clears the cache for the resultset.
2931
2932 =cut
2933
2934 sub clear_cache {
2935   shift->set_cache(undef);
2936 }
2937
2938 =head2 is_paged
2939
2940 =over 4
2941
2942 =item Arguments: none
2943
2944 =item Return Value: true, if the resultset has been paginated
2945
2946 =back
2947
2948 =cut
2949
2950 sub is_paged {
2951   my ($self) = @_;
2952   return !!$self->{attrs}{page};
2953 }
2954
2955 =head2 is_ordered
2956
2957 =over 4
2958
2959 =item Arguments: none
2960
2961 =item Return Value: true, if the resultset has been ordered with C<order_by>.
2962
2963 =back
2964
2965 =cut
2966
2967 sub is_ordered {
2968   my ($self) = @_;
2969   return scalar $self->result_source->storage->_extract_order_criteria($self->{attrs}{order_by});
2970 }
2971
2972 =head2 related_resultset
2973
2974 =over 4
2975
2976 =item Arguments: $rel_name
2977
2978 =item Return Value: L<$resultset|/search>
2979
2980 =back
2981
2982 Returns a related resultset for the supplied relationship name.
2983
2984   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
2985
2986 =cut
2987
2988 sub related_resultset {
2989   my ($self, $rel) = @_;
2990
2991   $self->{related_resultsets} ||= {};
2992   return $self->{related_resultsets}{$rel} ||= do {
2993     my $rsrc = $self->result_source;
2994     my $rel_info = $rsrc->relationship_info($rel);
2995
2996     $self->throw_exception(
2997       "search_related: result source '" . $rsrc->source_name .
2998         "' has no such relationship $rel")
2999       unless $rel_info;
3000
3001     my $attrs = $self->_chain_relationship($rel);
3002
3003     my $join_count = $attrs->{seen_join}{$rel};
3004
3005     my $alias = $self->result_source->storage
3006         ->relname_to_table_alias($rel, $join_count);
3007
3008     # since this is search_related, and we already slid the select window inwards
3009     # (the select/as attrs were deleted in the beginning), we need to flip all
3010     # left joins to inner, so we get the expected results
3011     # read the comment on top of the actual function to see what this does
3012     $attrs->{from} = $rsrc->schema->storage->_inner_join_to_node ($attrs->{from}, $alias);
3013
3014
3015     #XXX - temp fix for result_class bug. There likely is a more elegant fix -groditi
3016     delete @{$attrs}{qw(result_class alias)};
3017
3018     my $new_cache;
3019
3020     if (my $cache = $self->get_cache) {
3021       if ($cache->[0] && $cache->[0]->related_resultset($rel)->get_cache) {
3022         $new_cache = [ map { @{$_->related_resultset($rel)->get_cache||[]} }
3023                         @$cache ];
3024       }
3025     }
3026
3027     my $rel_source = $rsrc->related_source($rel);
3028
3029     my $new = do {
3030
3031       # The reason we do this now instead of passing the alias to the
3032       # search_rs below is that if you wrap/overload resultset on the
3033       # source you need to know what alias it's -going- to have for things
3034       # to work sanely (e.g. RestrictWithObject wants to be able to add
3035       # extra query restrictions, and these may need to be $alias.)
3036
3037       my $rel_attrs = $rel_source->resultset_attributes;
3038       local $rel_attrs->{alias} = $alias;
3039
3040       $rel_source->resultset
3041                  ->search_rs(
3042                      undef, {
3043                        %$attrs,
3044                        where => $attrs->{where},
3045                    });
3046     };
3047     $new->set_cache($new_cache) if $new_cache;
3048     $new;
3049   };
3050 }
3051
3052 =head2 current_source_alias
3053
3054 =over 4
3055
3056 =item Arguments: none
3057
3058 =item Return Value: $source_alias
3059
3060 =back
3061
3062 Returns the current table alias for the result source this resultset is built
3063 on, that will be used in the SQL query. Usually it is C<me>.
3064
3065 Currently the source alias that refers to the result set returned by a
3066 L</search>/L</find> family method depends on how you got to the resultset: it's
3067 C<me> by default, but eg. L</search_related> aliases it to the related result
3068 source name (and keeps C<me> referring to the original result set). The long
3069 term goal is to make L<DBIx::Class> always alias the current resultset as C<me>
3070 (and make this method unnecessary).
3071
3072 Thus it's currently necessary to use this method in predefined queries (see
3073 L<DBIx::Class::Manual::Cookbook/Predefined searches>) when referring to the
3074 source alias of the current result set:
3075
3076   # in a result set class
3077   sub modified_by {
3078     my ($self, $user) = @_;
3079
3080     my $me = $self->current_source_alias;
3081
3082     return $self->search({
3083       "$me.modified" => $user->id,
3084     });
3085   }
3086
3087 =cut
3088
3089 sub current_source_alias {
3090   return (shift->{attrs} || {})->{alias} || 'me';
3091 }
3092
3093 =head2 as_subselect_rs
3094
3095 =over 4
3096
3097 =item Arguments: none
3098
3099 =item Return Value: L<$resultset|/search>
3100
3101 =back
3102
3103 Act as a barrier to SQL symbols.  The resultset provided will be made into a
3104 "virtual view" by including it as a subquery within the from clause.  From this
3105 point on, any joined tables are inaccessible to ->search on the resultset (as if
3106 it were simply where-filtered without joins).  For example:
3107
3108  my $rs = $schema->resultset('Bar')->search({'x.name' => 'abc'},{ join => 'x' });
3109
3110  # 'x' now pollutes the query namespace
3111
3112  # So the following works as expected
3113  my $ok_rs = $rs->search({'x.other' => 1});
3114
3115  # But this doesn't: instead of finding a 'Bar' related to two x rows (abc and
3116  # def) we look for one row with contradictory terms and join in another table
3117  # (aliased 'x_2') which we never use
3118  my $broken_rs = $rs->search({'x.name' => 'def'});
3119
3120  my $rs2 = $rs->as_subselect_rs;
3121
3122  # doesn't work - 'x' is no longer accessible in $rs2, having been sealed away
3123  my $not_joined_rs = $rs2->search({'x.other' => 1});
3124
3125  # works as expected: finds a 'table' row related to two x rows (abc and def)
3126  my $correctly_joined_rs = $rs2->search({'x.name' => 'def'});
3127
3128 Another example of when one might use this would be to select a subset of
3129 columns in a group by clause:
3130
3131  my $rs = $schema->resultset('Bar')->search(undef, {
3132    group_by => [qw{ id foo_id baz_id }],
3133  })->as_subselect_rs->search(undef, {
3134    columns => [qw{ id foo_id }]
3135  });
3136
3137 In the above example normally columns would have to be equal to the group by,
3138 but because we isolated the group by into a subselect the above works.
3139
3140 =cut
3141
3142 sub as_subselect_rs {
3143   my $self = shift;
3144
3145   my $attrs = $self->_resolved_attrs;
3146
3147   my $fresh_rs = (ref $self)->new (
3148     $self->result_source
3149   );
3150
3151   # these pieces will be locked in the subquery
3152   delete $fresh_rs->{cond};
3153   delete @{$fresh_rs->{attrs}}{qw/where bind/};
3154
3155   return $fresh_rs->search( {}, {
3156     from => [{
3157       $attrs->{alias} => $self->as_query,
3158       -alias  => $attrs->{alias},
3159       -rsrc   => $self->result_source,
3160     }],
3161     alias => $attrs->{alias},
3162   });
3163 }
3164
3165 # This code is called by search_related, and makes sure there
3166 # is clear separation between the joins before, during, and
3167 # after the relationship. This information is needed later
3168 # in order to properly resolve prefetch aliases (any alias
3169 # with a relation_chain_depth less than the depth of the
3170 # current prefetch is not considered)
3171 #
3172 # The increments happen twice per join. An even number means a
3173 # relationship specified via a search_related, whereas an odd
3174 # number indicates a join/prefetch added via attributes
3175 #
3176 # Also this code will wrap the current resultset (the one we
3177 # chain to) in a subselect IFF it contains limiting attributes
3178 sub _chain_relationship {
3179   my ($self, $rel) = @_;
3180   my $source = $self->result_source;
3181   my $attrs = { %{$self->{attrs}||{}} };
3182
3183   # we need to take the prefetch the attrs into account before we
3184   # ->_resolve_join as otherwise they get lost - captainL
3185   my $join = $self->_merge_joinpref_attr( $attrs->{join}, $attrs->{prefetch} );
3186
3187   delete @{$attrs}{qw/join prefetch collapse group_by distinct select as columns +select +as +columns/};
3188
3189   my $seen = { %{ (delete $attrs->{seen_join}) || {} } };
3190
3191   my $from;
3192   my @force_subq_attrs = qw/offset rows group_by having/;
3193
3194   if (
3195     ($attrs->{from} && ref $attrs->{from} ne 'ARRAY')
3196       ||
3197     $self->_has_resolved_attr (@force_subq_attrs)
3198   ) {
3199     # Nuke the prefetch (if any) before the new $rs attrs
3200     # are resolved (prefetch is useless - we are wrapping
3201     # a subquery anyway).
3202     my $rs_copy = $self->search;
3203     $rs_copy->{attrs}{join} = $self->_merge_joinpref_attr (
3204       $rs_copy->{attrs}{join},
3205       delete $rs_copy->{attrs}{prefetch},
3206     );
3207
3208     $from = [{
3209       -rsrc   => $source,
3210       -alias  => $attrs->{alias},
3211       $attrs->{alias} => $rs_copy->as_query,
3212     }];
3213     delete @{$attrs}{@force_subq_attrs, qw/where bind/};
3214     $seen->{-relation_chain_depth} = 0;
3215   }
3216   elsif ($attrs->{from}) {  #shallow copy suffices
3217     $from = [ @{$attrs->{from}} ];
3218   }
3219   else {
3220     $from = [{
3221       -rsrc  => $source,
3222       -alias => $attrs->{alias},
3223       $attrs->{alias} => $source->from,
3224     }];
3225   }
3226
3227   my $jpath = ($seen->{-relation_chain_depth})
3228     ? $from->[-1][0]{-join_path}
3229     : [];
3230
3231   my @requested_joins = $source->_resolve_join(
3232     $join,
3233     $attrs->{alias},
3234     $seen,
3235     $jpath,
3236   );
3237
3238   push @$from, @requested_joins;
3239
3240   $seen->{-relation_chain_depth}++;
3241
3242   # if $self already had a join/prefetch specified on it, the requested
3243   # $rel might very well be already included. What we do in this case
3244   # is effectively a no-op (except that we bump up the chain_depth on
3245   # the join in question so we could tell it *is* the search_related)
3246   my $already_joined;
3247
3248   # we consider the last one thus reverse
3249   for my $j (reverse @requested_joins) {
3250     my ($last_j) = keys %{$j->[0]{-join_path}[-1]};
3251     if ($rel eq $last_j) {
3252       $j->[0]{-relation_chain_depth}++;
3253       $already_joined++;
3254       last;
3255     }
3256   }
3257
3258   unless ($already_joined) {
3259     push @$from, $source->_resolve_join(
3260       $rel,
3261       $attrs->{alias},
3262       $seen,
3263       $jpath,
3264     );
3265   }
3266
3267   $seen->{-relation_chain_depth}++;
3268
3269   return {%$attrs, from => $from, seen_join => $seen};
3270 }
3271
3272 sub _resolved_attrs {
3273   my $self = shift;
3274   return $self->{_attrs} if $self->{_attrs};
3275
3276   my $attrs  = { %{ $self->{attrs} || {} } };
3277   my $source = $self->result_source;
3278   my $alias  = $attrs->{alias};
3279
3280   # default selection list
3281   $attrs->{columns} = [ $source->columns ]
3282     unless List::Util::first { exists $attrs->{$_} } qw/columns cols select as/;
3283
3284   # merge selectors together
3285   for (qw/columns select as/) {
3286     $attrs->{$_} = $self->_merge_attr($attrs->{$_}, delete $attrs->{"+$_"})
3287       if $attrs->{$_} or $attrs->{"+$_"};
3288   }
3289
3290   # disassemble columns
3291   my (@sel, @as);
3292   if (my $cols = delete $attrs->{columns}) {
3293     for my $c (ref $cols eq 'ARRAY' ? @$cols : $cols) {
3294       if (ref $c eq 'HASH') {
3295         for my $as (sort keys %$c) {
3296           push @sel, $c->{$as};
3297           push @as, $as;
3298         }
3299       }
3300       else {
3301         push @sel, $c;
3302         push @as, $c;
3303       }
3304     }
3305   }
3306
3307   # when trying to weed off duplicates later do not go past this point -
3308   # everything added from here on is unbalanced "anyone's guess" stuff
3309   my $dedup_stop_idx = $#as;
3310
3311   push @as, @{ ref $attrs->{as} eq 'ARRAY' ? $attrs->{as} : [ $attrs->{as} ] }
3312     if $attrs->{as};
3313   push @sel, @{ ref $attrs->{select} eq 'ARRAY' ? $attrs->{select} : [ $attrs->{select} ] }
3314     if $attrs->{select};
3315
3316   # assume all unqualified selectors to apply to the current alias (legacy stuff)
3317   $_ = (ref $_ or $_ =~ /\./) ? $_ : "$alias.$_" for @sel;
3318
3319   # disqualify all $alias.col as-bits (inflate-map mandated)
3320   $_ = ($_ =~ /^\Q$alias.\E(.+)$/) ? $1 : $_ for @as;
3321
3322   # de-duplicate the result (remove *identical* select/as pairs)
3323   # and also die on duplicate {as} pointing to different {select}s
3324   # not using a c-style for as the condition is prone to shrinkage
3325   my $seen;
3326   my $i = 0;
3327   while ($i <= $dedup_stop_idx) {
3328     if ($seen->{"$sel[$i] \x00\x00 $as[$i]"}++) {
3329       splice @sel, $i, 1;
3330       splice @as, $i, 1;
3331       $dedup_stop_idx--;
3332     }
3333     elsif ($seen->{$as[$i]}++) {
3334       $self->throw_exception(
3335         "inflate_result() alias '$as[$i]' specified twice with different SQL-side {select}-ors"
3336       );
3337     }
3338     else {
3339       $i++;
3340     }
3341   }
3342
3343   $attrs->{select} = \@sel;
3344   $attrs->{as} = \@as;
3345
3346   $attrs->{from} ||= [{
3347     -rsrc   => $source,
3348     -alias  => $self->{attrs}{alias},
3349     $self->{attrs}{alias} => $source->from,
3350   }];
3351
3352   if ( $attrs->{join} || $attrs->{prefetch} ) {
3353
3354     $self->throw_exception ('join/prefetch can not be used with a custom {from}')
3355       if ref $attrs->{from} ne 'ARRAY';
3356
3357     my $join = (delete $attrs->{join}) || {};
3358
3359     if ( defined $attrs->{prefetch} ) {
3360       $join = $self->_merge_joinpref_attr( $join, $attrs->{prefetch} );
3361     }
3362
3363     $attrs->{from} =    # have to copy here to avoid corrupting the original
3364       [
3365         @{ $attrs->{from} },
3366         $source->_resolve_join(
3367           $join,
3368           $alias,
3369           { %{ $attrs->{seen_join} || {} } },
3370           ( $attrs->{seen_join} && keys %{$attrs->{seen_join}})
3371             ? $attrs->{from}[-1][0]{-join_path}
3372             : []
3373           ,
3374         )
3375       ];
3376   }
3377
3378   if ( defined $attrs->{order_by} ) {
3379     $attrs->{order_by} = (
3380       ref( $attrs->{order_by} ) eq 'ARRAY'
3381       ? [ @{ $attrs->{order_by} } ]
3382       : [ $attrs->{order_by} || () ]
3383     );
3384   }
3385
3386   if ($attrs->{group_by} and ref $attrs->{group_by} ne 'ARRAY') {
3387     $attrs->{group_by} = [ $attrs->{group_by} ];
3388   }
3389
3390   # generate the distinct induced group_by early, as prefetch will be carried via a
3391   # subquery (since a group_by is present)
3392   if (delete $attrs->{distinct}) {
3393     if ($attrs->{group_by}) {
3394       carp_unique ("Useless use of distinct on a grouped resultset ('distinct' is ignored when a 'group_by' is present)");
3395     }
3396     else {
3397       # distinct affects only the main selection part, not what prefetch may
3398       # add below.
3399       $attrs->{group_by} = $source->storage->_group_over_selection (
3400         $attrs->{from},
3401         $attrs->{select},
3402         $attrs->{order_by},
3403       );
3404     }
3405   }
3406
3407   # generate selections based on the prefetch helper
3408   my $prefetch;
3409   $prefetch = $self->_merge_joinpref_attr( {}, delete $attrs->{prefetch} )
3410     if defined $attrs->{prefetch};
3411
3412   if ($prefetch) {
3413
3414     $self->throw_exception("Unable to prefetch, resultset contains an unnamed selector $attrs->{_dark_selector}{string}")
3415       if $attrs->{_dark_selector};
3416
3417     $attrs->{collapse} = 1;
3418
3419     # this is a separate structure (we don't look in {from} directly)
3420     # as the resolver needs to shift things off the lists to work
3421     # properly (identical-prefetches on different branches)
3422     my $join_map = {};
3423     if (ref $attrs->{from} eq 'ARRAY') {
3424
3425       my $start_depth = $attrs->{seen_join}{-relation_chain_depth} || 0;
3426
3427       for my $j ( @{$attrs->{from}}[1 .. $#{$attrs->{from}} ] ) {
3428         next unless $j->[0]{-alias};
3429         next unless $j->[0]{-join_path};
3430         next if ($j->[0]{-relation_chain_depth} || 0) < $start_depth;
3431
3432         my @jpath = map { keys %$_ } @{$j->[0]{-join_path}};
3433
3434         my $p = $join_map;
3435         $p = $p->{$_} ||= {} for @jpath[ ($start_depth/2) .. $#jpath]; #only even depths are actual jpath boundaries
3436         push @{$p->{-join_aliases} }, $j->[0]{-alias};
3437       }
3438     }
3439
3440     my @prefetch = $source->_resolve_prefetch( $prefetch, $alias, $join_map );
3441
3442     # we need to somehow mark which columns came from prefetch
3443     if (@prefetch) {
3444       my $sel_end = $#{$attrs->{select}};
3445       $attrs->{_prefetch_selector_range} = [ $sel_end + 1, $sel_end + @prefetch ];
3446     }
3447
3448     push @{ $attrs->{select} }, (map { $_->[0] } @prefetch);
3449     push @{ $attrs->{as} }, (map { $_->[1] } @prefetch);
3450   }
3451
3452   if ( ! List::Util::first { $_ =~ /\./ } @{$attrs->{as}} ) {
3453     $attrs->{_single_object_inflation} = 1;
3454     $attrs->{collapse} = 0;
3455   }
3456
3457   # run through the resulting joinstructure (starting from our current slot)
3458   # and unset collapse if proven unnesessary
3459   #
3460   # also while we are at it find out if the current root source has
3461   # been premultiplied by previous related_source chaining
3462   #
3463   # this allows to predict whether a root object with all other relation
3464   # data set to NULL is in fact unique
3465   if ($attrs->{collapse}) {
3466
3467     if (ref $attrs->{from} eq 'ARRAY') {
3468
3469       if (@{$attrs->{from}} <= 1) {
3470         # no joins - no collapse
3471         $attrs->{collapse} = 0;
3472       }
3473       else {
3474         # find where our table-spec starts
3475         my @fromlist = @{$attrs->{from}};
3476         while (@fromlist) {
3477           my $t = shift @fromlist;
3478
3479           my $is_multi;
3480           # me vs join from-spec distinction - a ref means non-root
3481           if (ref $t eq 'ARRAY') {
3482             $t = $t->[0];
3483             $is_multi ||= ! $t->{-is_single};
3484           }
3485           last if ($t->{-alias} && $t->{-alias} eq $alias);
3486           $attrs->{_main_source_premultiplied} ||= $is_multi;
3487         }
3488
3489         # no non-singles remaining, nor any premultiplication - nothing to collapse
3490         if (
3491           ! $attrs->{_main_source_premultiplied}
3492             and
3493           ! List::Util::first { ! $_->[0]{-is_single} } @fromlist
3494         ) {
3495           $attrs->{collapse} = 0;
3496         }
3497       }
3498     }
3499
3500     else {
3501       # if we can not analyze the from - err on the side of safety
3502       $attrs->{_main_source_premultiplied} = 1;
3503     }
3504   }
3505
3506   if (! $attrs->{order_by} and $attrs->{collapse}) {
3507     # default order for collapsing unless the user asked for something
3508     $attrs->{order_by} = [ map { "$alias.$_" } $source->primary_columns ];
3509     $attrs->{_ordered_for_collapse} = 1;
3510     $attrs->{_order_is_artificial} = 1;
3511   }
3512
3513   # if both page and offset are specified, produce a combined offset
3514   # even though it doesn't make much sense, this is what pre 081xx has
3515   # been doing
3516   if (my $page = delete $attrs->{page}) {
3517     $attrs->{offset} =
3518       ($attrs->{rows} * ($page - 1))
3519             +
3520       ($attrs->{offset} || 0)
3521     ;
3522   }
3523
3524   return $self->{_attrs} = $attrs;
3525 }
3526
3527 sub _rollout_attr {
3528   my ($self, $attr) = @_;
3529
3530   if (ref $attr eq 'HASH') {
3531     return $self->_rollout_hash($attr);
3532   } elsif (ref $attr eq 'ARRAY') {
3533     return $self->_rollout_array($attr);
3534   } else {
3535     return [$attr];
3536   }
3537 }
3538
3539 sub _rollout_array {
3540   my ($self, $attr) = @_;
3541
3542   my @rolled_array;
3543   foreach my $element (@{$attr}) {
3544     if (ref $element eq 'HASH') {
3545       push( @rolled_array, @{ $self->_rollout_hash( $element ) } );
3546     } elsif (ref $element eq 'ARRAY') {
3547       #  XXX - should probably recurse here
3548       push( @rolled_array, @{$self->_rollout_array($element)} );
3549     } else {
3550       push( @rolled_array, $element );
3551     }
3552   }
3553   return \@rolled_array;
3554 }
3555
3556 sub _rollout_hash {
3557   my ($self, $attr) = @_;
3558
3559   my @rolled_array;
3560   foreach my $key (keys %{$attr}) {
3561     push( @rolled_array, { $key => $attr->{$key} } );
3562   }
3563   return \@rolled_array;
3564 }
3565
3566 sub _calculate_score {
3567   my ($self, $a, $b) = @_;
3568
3569   if (defined $a xor defined $b) {
3570     return 0;
3571   }
3572   elsif (not defined $a) {
3573     return 1;
3574   }
3575
3576   if (ref $b eq 'HASH') {
3577     my ($b_key) = keys %{$b};
3578     if (ref $a eq 'HASH') {
3579       my ($a_key) = keys %{$a};
3580       if ($a_key eq $b_key) {
3581         return (1 + $self->_calculate_score( $a->{$a_key}, $b->{$b_key} ));
3582       } else {
3583         return 0;
3584       }
3585     } else {
3586       return ($a eq $b_key) ? 1 : 0;
3587     }
3588   } else {
3589     if (ref $a eq 'HASH') {
3590       my ($a_key) = keys %{$a};
3591       return ($b eq $a_key) ? 1 : 0;
3592     } else {
3593       return ($b eq $a) ? 1 : 0;
3594     }
3595   }
3596 }
3597
3598 sub _merge_joinpref_attr {
3599   my ($self, $orig, $import) = @_;
3600
3601   return $import unless defined($orig);
3602   return $orig unless defined($import);
3603
3604   $orig = $self->_rollout_attr($orig);
3605   $import = $self->_rollout_attr($import);
3606
3607   my $seen_keys;
3608   foreach my $import_element ( @{$import} ) {
3609     # find best candidate from $orig to merge $b_element into
3610     my $best_candidate = { position => undef, score => 0 }; my $position = 0;
3611     foreach my $orig_element ( @{$orig} ) {
3612       my $score = $self->_calculate_score( $orig_element, $import_element );
3613       if ($score > $best_candidate->{score}) {
3614         $best_candidate->{position} = $position;
3615         $best_candidate->{score} = $score;
3616       }
3617       $position++;
3618     }
3619     my ($import_key) = ( ref $import_element eq 'HASH' ) ? keys %{$import_element} : ($import_element);
3620     $import_key = '' if not defined $import_key;
3621
3622     if ($best_candidate->{score} == 0 || exists $seen_keys->{$import_key}) {
3623       push( @{$orig}, $import_element );
3624     } else {
3625       my $orig_best = $orig->[$best_candidate->{position}];
3626       # merge orig_best and b_element together and replace original with merged
3627       if (ref $orig_best ne 'HASH') {
3628         $orig->[$best_candidate->{position}] = $import_element;
3629       } elsif (ref $import_element eq 'HASH') {
3630         my ($key) = keys %{$orig_best};
3631         $orig->[$best_candidate->{position}] = { $key => $self->_merge_joinpref_attr($orig_best->{$key}, $import_element->{$key}) };
3632       }
3633     }
3634     $seen_keys->{$import_key} = 1; # don't merge the same key twice
3635   }
3636
3637   return @$orig ? $orig : ();
3638 }
3639
3640 {
3641   my $hm;
3642
3643   sub _merge_attr {
3644     $hm ||= do {
3645       require Hash::Merge;
3646       my $hm = Hash::Merge->new;
3647
3648       $hm->specify_behavior({
3649         SCALAR => {
3650           SCALAR => sub {
3651             my ($defl, $defr) = map { defined $_ } (@_[0,1]);
3652
3653             if ($defl xor $defr) {
3654               return [ $defl ? $_[0] : $_[1] ];
3655             }
3656             elsif (! $defl) {
3657               return [];
3658             }
3659             elsif (__HM_DEDUP and $_[0] eq $_[1]) {
3660               return [ $_[0] ];
3661             }
3662             else {
3663               return [$_[0], $_[1]];
3664             }
3665           },
3666           ARRAY => sub {
3667             return $_[1] if !defined $_[0];
3668             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3669             return [$_[0], @{$_[1]}]
3670           },
3671           HASH  => sub {
3672             return [] if !defined $_[0] and !keys %{$_[1]};
3673             return [ $_[1] ] if !defined $_[0];
3674             return [ $_[0] ] if !keys %{$_[1]};
3675             return [$_[0], $_[1]]
3676           },
3677         },
3678         ARRAY => {
3679           SCALAR => sub {
3680             return $_[0] if !defined $_[1];
3681             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3682             return [@{$_[0]}, $_[1]]
3683           },
3684           ARRAY => sub {
3685             my @ret = @{$_[0]} or return $_[1];
3686             return [ @ret, @{$_[1]} ] unless __HM_DEDUP;
3687             my %idx = map { $_ => 1 } @ret;
3688             push @ret, grep { ! defined $idx{$_} } (@{$_[1]});
3689             \@ret;
3690           },
3691           HASH => sub {
3692             return [ $_[1] ] if ! @{$_[0]};
3693             return $_[0] if !keys %{$_[1]};
3694             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3695             return [ @{$_[0]}, $_[1] ];
3696           },
3697         },
3698         HASH => {
3699           SCALAR => sub {
3700             return [] if !keys %{$_[0]} and !defined $_[1];
3701             return [ $_[0] ] if !defined $_[1];
3702             return [ $_[1] ] if !keys %{$_[0]};
3703             return [$_[0], $_[1]]
3704           },
3705           ARRAY => sub {
3706             return [] if !keys %{$_[0]} and !@{$_[1]};
3707             return [ $_[0] ] if !@{$_[1]};
3708             return $_[1] if !keys %{$_[0]};
3709             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3710             return [ $_[0], @{$_[1]} ];
3711           },
3712           HASH => sub {
3713             return [] if !keys %{$_[0]} and !keys %{$_[1]};
3714             return [ $_[0] ] if !keys %{$_[1]};
3715             return [ $_[1] ] if !keys %{$_[0]};
3716             return [ $_[0] ] if $_[0] eq $_[1];
3717             return [ $_[0], $_[1] ];
3718           },
3719         }
3720       } => 'DBIC_RS_ATTR_MERGER');
3721       $hm;
3722     };
3723
3724     return $hm->merge ($_[1], $_[2]);
3725   }
3726 }
3727
3728 sub STORABLE_freeze {
3729   my ($self, $cloning) = @_;
3730   my $to_serialize = { %$self };
3731
3732   # A cursor in progress can't be serialized (and would make little sense anyway)
3733   # the parser can be regenerated (and can't be serialized)
3734   delete @{$to_serialize}{qw/cursor _row_parser/};
3735
3736   # nor is it sensical to store a not-yet-fired-count pager
3737   if ($to_serialize->{pager} and ref $to_serialize->{pager}{total_entries} eq 'CODE') {
3738     delete $to_serialize->{pager};
3739   }
3740
3741   Storable::nfreeze($to_serialize);
3742 }
3743
3744 # need this hook for symmetry
3745 sub STORABLE_thaw {
3746   my ($self, $cloning, $serialized) = @_;
3747
3748   %$self = %{ Storable::thaw($serialized) };
3749
3750   $self;
3751 }
3752
3753
3754 =head2 throw_exception
3755
3756 See L<DBIx::Class::Schema/throw_exception> for details.
3757
3758 =cut
3759
3760 sub throw_exception {
3761   my $self=shift;
3762
3763   if (ref $self and my $rsrc = $self->result_source) {
3764     $rsrc->throw_exception(@_)
3765   }
3766   else {
3767     DBIx::Class::Exception->throw(@_);
3768   }
3769 }
3770
3771 # XXX: FIXME: Attributes docs need clearing up
3772
3773 =head1 ATTRIBUTES
3774
3775 Attributes are used to refine a ResultSet in various ways when
3776 searching for data. They can be passed to any method which takes an
3777 C<\%attrs> argument. See L</search>, L</search_rs>, L</find>,
3778 L</count>.
3779
3780 Default attributes can be set on the result class using
3781 L<DBIx::Class::ResultSource/resultset_attributes>.  (Please read
3782 the CAVEATS on that feature before using it!)
3783
3784 These are in no particular order:
3785
3786 =head2 order_by
3787
3788 =over 4
3789
3790 =item Value: ( $order_by | \@order_by | \%order_by )
3791
3792 =back
3793
3794 Which column(s) to order the results by.
3795
3796 [The full list of suitable values is documented in
3797 L<SQL::Abstract/"ORDER BY CLAUSES">; the following is a summary of
3798 common options.]
3799
3800 If a single column name, or an arrayref of names is supplied, the
3801 argument is passed through directly to SQL. The hashref syntax allows
3802 for connection-agnostic specification of ordering direction:
3803
3804  For descending order:
3805
3806   order_by => { -desc => [qw/col1 col2 col3/] }
3807
3808  For explicit ascending order:
3809
3810   order_by => { -asc => 'col' }
3811
3812 The old scalarref syntax (i.e. order_by => \'year DESC') is still
3813 supported, although you are strongly encouraged to use the hashref
3814 syntax as outlined above.
3815
3816 =head2 columns
3817
3818 =over 4
3819
3820 =item Value: \@columns
3821
3822 =back
3823
3824 Shortcut to request a particular set of columns to be retrieved. Each
3825 column spec may be a string (a table column name), or a hash (in which
3826 case the key is the C<as> value, and the value is used as the C<select>
3827 expression). Adds C<me.> onto the start of any column without a C<.> in
3828 it and sets C<select> from that, then auto-populates C<as> from
3829 C<select> as normal. (You may also use the C<cols> attribute, as in
3830 earlier versions of DBIC.)
3831
3832 Essentially C<columns> does the same as L</select> and L</as>.
3833
3834     columns => [ 'foo', { bar => 'baz' } ]
3835
3836 is the same as
3837
3838     select => [qw/foo baz/],
3839     as => [qw/foo bar/]
3840
3841 =head2 +columns
3842
3843 =over 4
3844
3845 =item Value: \@columns
3846
3847 =back
3848
3849 Indicates additional columns to be selected from storage. Works the same
3850 as L</columns> but adds columns to the selection. (You may also use the
3851 C<include_columns> attribute, as in earlier versions of DBIC). For
3852 example:-
3853
3854   $schema->resultset('CD')->search(undef, {
3855     '+columns' => ['artist.name'],
3856     join => ['artist']
3857   });
3858
3859 would return all CDs and include a 'name' column to the information
3860 passed to object inflation. Note that the 'artist' is the name of the
3861 column (or relationship) accessor, and 'name' is the name of the column
3862 accessor in the related table.
3863
3864 B<NOTE:> You need to explicitly quote '+columns' when defining the attribute.
3865 Not doing so causes Perl to incorrectly interpret +columns as a bareword with a
3866 unary plus operator before it.
3867
3868 =head2 include_columns
3869
3870 =over 4
3871
3872 =item Value: \@columns
3873
3874 =back
3875
3876 Deprecated.  Acts as a synonym for L</+columns> for backward compatibility.
3877
3878 =head2 select
3879
3880 =over 4
3881
3882 =item Value: \@select_columns
3883
3884 =back
3885
3886 Indicates which columns should be selected from the storage. You can use
3887 column names, or in the case of RDBMS back ends, function or stored procedure
3888 names:
3889
3890   $rs = $schema->resultset('Employee')->search(undef, {
3891     select => [
3892       'name',
3893       { count => 'employeeid' },
3894       { max => { length => 'name' }, -as => 'longest_name' }
3895     ]
3896   });
3897
3898   # Equivalent SQL
3899   SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee
3900
3901 B<NOTE:> You will almost always need a corresponding L</as> attribute when you
3902 use L</select>, to instruct DBIx::Class how to store the result of the column.
3903 Also note that the L</as> attribute has nothing to do with the SQL-side 'AS'
3904 identifier aliasing. You can however alias a function, so you can use it in
3905 e.g. an C<ORDER BY> clause. This is done via the C<-as> B<select function
3906 attribute> supplied as shown in the example above.
3907
3908 B<NOTE:> You need to explicitly quote '+select'/'+as' when defining the attributes.
3909 Not doing so causes Perl to incorrectly interpret them as a bareword with a
3910 unary plus operator before it.
3911
3912 =head2 +select
3913
3914 =over 4
3915
3916 Indicates additional columns to be selected from storage.  Works the same as
3917 L</select> but adds columns to the default selection, instead of specifying
3918 an explicit list.
3919
3920 =back
3921
3922 =head2 +as
3923
3924 =over 4
3925
3926 Indicates additional column names for those added via L</+select>. See L</as>.
3927
3928 =back
3929
3930 =head2 as
3931
3932 =over 4
3933
3934 =item Value: \@inflation_names
3935
3936 =back
3937
3938 Indicates column names for object inflation. That is L</as> indicates the
3939 slot name in which the column value will be stored within the
3940 L<Row|DBIx::Class::Row> object. The value will then be accessible via this
3941 identifier by the C<get_column> method (or via the object accessor B<if one
3942 with the same name already exists>) as shown below. The L</as> attribute has
3943 B<nothing to do> with the SQL-side C<AS>. See L</select> for details.
3944
3945   $rs = $schema->resultset('Employee')->search(undef, {
3946     select => [
3947       'name',
3948       { count => 'employeeid' },
3949       { max => { length => 'name' }, -as => 'longest_name' }
3950     ],
3951     as => [qw/
3952       name
3953       employee_count
3954       max_name_length
3955     /],
3956   });
3957
3958 If the object against which the search is performed already has an accessor
3959 matching a column name specified in C<as>, the value can be retrieved using
3960 the accessor as normal:
3961
3962   my $name = $employee->name();
3963
3964 If on the other hand an accessor does not exist in the object, you need to
3965 use C<get_column> instead:
3966
3967   my $employee_count = $employee->get_column('employee_count');
3968
3969 You can create your own accessors if required - see
3970 L<DBIx::Class::Manual::Cookbook> for details.
3971
3972 =head2 join
3973
3974 =over 4
3975
3976 =item Value: ($rel_name | \@rel_names | \%rel_names)
3977
3978 =back
3979
3980 Contains a list of relationships that should be joined for this query.  For
3981 example:
3982
3983   # Get CDs by Nine Inch Nails
3984   my $rs = $schema->resultset('CD')->search(
3985     { 'artist.name' => 'Nine Inch Nails' },
3986     { join => 'artist' }
3987   );
3988
3989 Can also contain a hash reference to refer to the other relation's relations.
3990 For example:
3991
3992   package MyApp::Schema::Track;
3993   use base qw/DBIx::Class/;
3994   __PACKAGE__->table('track');
3995   __PACKAGE__->add_columns(qw/trackid cd position title/);
3996   __PACKAGE__->set_primary_key('trackid');
3997   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
3998   1;
3999
4000   # In your application
4001   my $rs = $schema->resultset('Artist')->search(
4002     { 'track.title' => 'Teardrop' },
4003     {
4004       join     => { cd => 'track' },
4005       order_by => 'artist.name',
4006     }
4007   );
4008
4009 You need to use the relationship (not the table) name in  conditions,
4010 because they are aliased as such. The current table is aliased as "me", so
4011 you need to use me.column_name in order to avoid ambiguity. For example:
4012
4013   # Get CDs from 1984 with a 'Foo' track
4014   my $rs = $schema->resultset('CD')->search(
4015     {
4016       'me.year' => 1984,
4017       'tracks.name' => 'Foo'
4018     },
4019     { join => 'tracks' }
4020   );
4021
4022 If the same join is supplied twice, it will be aliased to <rel>_2 (and
4023 similarly for a third time). For e.g.
4024
4025   my $rs = $schema->resultset('Artist')->search({
4026     'cds.title'   => 'Down to Earth',
4027     'cds_2.title' => 'Popular',
4028   }, {
4029     join => [ qw/cds cds/ ],
4030   });
4031
4032 will return a set of all artists that have both a cd with title 'Down
4033 to Earth' and a cd with title 'Popular'.
4034
4035 If you want to fetch related objects from other tables as well, see C<prefetch>
4036 below.
4037
4038  NOTE: An internal join-chain pruner will discard certain joins while
4039  constructing the actual SQL query, as long as the joins in question do not
4040  affect the retrieved result. This for example includes 1:1 left joins
4041  that are not part of the restriction specification (WHERE/HAVING) nor are
4042  a part of the query selection.
4043
4044 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
4045
4046 =head2 prefetch
4047
4048 =over 4
4049
4050 =item Value: ($rel_name | \@rel_names | \%rel_names)
4051
4052 =back
4053
4054 Contains one or more relationships that should be fetched along with
4055 the main query (when they are accessed afterwards the data will
4056 already be available, without extra queries to the database).  This is
4057 useful for when you know you will need the related objects, because it
4058 saves at least one query:
4059
4060   my $rs = $schema->resultset('Tag')->search(
4061     undef,
4062     {
4063       prefetch => {
4064         cd => 'artist'
4065       }
4066     }
4067   );
4068
4069 The initial search results in SQL like the following:
4070
4071   SELECT tag.*, cd.*, artist.* FROM tag
4072   JOIN cd ON tag.cd = cd.cdid
4073   JOIN artist ON cd.artist = artist.artistid
4074
4075 L<DBIx::Class> has no need to go back to the database when we access the
4076 C<cd> or C<artist> relationships, which saves us two SQL statements in this
4077 case.
4078
4079 Simple prefetches will be joined automatically, so there is no need
4080 for a C<join> attribute in the above search.
4081
4082 L</prefetch> can be used with the any of the relationship types and
4083 multiple prefetches can be specified together. Below is a more complex
4084 example that prefetches a CD's artist, its liner notes (if present),
4085 the cover image, the tracks on that cd, and the guests on those
4086 tracks.
4087
4088  # Assuming:
4089  My::Schema::CD->belongs_to( artist      => 'My::Schema::Artist'     );
4090  My::Schema::CD->might_have( liner_note  => 'My::Schema::LinerNotes' );
4091  My::Schema::CD->has_one(    cover_image => 'My::Schema::Artwork'    );
4092  My::Schema::CD->has_many(   tracks      => 'My::Schema::Track'      );
4093
4094  My::Schema::Artist->belongs_to( record_label => 'My::Schema::RecordLabel' );
4095
4096  My::Schema::Track->has_many( guests => 'My::Schema::Guest' );
4097
4098
4099  my $rs = $schema->resultset('CD')->search(
4100    undef,
4101    {
4102      prefetch => [
4103        { artist => 'record_label'},  # belongs_to => belongs_to
4104        'liner_note',                 # might_have
4105        'cover_image',                # has_one
4106        { tracks => 'guests' },       # has_many => has_many
4107      ]
4108    }
4109  );
4110
4111 This will produce SQL like the following:
4112
4113  SELECT cd.*, artist.*, record_label.*, liner_note.*, cover_image.*,
4114         tracks.*, guests.*
4115    FROM cd me
4116    JOIN artist artist
4117      ON artist.artistid = me.artistid
4118    JOIN record_label record_label
4119      ON record_label.labelid = artist.labelid
4120    LEFT JOIN track tracks
4121      ON tracks.cdid = me.cdid
4122    LEFT JOIN guest guests
4123      ON guests.trackid = track.trackid
4124    LEFT JOIN liner_notes liner_note
4125      ON liner_note.cdid = me.cdid
4126    JOIN cd_artwork cover_image
4127      ON cover_image.cdid = me.cdid
4128  ORDER BY tracks.cd
4129
4130 Now the C<artist>, C<record_label>, C<liner_note>, C<cover_image>,
4131 C<tracks>, and C<guests> of the CD will all be available through the
4132 relationship accessors without the need for additional queries to the
4133 database.
4134
4135 However, there is one caveat to be observed: it can be dangerous to
4136 prefetch more than one L<has_many|DBIx::Class::Relationship/has_many>
4137 relationship on a given level. e.g.:
4138
4139  my $rs = $schema->resultset('CD')->search(
4140    undef,
4141    {
4142      prefetch => [
4143        'tracks',                         # has_many
4144        { cd_to_producer => 'producer' }, # has_many => belongs_to (i.e. m2m)
4145      ]
4146    }
4147  );
4148
4149 The collapser currently can't identify duplicate tuples for multiple
4150 L<has_many|DBIx::Class::Relationship/has_many> relationships and as a
4151 result the second L<has_many|DBIx::Class::Relationship/has_many>
4152 relation could contain redundant objects.
4153
4154 =head3 Using L</prefetch> with L</join>
4155
4156 L</prefetch> implies a L</join> with the equivalent argument, and is
4157 properly merged with any existing L</join> specification. So the
4158 following:
4159
4160   my $rs = $schema->resultset('CD')->search(
4161    {'record_label.name' => 'Music Product Ltd.'},
4162    {
4163      join     => {artist => 'record_label'},
4164      prefetch => 'artist',
4165    }
4166  );
4167
4168 ... will work, searching on the record label's name, but only
4169 prefetching the C<artist>.
4170
4171 =head3 Using L</prefetch> with L</select> / L</+select> / L</as> / L</+as>
4172
4173 L</prefetch> implies a L</+select>/L</+as> with the fields of the
4174 prefetched relations.  So given:
4175
4176   my $rs = $schema->resultset('CD')->search(
4177    undef,
4178    {
4179      select   => ['cd.title'],
4180      as       => ['cd_title'],
4181      prefetch => 'artist',
4182    }
4183  );
4184
4185 The L</select> becomes: C<'cd.title', 'artist.*'> and the L</as>
4186 becomes: C<'cd_title', 'artist.*'>.
4187
4188 =head3 CAVEATS
4189
4190 Prefetch does a lot of deep magic. As such, it may not behave exactly
4191 as you might expect.
4192
4193 =over 4
4194
4195 =item *
4196
4197 Prefetch uses the L</cache> to populate the prefetched relationships. This
4198 may or may not be what you want.
4199
4200 =item *
4201
4202 If you specify a condition on a prefetched relationship, ONLY those
4203 rows that match the prefetched condition will be fetched into that relationship.
4204 This means that adding prefetch to a search() B<may alter> what is returned by
4205 traversing a relationship. So, if you have C<< Artist->has_many(CDs) >> and you do
4206
4207   my $artist_rs = $schema->resultset('Artist')->search({
4208       'cds.year' => 2008,
4209   }, {
4210       join => 'cds',
4211   });
4212
4213   my $count = $artist_rs->first->cds->count;
4214
4215   my $artist_rs_prefetch = $artist_rs->search( {}, { prefetch => 'cds' } );
4216
4217   my $prefetch_count = $artist_rs_prefetch->first->cds->count;
4218
4219   cmp_ok( $count, '==', $prefetch_count, "Counts should be the same" );
4220
4221 that cmp_ok() may or may not pass depending on the datasets involved. This
4222 behavior may or may not survive the 0.09 transition.
4223
4224 =back
4225
4226 =head2 alias
4227
4228 =over 4
4229
4230 =item Value: $source_alias
4231
4232 =back
4233
4234 Sets the source alias for the query.  Normally, this defaults to C<me>, but
4235 nested search queries (sub-SELECTs) might need specific aliases set to
4236 reference inner queries.  For example:
4237
4238    my $q = $rs
4239       ->related_resultset('CDs')
4240       ->related_resultset('Tracks')
4241       ->search({
4242          'track.id' => { -ident => 'none_search.id' },
4243       })
4244       ->as_query;
4245
4246    my $ids = $self->search({
4247       -not_exists => $q,
4248    }, {
4249       alias    => 'none_search',
4250       group_by => 'none_search.id',
4251    })->get_column('id')->as_query;
4252
4253    $self->search({ id => { -in => $ids } })
4254
4255 This attribute is directly tied to L</current_source_alias>.
4256
4257 =head2 page
4258
4259 =over 4
4260
4261 =item Value: $page
4262
4263 =back
4264
4265 Makes the resultset paged and specifies the page to retrieve. Effectively
4266 identical to creating a non-pages resultset and then calling ->page($page)
4267 on it.
4268
4269 If L</rows> attribute is not specified it defaults to 10 rows per page.
4270
4271 When you have a paged resultset, L</count> will only return the number
4272 of rows in the page. To get the total, use the L</pager> and call
4273 C<total_entries> on it.
4274
4275 =head2 rows
4276
4277 =over 4
4278
4279 =item Value: $rows
4280
4281 =back
4282
4283 Specifies the maximum number of rows for direct retrieval or the number of
4284 rows per page if the page attribute or method is used.
4285
4286 =head2 offset
4287
4288 =over 4
4289
4290 =item Value: $offset
4291
4292 =back
4293
4294 Specifies the (zero-based) row number for the  first row to be returned, or the
4295 of the first row of the first page if paging is used.
4296
4297 =head2 software_limit
4298
4299 =over 4
4300
4301 =item Value: (0 | 1)
4302
4303 =back
4304
4305 When combined with L</rows> and/or L</offset> the generated SQL will not
4306 include any limit dialect stanzas. Instead the entire result will be selected
4307 as if no limits were specified, and DBIC will perform the limit locally, by
4308 artificially advancing and finishing the resulting L</cursor>.
4309
4310 This is the recommended way of performing resultset limiting when no sane RDBMS
4311 implementation is available (e.g.
4312 L<Sybase ASE|DBIx::Class::Storage::DBI::Sybase::ASE> using the
4313 L<Generic Sub Query|DBIx::Class::SQLMaker::LimitDialects/GenericSubQ> hack)
4314
4315 =head2 group_by
4316
4317 =over 4
4318
4319 =item Value: \@columns
4320
4321 =back
4322
4323 A arrayref of columns to group by. Can include columns of joined tables.
4324
4325   group_by => [qw/ column1 column2 ... /]
4326
4327 =head2 having
4328
4329 =over 4
4330
4331 =item Value: $condition
4332
4333 =back
4334
4335 HAVING is a select statement attribute that is applied between GROUP BY and
4336 ORDER BY. It is applied to the after the grouping calculations have been
4337 done.
4338
4339   having => { 'count_employee' => { '>=', 100 } }
4340
4341 or with an in-place function in which case literal SQL is required:
4342
4343   having => \[ 'count(employee) >= ?', [ count => 100 ] ]
4344
4345 =head2 distinct
4346
4347 =over 4
4348
4349 =item Value: (0 | 1)
4350
4351 =back
4352
4353 Set to 1 to group by all columns. If the resultset already has a group_by
4354 attribute, this setting is ignored and an appropriate warning is issued.
4355
4356 =head2 where
4357
4358 =over 4
4359
4360 Adds to the WHERE clause.
4361
4362   # only return rows WHERE deleted IS NULL for all searches
4363   __PACKAGE__->resultset_attributes({ where => { deleted => undef } });
4364
4365 Can be overridden by passing C<< { where => undef } >> as an attribute
4366 to a resultset.
4367
4368 For more complicated where clauses see L<SQL::Abstract/WHERE CLAUSES>.
4369
4370 =back
4371
4372 =head2 cache
4373
4374 Set to 1 to cache search results. This prevents extra SQL queries if you
4375 revisit rows in your ResultSet:
4376
4377   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
4378
4379   while( my $artist = $resultset->next ) {
4380     ... do stuff ...
4381   }
4382
4383   $rs->first; # without cache, this would issue a query
4384
4385 By default, searches are not cached.
4386
4387 For more examples of using these attributes, see
4388 L<DBIx::Class::Manual::Cookbook>.
4389
4390 =head2 for
4391
4392 =over 4
4393
4394 =item Value: ( 'update' | 'shared' | \$scalar )
4395
4396 =back
4397
4398 Set to 'update' for a SELECT ... FOR UPDATE or 'shared' for a SELECT
4399 ... FOR SHARED. If \$scalar is passed, this is taken directly and embedded in the
4400 query.
4401
4402 =head1 DBIC BIND VALUES
4403
4404 Because DBIC may need more information to bind values than just the column name
4405 and value itself, it uses a special format for both passing and receiving bind
4406 values.  Each bind value should be composed of an arrayref of
4407 C<< [ \%args => $val ] >>.  The format of C<< \%args >> is currently:
4408
4409 =over 4
4410
4411 =item dbd_attrs
4412
4413 If present (in any form), this is what is being passed directly to bind_param.
4414 Note that different DBD's expect different bind args.  (e.g. DBD::SQLite takes
4415 a single numerical type, while DBD::Pg takes a hashref if bind options.)
4416
4417 If this is specified, all other bind options described below are ignored.
4418
4419 =item sqlt_datatype
4420
4421 If present, this is used to infer the actual bind attribute by passing to
4422 C<< $resolved_storage->bind_attribute_by_data_type() >>.  Defaults to the
4423 "data_type" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>.
4424
4425 Note that the data type is somewhat freeform (hence the sqlt_ prefix);
4426 currently drivers are expected to "Do the Right Thing" when given a common
4427 datatype name.  (Not ideal, but that's what we got at this point.)
4428
4429 =item sqlt_size
4430
4431 Currently used to correctly allocate buffers for bind_param_inout().
4432 Defaults to "size" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>,
4433 or to a sensible value based on the "data_type".
4434
4435 =item dbic_colname
4436
4437 Used to fill in missing sqlt_datatype and sqlt_size attributes (if they are
4438 explicitly specified they are never overriden).  Also used by some weird DBDs,
4439 where the column name should be available at bind_param time (e.g. Oracle).
4440
4441 =back
4442
4443 For backwards compatibility and convenience, the following shortcuts are
4444 supported:
4445
4446   [ $name => $val ] === [ { dbic_colname => $name }, $val ]
4447   [ \$dt  => $val ] === [ { sqlt_datatype => $dt }, $val ]
4448   [ undef,   $val ] === [ {}, $val ]
4449
4450 =head1 AUTHOR AND CONTRIBUTORS
4451
4452 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
4453
4454 =head1 LICENSE
4455
4456 You may distribute this code under the same terms as Perl itself.
4457
4458 =cut
4459
4460 1;