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