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_select_dq } };
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 sub _as_select_dq {
2688   my $self = shift;
2689   my $attrs = { %{ $self->_resolved_attrs } };
2690   my $storage = $self->result_source->storage;
2691   my (undef, $ident, @args) = $storage->_select_args(
2692     $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
2693   );
2694   $ident = $ident->from if blessed($ident);
2695   $storage->sql_maker->converter->_select_to_dq(
2696     $ident, @args
2697   );
2698 }
2699
2700 =head2 find_or_new
2701
2702 =over 4
2703
2704 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2705
2706 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2707
2708 =back
2709
2710   my $artist = $schema->resultset('Artist')->find_or_new(
2711     { artist => 'fred' }, { key => 'artists' });
2712
2713   $cd->cd_to_producer->find_or_new({ producer => $producer },
2714                                    { key => 'primary' });
2715
2716 Find an existing record from this resultset using L</find>. if none exists,
2717 instantiate a new result object and return it. The object will not be saved
2718 into your storage until you call L<DBIx::Class::Row/insert> on it.
2719
2720 You most likely want this method when looking for existing rows using a unique
2721 constraint that is not the primary key, or looking for related rows.
2722
2723 If you want objects to be saved immediately, use L</find_or_create> instead.
2724
2725 B<Note>: Make sure to read the documentation of L</find> and understand the
2726 significance of the C<key> attribute, as its lack may skew your search, and
2727 subsequently result in spurious new objects.
2728
2729 B<Note>: Take care when using C<find_or_new> with a table having
2730 columns with default values that you intend to be automatically
2731 supplied by the database (e.g. an auto_increment primary key column).
2732 In normal usage, the value of such columns should NOT be included at
2733 all in the call to C<find_or_new>, even when set to C<undef>.
2734
2735 =cut
2736
2737 sub find_or_new {
2738   my $self     = shift;
2739   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2740   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2741   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2742     return $row;
2743   }
2744   return $self->new_result($hash);
2745 }
2746
2747 =head2 create
2748
2749 =over 4
2750
2751 =item Arguments: \%col_data
2752
2753 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2754
2755 =back
2756
2757 Attempt to create a single new row or a row with multiple related rows
2758 in the table represented by the resultset (and related tables). This
2759 will not check for duplicate rows before inserting, use
2760 L</find_or_create> to do that.
2761
2762 To create one row for this resultset, pass a hashref of key/value
2763 pairs representing the columns of the table and the values you wish to
2764 store. If the appropriate relationships are set up, foreign key fields
2765 can also be passed an object representing the foreign row, and the
2766 value will be set to its primary key.
2767
2768 To create related objects, pass a hashref of related-object column values
2769 B<keyed on the relationship name>. If the relationship is of type C<multi>
2770 (L<DBIx::Class::Relationship/has_many>) - pass an arrayref of hashrefs.
2771 The process will correctly identify columns holding foreign keys, and will
2772 transparently populate them from the keys of the corresponding relation.
2773 This can be applied recursively, and will work correctly for a structure
2774 with an arbitrary depth and width, as long as the relationships actually
2775 exists and the correct column data has been supplied.
2776
2777 Instead of hashrefs of plain related data (key/value pairs), you may
2778 also pass new or inserted objects. New objects (not inserted yet, see
2779 L</new_result>), will be inserted into their appropriate tables.
2780
2781 Effectively a shortcut for C<< ->new_result(\%col_data)->insert >>.
2782
2783 Example of creating a new row.
2784
2785   $person_rs->create({
2786     name=>"Some Person",
2787     email=>"somebody@someplace.com"
2788   });
2789
2790 Example of creating a new row and also creating rows in a related C<has_many>
2791 or C<has_one> resultset.  Note Arrayref.
2792
2793   $artist_rs->create(
2794      { artistid => 4, name => 'Manufactured Crap', cds => [
2795         { title => 'My First CD', year => 2006 },
2796         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
2797       ],
2798      },
2799   );
2800
2801 Example of creating a new row and also creating a row in a related
2802 C<belongs_to> resultset. Note Hashref.
2803
2804   $cd_rs->create({
2805     title=>"Music for Silly Walks",
2806     year=>2000,
2807     artist => {
2808       name=>"Silly Musician",
2809     }
2810   });
2811
2812 =over
2813
2814 =item WARNING
2815
2816 When subclassing ResultSet never attempt to override this method. Since
2817 it is a simple shortcut for C<< $self->new_result($attrs)->insert >>, a
2818 lot of the internals simply never call it, so your override will be
2819 bypassed more often than not. Override either L<DBIx::Class::Row/new>
2820 or L<DBIx::Class::Row/insert> depending on how early in the
2821 L</create> process you need to intervene. See also warning pertaining to
2822 L</new>.
2823
2824 =back
2825
2826 =cut
2827
2828 sub create {
2829   my ($self, $col_data) = @_;
2830   $self->throw_exception( "create needs a hashref" )
2831     unless ref $col_data eq 'HASH';
2832   return $self->new_result($col_data)->insert;
2833 }
2834
2835 =head2 find_or_create
2836
2837 =over 4
2838
2839 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2840
2841 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2842
2843 =back
2844
2845   $cd->cd_to_producer->find_or_create({ producer => $producer },
2846                                       { key => 'primary' });
2847
2848 Tries to find a record based on its primary key or unique constraints; if none
2849 is found, creates one and returns that instead.
2850
2851   my $cd = $schema->resultset('CD')->find_or_create({
2852     cdid   => 5,
2853     artist => 'Massive Attack',
2854     title  => 'Mezzanine',
2855     year   => 2005,
2856   });
2857
2858 Also takes an optional C<key> attribute, to search by a specific key or unique
2859 constraint. For example:
2860
2861   my $cd = $schema->resultset('CD')->find_or_create(
2862     {
2863       artist => 'Massive Attack',
2864       title  => 'Mezzanine',
2865     },
2866     { key => 'cd_artist_title' }
2867   );
2868
2869 B<Note>: Make sure to read the documentation of L</find> and understand the
2870 significance of the C<key> attribute, as its lack may skew your search, and
2871 subsequently result in spurious row creation.
2872
2873 B<Note>: Because find_or_create() reads from the database and then
2874 possibly inserts based on the result, this method is subject to a race
2875 condition. Another process could create a record in the table after
2876 the find has completed and before the create has started. To avoid
2877 this problem, use find_or_create() inside a transaction.
2878
2879 B<Note>: Take care when using C<find_or_create> with a table having
2880 columns with default values that you intend to be automatically
2881 supplied by the database (e.g. an auto_increment primary key column).
2882 In normal usage, the value of such columns should NOT be included at
2883 all in the call to C<find_or_create>, even when set to C<undef>.
2884
2885 See also L</find> and L</update_or_create>. For information on how to declare
2886 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
2887
2888 If you need to know if an existing row was found or a new one created use
2889 L</find_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
2890 to call L<DBIx::Class::Row/insert> to save the newly created row to the
2891 database!
2892
2893   my $cd = $schema->resultset('CD')->find_or_new({
2894     cdid   => 5,
2895     artist => 'Massive Attack',
2896     title  => 'Mezzanine',
2897     year   => 2005,
2898   });
2899
2900   if( !$cd->in_storage ) {
2901       # do some stuff
2902       $cd->insert;
2903   }
2904
2905 =cut
2906
2907 sub find_or_create {
2908   my $self     = shift;
2909   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2910   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2911   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2912     return $row;
2913   }
2914   return $self->create($hash);
2915 }
2916
2917 =head2 update_or_create
2918
2919 =over 4
2920
2921 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2922
2923 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2924
2925 =back
2926
2927   $resultset->update_or_create({ col => $val, ... });
2928
2929 Like L</find_or_create>, but if a row is found it is immediately updated via
2930 C<< $found_row->update (\%col_data) >>.
2931
2932
2933 Takes an optional C<key> attribute to search on a specific unique constraint.
2934 For example:
2935
2936   # In your application
2937   my $cd = $schema->resultset('CD')->update_or_create(
2938     {
2939       artist => 'Massive Attack',
2940       title  => 'Mezzanine',
2941       year   => 1998,
2942     },
2943     { key => 'cd_artist_title' }
2944   );
2945
2946   $cd->cd_to_producer->update_or_create({
2947     producer => $producer,
2948     name => 'harry',
2949   }, {
2950     key => 'primary',
2951   });
2952
2953 B<Note>: Make sure to read the documentation of L</find> and understand the
2954 significance of the C<key> attribute, as its lack may skew your search, and
2955 subsequently result in spurious row creation.
2956
2957 B<Note>: Take care when using C<update_or_create> with a table having
2958 columns with default values that you intend to be automatically
2959 supplied by the database (e.g. an auto_increment primary key column).
2960 In normal usage, the value of such columns should NOT be included at
2961 all in the call to C<update_or_create>, even when set to C<undef>.
2962
2963 See also L</find> and L</find_or_create>. For information on how to declare
2964 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
2965
2966 If you need to know if an existing row was updated or a new one created use
2967 L</update_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
2968 to call L<DBIx::Class::Row/insert> to save the newly created row to the
2969 database!
2970
2971 =cut
2972
2973 sub update_or_create {
2974   my $self = shift;
2975   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2976   my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
2977
2978   my $row = $self->find($cond, $attrs);
2979   if (defined $row) {
2980     $row->update($cond);
2981     return $row;
2982   }
2983
2984   return $self->create($cond);
2985 }
2986
2987 =head2 update_or_new
2988
2989 =over 4
2990
2991 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2992
2993 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2994
2995 =back
2996
2997   $resultset->update_or_new({ col => $val, ... });
2998
2999 Like L</find_or_new> but if a row is found it is immediately updated via
3000 C<< $found_row->update (\%col_data) >>.
3001
3002 For example:
3003
3004   # In your application
3005   my $cd = $schema->resultset('CD')->update_or_new(
3006     {
3007       artist => 'Massive Attack',
3008       title  => 'Mezzanine',
3009       year   => 1998,
3010     },
3011     { key => 'cd_artist_title' }
3012   );
3013
3014   if ($cd->in_storage) {
3015       # the cd was updated
3016   }
3017   else {
3018       # the cd is not yet in the database, let's insert it
3019       $cd->insert;
3020   }
3021
3022 B<Note>: Make sure to read the documentation of L</find> and understand the
3023 significance of the C<key> attribute, as its lack may skew your search, and
3024 subsequently result in spurious new objects.
3025
3026 B<Note>: Take care when using C<update_or_new> with a table having
3027 columns with default values that you intend to be automatically
3028 supplied by the database (e.g. an auto_increment primary key column).
3029 In normal usage, the value of such columns should NOT be included at
3030 all in the call to C<update_or_new>, even when set to C<undef>.
3031
3032 See also L</find>, L</find_or_create> and L</find_or_new>.
3033
3034 =cut
3035
3036 sub update_or_new {
3037     my $self  = shift;
3038     my $attrs = ( @_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {} );
3039     my $cond  = ref $_[0] eq 'HASH' ? shift : {@_};
3040
3041     my $row = $self->find( $cond, $attrs );
3042     if ( defined $row ) {
3043         $row->update($cond);
3044         return $row;
3045     }
3046
3047     return $self->new_result($cond);
3048 }
3049
3050 =head2 get_cache
3051
3052 =over 4
3053
3054 =item Arguments: none
3055
3056 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass> | undef
3057
3058 =back
3059
3060 Gets the contents of the cache for the resultset, if the cache is set.
3061
3062 The cache is populated either by using the L</prefetch> attribute to
3063 L</search> or by calling L</set_cache>.
3064
3065 =cut
3066
3067 sub get_cache {
3068   shift->{all_cache};
3069 }
3070
3071 =head2 set_cache
3072
3073 =over 4
3074
3075 =item Arguments: L<\@result_objs|DBIx::Class::Manual::ResultClass>
3076
3077 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass>
3078
3079 =back
3080
3081 Sets the contents of the cache for the resultset. Expects an arrayref
3082 of objects of the same class as those produced by the resultset. Note that
3083 if the cache is set, the resultset will return the cached objects rather
3084 than re-querying the database even if the cache attr is not set.
3085
3086 The contents of the cache can also be populated by using the
3087 L</prefetch> attribute to L</search>.
3088
3089 =cut
3090
3091 sub set_cache {
3092   my ( $self, $data ) = @_;
3093   $self->throw_exception("set_cache requires an arrayref")
3094       if defined($data) && (ref $data ne 'ARRAY');
3095   $self->{all_cache} = $data;
3096 }
3097
3098 =head2 clear_cache
3099
3100 =over 4
3101
3102 =item Arguments: none
3103
3104 =item Return Value: undef
3105
3106 =back
3107
3108 Clears the cache for the resultset.
3109
3110 =cut
3111
3112 sub clear_cache {
3113   shift->set_cache(undef);
3114 }
3115
3116 =head2 is_paged
3117
3118 =over 4
3119
3120 =item Arguments: none
3121
3122 =item Return Value: true, if the resultset has been paginated
3123
3124 =back
3125
3126 =cut
3127
3128 sub is_paged {
3129   my ($self) = @_;
3130   return !!$self->{attrs}{page};
3131 }
3132
3133 =head2 is_ordered
3134
3135 =over 4
3136
3137 =item Arguments: none
3138
3139 =item Return Value: true, if the resultset has been ordered with C<order_by>.
3140
3141 =back
3142
3143 =cut
3144
3145 sub is_ordered {
3146   my ($self) = @_;
3147   return scalar $self->result_source->storage->_extract_order_criteria($self->{attrs}{order_by});
3148 }
3149
3150 =head2 related_resultset
3151
3152 =over 4
3153
3154 =item Arguments: $rel_name
3155
3156 =item Return Value: L<$resultset|/search>
3157
3158 =back
3159
3160 Returns a related resultset for the supplied relationship name.
3161
3162   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
3163
3164 =cut
3165
3166 sub related_resultset {
3167   my ($self, $rel) = @_;
3168
3169   return $self->{related_resultsets}{$rel}
3170     if defined $self->{related_resultsets}{$rel};
3171
3172   return $self->{related_resultsets}{$rel} = do {
3173     my $rsrc = $self->result_source;
3174     my $rel_info = $rsrc->relationship_info($rel);
3175
3176     $self->throw_exception(
3177       "search_related: result source '" . $rsrc->source_name .
3178         "' has no such relationship $rel")
3179       unless $rel_info;
3180
3181     my $attrs = $self->_chain_relationship($rel);
3182
3183     my $join_count = $attrs->{seen_join}{$rel};
3184
3185     my $alias = $self->result_source->storage
3186         ->relname_to_table_alias($rel, $join_count);
3187
3188     # since this is search_related, and we already slid the select window inwards
3189     # (the select/as attrs were deleted in the beginning), we need to flip all
3190     # left joins to inner, so we get the expected results
3191     # read the comment on top of the actual function to see what this does
3192     $attrs->{from} = $rsrc->schema->storage->_inner_join_to_node ($attrs->{from}, $alias);
3193
3194
3195     #XXX - temp fix for result_class bug. There likely is a more elegant fix -groditi
3196     delete @{$attrs}{qw(result_class alias)};
3197
3198     my $rel_source = $rsrc->related_source($rel);
3199
3200     my $new = do {
3201
3202       # The reason we do this now instead of passing the alias to the
3203       # search_rs below is that if you wrap/overload resultset on the
3204       # source you need to know what alias it's -going- to have for things
3205       # to work sanely (e.g. RestrictWithObject wants to be able to add
3206       # extra query restrictions, and these may need to be $alias.)
3207
3208       my $rel_attrs = $rel_source->resultset_attributes;
3209       local $rel_attrs->{alias} = $alias;
3210
3211       $rel_source->resultset
3212                  ->search_rs(
3213                      undef, {
3214                        %$attrs,
3215                        where => $attrs->{where},
3216                    });
3217     };
3218
3219     if (my $cache = $self->get_cache) {
3220       my @related_cache = map
3221         { @{$_->related_resultset($rel)->get_cache||[]} }
3222         @$cache
3223       ;
3224
3225       $new->set_cache(\@related_cache) if @related_cache;
3226     }
3227
3228     $new;
3229   };
3230 }
3231
3232 =head2 current_source_alias
3233
3234 =over 4
3235
3236 =item Arguments: none
3237
3238 =item Return Value: $source_alias
3239
3240 =back
3241
3242 Returns the current table alias for the result source this resultset is built
3243 on, that will be used in the SQL query. Usually it is C<me>.
3244
3245 Currently the source alias that refers to the result set returned by a
3246 L</search>/L</find> family method depends on how you got to the resultset: it's
3247 C<me> by default, but eg. L</search_related> aliases it to the related result
3248 source name (and keeps C<me> referring to the original result set). The long
3249 term goal is to make L<DBIx::Class> always alias the current resultset as C<me>
3250 (and make this method unnecessary).
3251
3252 Thus it's currently necessary to use this method in predefined queries (see
3253 L<DBIx::Class::Manual::Cookbook/Predefined searches>) when referring to the
3254 source alias of the current result set:
3255
3256   # in a result set class
3257   sub modified_by {
3258     my ($self, $user) = @_;
3259
3260     my $me = $self->current_source_alias;
3261
3262     return $self->search({
3263       "$me.modified" => $user->id,
3264     });
3265   }
3266
3267 =cut
3268
3269 sub current_source_alias {
3270   return (shift->{attrs} || {})->{alias} || 'me';
3271 }
3272
3273 =head2 as_subselect_rs
3274
3275 =over 4
3276
3277 =item Arguments: none
3278
3279 =item Return Value: L<$resultset|/search>
3280
3281 =back
3282
3283 Act as a barrier to SQL symbols.  The resultset provided will be made into a
3284 "virtual view" by including it as a subquery within the from clause.  From this
3285 point on, any joined tables are inaccessible to ->search on the resultset (as if
3286 it were simply where-filtered without joins).  For example:
3287
3288  my $rs = $schema->resultset('Bar')->search({'x.name' => 'abc'},{ join => 'x' });
3289
3290  # 'x' now pollutes the query namespace
3291
3292  # So the following works as expected
3293  my $ok_rs = $rs->search({'x.other' => 1});
3294
3295  # But this doesn't: instead of finding a 'Bar' related to two x rows (abc and
3296  # def) we look for one row with contradictory terms and join in another table
3297  # (aliased 'x_2') which we never use
3298  my $broken_rs = $rs->search({'x.name' => 'def'});
3299
3300  my $rs2 = $rs->as_subselect_rs;
3301
3302  # doesn't work - 'x' is no longer accessible in $rs2, having been sealed away
3303  my $not_joined_rs = $rs2->search({'x.other' => 1});
3304
3305  # works as expected: finds a 'table' row related to two x rows (abc and def)
3306  my $correctly_joined_rs = $rs2->search({'x.name' => 'def'});
3307
3308 Another example of when one might use this would be to select a subset of
3309 columns in a group by clause:
3310
3311  my $rs = $schema->resultset('Bar')->search(undef, {
3312    group_by => [qw{ id foo_id baz_id }],
3313  })->as_subselect_rs->search(undef, {
3314    columns => [qw{ id foo_id }]
3315  });
3316
3317 In the above example normally columns would have to be equal to the group by,
3318 but because we isolated the group by into a subselect the above works.
3319
3320 =cut
3321
3322 sub as_subselect_rs {
3323   my $self = shift;
3324
3325   my $attrs = $self->_resolved_attrs;
3326
3327   my $fresh_rs = (ref $self)->new (
3328     $self->result_source
3329   );
3330
3331   # these pieces will be locked in the subquery
3332   delete $fresh_rs->{cond};
3333   delete @{$fresh_rs->{attrs}}{qw/where bind/};
3334
3335   return $fresh_rs->search( {}, {
3336     from => [{
3337       $attrs->{alias} => $self->as_query,
3338       -alias  => $attrs->{alias},
3339       -rsrc   => $self->result_source,
3340     }],
3341     alias => $attrs->{alias},
3342   });
3343 }
3344
3345 # This code is called by search_related, and makes sure there
3346 # is clear separation between the joins before, during, and
3347 # after the relationship. This information is needed later
3348 # in order to properly resolve prefetch aliases (any alias
3349 # with a relation_chain_depth less than the depth of the
3350 # current prefetch is not considered)
3351 #
3352 # The increments happen twice per join. An even number means a
3353 # relationship specified via a search_related, whereas an odd
3354 # number indicates a join/prefetch added via attributes
3355 #
3356 # Also this code will wrap the current resultset (the one we
3357 # chain to) in a subselect IFF it contains limiting attributes
3358 sub _chain_relationship {
3359   my ($self, $rel) = @_;
3360   my $source = $self->result_source;
3361   my $attrs = { %{$self->{attrs}||{}} };
3362
3363   # we need to take the prefetch the attrs into account before we
3364   # ->_resolve_join as otherwise they get lost - captainL
3365   my $join = $self->_merge_joinpref_attr( $attrs->{join}, $attrs->{prefetch} );
3366
3367   delete @{$attrs}{qw/join prefetch collapse group_by distinct _grouped_by_distinct select as columns +select +as +columns/};
3368
3369   my $seen = { %{ (delete $attrs->{seen_join}) || {} } };
3370
3371   my $from;
3372   my @force_subq_attrs = qw/offset rows group_by having/;
3373
3374   if (
3375     ($attrs->{from} && ref $attrs->{from} ne 'ARRAY')
3376       ||
3377     $self->_has_resolved_attr (@force_subq_attrs)
3378   ) {
3379     # Nuke the prefetch (if any) before the new $rs attrs
3380     # are resolved (prefetch is useless - we are wrapping
3381     # a subquery anyway).
3382     my $rs_copy = $self->search;
3383     $rs_copy->{attrs}{join} = $self->_merge_joinpref_attr (
3384       $rs_copy->{attrs}{join},
3385       delete $rs_copy->{attrs}{prefetch},
3386     );
3387
3388     $from = [{
3389       -rsrc   => $source,
3390       -alias  => $attrs->{alias},
3391       $attrs->{alias} => $rs_copy->as_query,
3392     }];
3393     delete @{$attrs}{@force_subq_attrs, qw/where bind/};
3394     $seen->{-relation_chain_depth} = 0;
3395   }
3396   elsif ($attrs->{from}) {  #shallow copy suffices
3397     $from = [ @{$attrs->{from}} ];
3398   }
3399   else {
3400     $from = [{
3401       -rsrc  => $source,
3402       -alias => $attrs->{alias},
3403       $attrs->{alias} => $source->from,
3404     }];
3405   }
3406
3407   my $jpath = ($seen->{-relation_chain_depth})
3408     ? $from->[-1][0]{-join_path}
3409     : [];
3410
3411   my @requested_joins = $source->_resolve_join(
3412     $join,
3413     $attrs->{alias},
3414     $seen,
3415     $jpath,
3416   );
3417
3418   push @$from, @requested_joins;
3419
3420   $seen->{-relation_chain_depth}++;
3421
3422   # if $self already had a join/prefetch specified on it, the requested
3423   # $rel might very well be already included. What we do in this case
3424   # is effectively a no-op (except that we bump up the chain_depth on
3425   # the join in question so we could tell it *is* the search_related)
3426   my $already_joined;
3427
3428   # we consider the last one thus reverse
3429   for my $j (reverse @requested_joins) {
3430     my ($last_j) = keys %{$j->[0]{-join_path}[-1]};
3431     if ($rel eq $last_j) {
3432       $j->[0]{-relation_chain_depth}++;
3433       $already_joined++;
3434       last;
3435     }
3436   }
3437
3438   unless ($already_joined) {
3439     push @$from, $source->_resolve_join(
3440       $rel,
3441       $attrs->{alias},
3442       $seen,
3443       $jpath,
3444     );
3445   }
3446
3447   $seen->{-relation_chain_depth}++;
3448
3449   return {%$attrs, from => $from, seen_join => $seen};
3450 }
3451
3452 sub _resolved_attrs {
3453   my $self = shift;
3454   return $self->{_attrs} if $self->{_attrs};
3455
3456   my $attrs  = { %{ $self->{attrs} || {} } };
3457   my $source = $self->result_source;
3458   my $alias  = $attrs->{alias};
3459
3460   # default selection list
3461   $attrs->{columns} = [ $source->columns ]
3462     unless List::Util::first { exists $attrs->{$_} } qw/columns cols select as/;
3463
3464   # merge selectors together
3465   for (qw/columns select as/) {
3466     $attrs->{$_} = $self->_merge_attr($attrs->{$_}, delete $attrs->{"+$_"})
3467       if $attrs->{$_} or $attrs->{"+$_"};
3468   }
3469
3470   # disassemble columns
3471   my (@sel, @as);
3472   if (my $cols = delete $attrs->{columns}) {
3473     for my $c (ref $cols eq 'ARRAY' ? @$cols : $cols) {
3474       if (ref $c eq 'HASH') {
3475         for my $as (sort keys %$c) {
3476           push @sel, $c->{$as};
3477           push @as, $as;
3478         }
3479       }
3480       else {
3481         push @sel, $c;
3482         push @as, $c;
3483       }
3484     }
3485   }
3486
3487   # when trying to weed off duplicates later do not go past this point -
3488   # everything added from here on is unbalanced "anyone's guess" stuff
3489   my $dedup_stop_idx = $#as;
3490
3491   push @as, @{ ref $attrs->{as} eq 'ARRAY' ? $attrs->{as} : [ $attrs->{as} ] }
3492     if $attrs->{as};
3493   push @sel, @{ ref $attrs->{select} eq 'ARRAY' ? $attrs->{select} : [ $attrs->{select} ] }
3494     if $attrs->{select};
3495
3496   # assume all unqualified selectors to apply to the current alias (legacy stuff)
3497   $_ = (ref $_ or $_ =~ /\./) ? $_ : "$alias.$_" for @sel;
3498
3499   # disqualify all $alias.col as-bits (inflate-map mandated)
3500   $_ = ($_ =~ /^\Q$alias.\E(.+)$/) ? $1 : $_ for @as;
3501
3502   # de-duplicate the result (remove *identical* select/as pairs)
3503   # and also die on duplicate {as} pointing to different {select}s
3504   # not using a c-style for as the condition is prone to shrinkage
3505   my $seen;
3506   my $i = 0;
3507   while ($i <= $dedup_stop_idx) {
3508     if ($seen->{"$sel[$i] \x00\x00 $as[$i]"}++) {
3509       splice @sel, $i, 1;
3510       splice @as, $i, 1;
3511       $dedup_stop_idx--;
3512     }
3513     elsif ($seen->{$as[$i]}++) {
3514       $self->throw_exception(
3515         "inflate_result() alias '$as[$i]' specified twice with different SQL-side {select}-ors"
3516       );
3517     }
3518     else {
3519       $i++;
3520     }
3521   }
3522
3523   $attrs->{select} = \@sel;
3524   $attrs->{as} = \@as;
3525
3526   $attrs->{from} ||= [{
3527     -rsrc   => $source,
3528     -alias  => $self->{attrs}{alias},
3529     $self->{attrs}{alias} => $source->from,
3530   }];
3531
3532   if ( $attrs->{join} || $attrs->{prefetch} ) {
3533
3534     $self->throw_exception ('join/prefetch can not be used with a custom {from}')
3535       if ref $attrs->{from} ne 'ARRAY';
3536
3537     my $join = (delete $attrs->{join}) || {};
3538
3539     if ( defined $attrs->{prefetch} ) {
3540       $join = $self->_merge_joinpref_attr( $join, $attrs->{prefetch} );
3541     }
3542
3543     $attrs->{from} =    # have to copy here to avoid corrupting the original
3544       [
3545         @{ $attrs->{from} },
3546         $source->_resolve_join(
3547           $join,
3548           $alias,
3549           { %{ $attrs->{seen_join} || {} } },
3550           ( $attrs->{seen_join} && keys %{$attrs->{seen_join}})
3551             ? $attrs->{from}[-1][0]{-join_path}
3552             : []
3553           ,
3554         )
3555       ];
3556   }
3557
3558   if ( defined $attrs->{order_by} ) {
3559     $attrs->{order_by} = (
3560       ref( $attrs->{order_by} ) eq 'ARRAY'
3561       ? [ @{ $attrs->{order_by} } ]
3562       : [ $attrs->{order_by} || () ]
3563     );
3564   }
3565
3566   if ($attrs->{group_by} and ref $attrs->{group_by} ne 'ARRAY') {
3567     $attrs->{group_by} = [ $attrs->{group_by} ];
3568   }
3569
3570   # generate the distinct induced group_by early, as prefetch will be carried via a
3571   # subquery (since a group_by is present)
3572   if (delete $attrs->{distinct}) {
3573     if ($attrs->{group_by}) {
3574       carp_unique ("Useless use of distinct on a grouped resultset ('distinct' is ignored when a 'group_by' is present)");
3575     }
3576     else {
3577       $attrs->{_grouped_by_distinct} = 1;
3578       # distinct affects only the main selection part, not what prefetch may
3579       # add below.
3580       $attrs->{group_by} = $source->storage->_group_over_selection($attrs);
3581     }
3582   }
3583
3584   # generate selections based on the prefetch helper
3585   my $prefetch;
3586   $prefetch = $self->_merge_joinpref_attr( {}, delete $attrs->{prefetch} )
3587     if defined $attrs->{prefetch};
3588
3589   if ($prefetch) {
3590
3591     $self->throw_exception("Unable to prefetch, resultset contains an unnamed selector $attrs->{_dark_selector}{string}")
3592       if $attrs->{_dark_selector};
3593
3594     $attrs->{collapse} = 1;
3595
3596     # this is a separate structure (we don't look in {from} directly)
3597     # as the resolver needs to shift things off the lists to work
3598     # properly (identical-prefetches on different branches)
3599     my $join_map = {};
3600     if (ref $attrs->{from} eq 'ARRAY') {
3601
3602       my $start_depth = $attrs->{seen_join}{-relation_chain_depth} || 0;
3603
3604       for my $j ( @{$attrs->{from}}[1 .. $#{$attrs->{from}} ] ) {
3605         next unless $j->[0]{-alias};
3606         next unless $j->[0]{-join_path};
3607         next if ($j->[0]{-relation_chain_depth} || 0) < $start_depth;
3608
3609         my @jpath = map { keys %$_ } @{$j->[0]{-join_path}};
3610
3611         my $p = $join_map;
3612         $p = $p->{$_} ||= {} for @jpath[ ($start_depth/2) .. $#jpath]; #only even depths are actual jpath boundaries
3613         push @{$p->{-join_aliases} }, $j->[0]{-alias};
3614       }
3615     }
3616
3617     my @prefetch = $source->_resolve_prefetch( $prefetch, $alias, $join_map );
3618
3619     push @{ $attrs->{select} }, (map { $_->[0] } @prefetch);
3620     push @{ $attrs->{as} }, (map { $_->[1] } @prefetch);
3621   }
3622
3623   if ( List::Util::first { $_ =~ /\./ } @{$attrs->{as}} ) {
3624     $attrs->{_related_results_construction} = 1;
3625   }
3626
3627   # run through the resulting joinstructure (starting from our current slot)
3628   # and unset collapse if proven unnecessary
3629   #
3630   # also while we are at it find out if the current root source has
3631   # been premultiplied by previous related_source chaining
3632   #
3633   # this allows to predict whether a root object with all other relation
3634   # data set to NULL is in fact unique
3635   if ($attrs->{collapse}) {
3636
3637     if (ref $attrs->{from} eq 'ARRAY') {
3638
3639       if (@{$attrs->{from}} == 1) {
3640         # no joins - no collapse
3641         $attrs->{collapse} = 0;
3642       }
3643       else {
3644         # find where our table-spec starts
3645         my @fromlist = @{$attrs->{from}};
3646         while (@fromlist) {
3647           my $t = shift @fromlist;
3648
3649           my $is_multi;
3650           # me vs join from-spec distinction - a ref means non-root
3651           if (ref $t eq 'ARRAY') {
3652             $t = $t->[0];
3653             $is_multi ||= ! $t->{-is_single};
3654           }
3655           last if ($t->{-alias} && $t->{-alias} eq $alias);
3656           $attrs->{_main_source_premultiplied} ||= $is_multi;
3657         }
3658
3659         # no non-singles remaining, nor any premultiplication - nothing to collapse
3660         if (
3661           ! $attrs->{_main_source_premultiplied}
3662             and
3663           ! List::Util::first { ! $_->[0]{-is_single} } @fromlist
3664         ) {
3665           $attrs->{collapse} = 0;
3666         }
3667       }
3668     }
3669
3670     else {
3671       # if we can not analyze the from - err on the side of safety
3672       $attrs->{_main_source_premultiplied} = 1;
3673     }
3674   }
3675
3676   # if both page and offset are specified, produce a combined offset
3677   # even though it doesn't make much sense, this is what pre 081xx has
3678   # been doing
3679   if (my $page = delete $attrs->{page}) {
3680     $attrs->{offset} =
3681       ($attrs->{rows} * ($page - 1))
3682             +
3683       ($attrs->{offset} || 0)
3684     ;
3685   }
3686
3687   return $self->{_attrs} = $attrs;
3688 }
3689
3690 sub _rollout_attr {
3691   my ($self, $attr) = @_;
3692
3693   if (ref $attr eq 'HASH') {
3694     return $self->_rollout_hash($attr);
3695   } elsif (ref $attr eq 'ARRAY') {
3696     return $self->_rollout_array($attr);
3697   } else {
3698     return [$attr];
3699   }
3700 }
3701
3702 sub _rollout_array {
3703   my ($self, $attr) = @_;
3704
3705   my @rolled_array;
3706   foreach my $element (@{$attr}) {
3707     if (ref $element eq 'HASH') {
3708       push( @rolled_array, @{ $self->_rollout_hash( $element ) } );
3709     } elsif (ref $element eq 'ARRAY') {
3710       #  XXX - should probably recurse here
3711       push( @rolled_array, @{$self->_rollout_array($element)} );
3712     } else {
3713       push( @rolled_array, $element );
3714     }
3715   }
3716   return \@rolled_array;
3717 }
3718
3719 sub _rollout_hash {
3720   my ($self, $attr) = @_;
3721
3722   my @rolled_array;
3723   foreach my $key (keys %{$attr}) {
3724     push( @rolled_array, { $key => $attr->{$key} } );
3725   }
3726   return \@rolled_array;
3727 }
3728
3729 sub _calculate_score {
3730   my ($self, $a, $b) = @_;
3731
3732   if (defined $a xor defined $b) {
3733     return 0;
3734   }
3735   elsif (not defined $a) {
3736     return 1;
3737   }
3738
3739   if (ref $b eq 'HASH') {
3740     my ($b_key) = keys %{$b};
3741     if (ref $a eq 'HASH') {
3742       my ($a_key) = keys %{$a};
3743       if ($a_key eq $b_key) {
3744         return (1 + $self->_calculate_score( $a->{$a_key}, $b->{$b_key} ));
3745       } else {
3746         return 0;
3747       }
3748     } else {
3749       return ($a eq $b_key) ? 1 : 0;
3750     }
3751   } else {
3752     if (ref $a eq 'HASH') {
3753       my ($a_key) = keys %{$a};
3754       return ($b eq $a_key) ? 1 : 0;
3755     } else {
3756       return ($b eq $a) ? 1 : 0;
3757     }
3758   }
3759 }
3760
3761 sub _merge_joinpref_attr {
3762   my ($self, $orig, $import) = @_;
3763
3764   return $import unless defined($orig);
3765   return $orig unless defined($import);
3766
3767   $orig = $self->_rollout_attr($orig);
3768   $import = $self->_rollout_attr($import);
3769
3770   my $seen_keys;
3771   foreach my $import_element ( @{$import} ) {
3772     # find best candidate from $orig to merge $b_element into
3773     my $best_candidate = { position => undef, score => 0 }; my $position = 0;
3774     foreach my $orig_element ( @{$orig} ) {
3775       my $score = $self->_calculate_score( $orig_element, $import_element );
3776       if ($score > $best_candidate->{score}) {
3777         $best_candidate->{position} = $position;
3778         $best_candidate->{score} = $score;
3779       }
3780       $position++;
3781     }
3782     my ($import_key) = ( ref $import_element eq 'HASH' ) ? keys %{$import_element} : ($import_element);
3783     $import_key = '' if not defined $import_key;
3784
3785     if ($best_candidate->{score} == 0 || exists $seen_keys->{$import_key}) {
3786       push( @{$orig}, $import_element );
3787     } else {
3788       my $orig_best = $orig->[$best_candidate->{position}];
3789       # merge orig_best and b_element together and replace original with merged
3790       if (ref $orig_best ne 'HASH') {
3791         $orig->[$best_candidate->{position}] = $import_element;
3792       } elsif (ref $import_element eq 'HASH') {
3793         my ($key) = keys %{$orig_best};
3794         $orig->[$best_candidate->{position}] = { $key => $self->_merge_joinpref_attr($orig_best->{$key}, $import_element->{$key}) };
3795       }
3796     }
3797     $seen_keys->{$import_key} = 1; # don't merge the same key twice
3798   }
3799
3800   return @$orig ? $orig : ();
3801 }
3802
3803 {
3804   my $hm;
3805
3806   sub _merge_attr {
3807     $hm ||= do {
3808       require Hash::Merge;
3809       my $hm = Hash::Merge->new;
3810
3811       $hm->specify_behavior({
3812         SCALAR => {
3813           SCALAR => sub {
3814             my ($defl, $defr) = map { defined $_ } (@_[0,1]);
3815
3816             if ($defl xor $defr) {
3817               return [ $defl ? $_[0] : $_[1] ];
3818             }
3819             elsif (! $defl) {
3820               return [];
3821             }
3822             elsif (__HM_DEDUP and $_[0] eq $_[1]) {
3823               return [ $_[0] ];
3824             }
3825             else {
3826               return [$_[0], $_[1]];
3827             }
3828           },
3829           ARRAY => sub {
3830             return $_[1] if !defined $_[0];
3831             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3832             return [$_[0], @{$_[1]}]
3833           },
3834           HASH  => sub {
3835             return [] if !defined $_[0] and !keys %{$_[1]};
3836             return [ $_[1] ] if !defined $_[0];
3837             return [ $_[0] ] if !keys %{$_[1]};
3838             return [$_[0], $_[1]]
3839           },
3840         },
3841         ARRAY => {
3842           SCALAR => sub {
3843             return $_[0] if !defined $_[1];
3844             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3845             return [@{$_[0]}, $_[1]]
3846           },
3847           ARRAY => sub {
3848             my @ret = @{$_[0]} or return $_[1];
3849             return [ @ret, @{$_[1]} ] unless __HM_DEDUP;
3850             my %idx = map { $_ => 1 } @ret;
3851             push @ret, grep { ! defined $idx{$_} } (@{$_[1]});
3852             \@ret;
3853           },
3854           HASH => sub {
3855             return [ $_[1] ] if ! @{$_[0]};
3856             return $_[0] if !keys %{$_[1]};
3857             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3858             return [ @{$_[0]}, $_[1] ];
3859           },
3860         },
3861         HASH => {
3862           SCALAR => sub {
3863             return [] if !keys %{$_[0]} and !defined $_[1];
3864             return [ $_[0] ] if !defined $_[1];
3865             return [ $_[1] ] if !keys %{$_[0]};
3866             return [$_[0], $_[1]]
3867           },
3868           ARRAY => sub {
3869             return [] if !keys %{$_[0]} and !@{$_[1]};
3870             return [ $_[0] ] if !@{$_[1]};
3871             return $_[1] if !keys %{$_[0]};
3872             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3873             return [ $_[0], @{$_[1]} ];
3874           },
3875           HASH => sub {
3876             return [] if !keys %{$_[0]} and !keys %{$_[1]};
3877             return [ $_[0] ] if !keys %{$_[1]};
3878             return [ $_[1] ] if !keys %{$_[0]};
3879             return [ $_[0] ] if $_[0] eq $_[1];
3880             return [ $_[0], $_[1] ];
3881           },
3882         }
3883       } => 'DBIC_RS_ATTR_MERGER');
3884       $hm;
3885     };
3886
3887     return $hm->merge ($_[1], $_[2]);
3888   }
3889 }
3890
3891 sub STORABLE_freeze {
3892   my ($self, $cloning) = @_;
3893   my $to_serialize = { %$self };
3894
3895   # A cursor in progress can't be serialized (and would make little sense anyway)
3896   # the parser can be regenerated (and can't be serialized)
3897   delete @{$to_serialize}{qw/cursor _row_parser _result_inflator/};
3898
3899   # nor is it sensical to store a not-yet-fired-count pager
3900   if ($to_serialize->{pager} and ref $to_serialize->{pager}{total_entries} eq 'CODE') {
3901     delete $to_serialize->{pager};
3902   }
3903
3904   Storable::nfreeze($to_serialize);
3905 }
3906
3907 # need this hook for symmetry
3908 sub STORABLE_thaw {
3909   my ($self, $cloning, $serialized) = @_;
3910
3911   %$self = %{ Storable::thaw($serialized) };
3912
3913   $self;
3914 }
3915
3916
3917 =head2 throw_exception
3918
3919 See L<DBIx::Class::Schema/throw_exception> for details.
3920
3921 =cut
3922
3923 sub throw_exception {
3924   my $self=shift;
3925
3926   if (ref $self and my $rsrc = $self->result_source) {
3927     $rsrc->throw_exception(@_)
3928   }
3929   else {
3930     DBIx::Class::Exception->throw(@_);
3931   }
3932 }
3933
3934 1;
3935
3936 __END__
3937
3938 # XXX: FIXME: Attributes docs need clearing up
3939
3940 =head1 ATTRIBUTES
3941
3942 Attributes are used to refine a ResultSet in various ways when
3943 searching for data. They can be passed to any method which takes an
3944 C<\%attrs> argument. See L</search>, L</search_rs>, L</find>,
3945 L</count>.
3946
3947 Default attributes can be set on the result class using
3948 L<DBIx::Class::ResultSource/resultset_attributes>.  (Please read
3949 the CAVEATS on that feature before using it!)
3950
3951 These are in no particular order:
3952
3953 =head2 order_by
3954
3955 =over 4
3956
3957 =item Value: ( $order_by | \@order_by | \%order_by )
3958
3959 =back
3960
3961 Which column(s) to order the results by.
3962
3963 [The full list of suitable values is documented in
3964 L<SQL::Abstract/"ORDER BY CLAUSES">; the following is a summary of
3965 common options.]
3966
3967 If a single column name, or an arrayref of names is supplied, the
3968 argument is passed through directly to SQL. The hashref syntax allows
3969 for connection-agnostic specification of ordering direction:
3970
3971  For descending order:
3972
3973   order_by => { -desc => [qw/col1 col2 col3/] }
3974
3975  For explicit ascending order:
3976
3977   order_by => { -asc => 'col' }
3978
3979 The old scalarref syntax (i.e. order_by => \'year DESC') is still
3980 supported, although you are strongly encouraged to use the hashref
3981 syntax as outlined above.
3982
3983 =head2 columns
3984
3985 =over 4
3986
3987 =item Value: \@columns | \%columns | $column
3988
3989 =back
3990
3991 Shortcut to request a particular set of columns to be retrieved. Each
3992 column spec may be a string (a table column name), or a hash (in which
3993 case the key is the C<as> value, and the value is used as the C<select>
3994 expression). Adds C<me.> onto the start of any column without a C<.> in
3995 it and sets C<select> from that, then auto-populates C<as> from
3996 C<select> as normal. (You may also use the C<cols> attribute, as in
3997 earlier versions of DBIC, but this is deprecated.)
3998
3999 Essentially C<columns> does the same as L</select> and L</as>.
4000
4001     columns => [ 'foo', { bar => 'baz' } ]
4002
4003 is the same as
4004
4005     select => [qw/foo baz/],
4006     as => [qw/foo bar/]
4007
4008 =head2 +columns
4009
4010 =over 4
4011
4012 =item Value: \@columns
4013
4014 =back
4015
4016 Indicates additional columns to be selected from storage. Works the same as
4017 L</columns> but adds columns to the selection. (You may also use the
4018 C<include_columns> attribute, as in earlier versions of DBIC, but this is
4019 deprecated). For example:-
4020
4021   $schema->resultset('CD')->search(undef, {
4022     '+columns' => ['artist.name'],
4023     join => ['artist']
4024   });
4025
4026 would return all CDs and include a 'name' column to the information
4027 passed to object inflation. Note that the 'artist' is the name of the
4028 column (or relationship) accessor, and 'name' is the name of the column
4029 accessor in the related table.
4030
4031 B<NOTE:> You need to explicitly quote '+columns' when defining the attribute.
4032 Not doing so causes Perl to incorrectly interpret +columns as a bareword with a
4033 unary plus operator before it.
4034
4035 =head2 include_columns
4036
4037 =over 4
4038
4039 =item Value: \@columns
4040
4041 =back
4042
4043 Deprecated.  Acts as a synonym for L</+columns> for backward compatibility.
4044
4045 =head2 select
4046
4047 =over 4
4048
4049 =item Value: \@select_columns
4050
4051 =back
4052
4053 Indicates which columns should be selected from the storage. You can use
4054 column names, or in the case of RDBMS back ends, function or stored procedure
4055 names:
4056
4057   $rs = $schema->resultset('Employee')->search(undef, {
4058     select => [
4059       'name',
4060       { count => 'employeeid' },
4061       { max => { length => 'name' }, -as => 'longest_name' }
4062     ]
4063   });
4064
4065   # Equivalent SQL
4066   SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee
4067
4068 B<NOTE:> You will almost always need a corresponding L</as> attribute when you
4069 use L</select>, to instruct DBIx::Class how to store the result of the column.
4070 Also note that the L</as> attribute has nothing to do with the SQL-side 'AS'
4071 identifier aliasing. You can however alias a function, so you can use it in
4072 e.g. an C<ORDER BY> clause. This is done via the C<-as> B<select function
4073 attribute> supplied as shown in the example above.
4074
4075 B<NOTE:> You need to explicitly quote '+select'/'+as' when defining the attributes.
4076 Not doing so causes Perl to incorrectly interpret them as a bareword with a
4077 unary plus operator before it.
4078
4079 =head2 +select
4080
4081 =over 4
4082
4083 Indicates additional columns to be selected from storage.  Works the same as
4084 L</select> but adds columns to the default selection, instead of specifying
4085 an explicit list.
4086
4087 =back
4088
4089 =head2 as
4090
4091 =over 4
4092
4093 =item Value: \@inflation_names
4094
4095 =back
4096
4097 Indicates column names for object inflation. That is L</as> indicates the
4098 slot name in which the column value will be stored within the
4099 L<Row|DBIx::Class::Row> object. The value will then be accessible via this
4100 identifier by the C<get_column> method (or via the object accessor B<if one
4101 with the same name already exists>) as shown below. The L</as> attribute has
4102 B<nothing to do> with the SQL-side C<AS>. See L</select> for details.
4103
4104   $rs = $schema->resultset('Employee')->search(undef, {
4105     select => [
4106       'name',
4107       { count => 'employeeid' },
4108       { max => { length => 'name' }, -as => 'longest_name' }
4109     ],
4110     as => [qw/
4111       name
4112       employee_count
4113       max_name_length
4114     /],
4115   });
4116
4117 If the object against which the search is performed already has an accessor
4118 matching a column name specified in C<as>, the value can be retrieved using
4119 the accessor as normal:
4120
4121   my $name = $employee->name();
4122
4123 If on the other hand an accessor does not exist in the object, you need to
4124 use C<get_column> instead:
4125
4126   my $employee_count = $employee->get_column('employee_count');
4127
4128 You can create your own accessors if required - see
4129 L<DBIx::Class::Manual::Cookbook> for details.
4130
4131 =head2 +as
4132
4133 =over 4
4134
4135 Indicates additional column names for those added via L</+select>. See L</as>.
4136
4137 =back
4138
4139 =head2 join
4140
4141 =over 4
4142
4143 =item Value: ($rel_name | \@rel_names | \%rel_names)
4144
4145 =back
4146
4147 Contains a list of relationships that should be joined for this query.  For
4148 example:
4149
4150   # Get CDs by Nine Inch Nails
4151   my $rs = $schema->resultset('CD')->search(
4152     { 'artist.name' => 'Nine Inch Nails' },
4153     { join => 'artist' }
4154   );
4155
4156 Can also contain a hash reference to refer to the other relation's relations.
4157 For example:
4158
4159   package MyApp::Schema::Track;
4160   use base qw/DBIx::Class/;
4161   __PACKAGE__->table('track');
4162   __PACKAGE__->add_columns(qw/trackid cd position title/);
4163   __PACKAGE__->set_primary_key('trackid');
4164   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
4165   1;
4166
4167   # In your application
4168   my $rs = $schema->resultset('Artist')->search(
4169     { 'track.title' => 'Teardrop' },
4170     {
4171       join     => { cd => 'track' },
4172       order_by => 'artist.name',
4173     }
4174   );
4175
4176 You need to use the relationship (not the table) name in  conditions,
4177 because they are aliased as such. The current table is aliased as "me", so
4178 you need to use me.column_name in order to avoid ambiguity. For example:
4179
4180   # Get CDs from 1984 with a 'Foo' track
4181   my $rs = $schema->resultset('CD')->search(
4182     {
4183       'me.year' => 1984,
4184       'tracks.name' => 'Foo'
4185     },
4186     { join => 'tracks' }
4187   );
4188
4189 If the same join is supplied twice, it will be aliased to <rel>_2 (and
4190 similarly for a third time). For e.g.
4191
4192   my $rs = $schema->resultset('Artist')->search({
4193     'cds.title'   => 'Down to Earth',
4194     'cds_2.title' => 'Popular',
4195   }, {
4196     join => [ qw/cds cds/ ],
4197   });
4198
4199 will return a set of all artists that have both a cd with title 'Down
4200 to Earth' and a cd with title 'Popular'.
4201
4202 If you want to fetch related objects from other tables as well, see L</prefetch>
4203 below.
4204
4205  NOTE: An internal join-chain pruner will discard certain joins while
4206  constructing the actual SQL query, as long as the joins in question do not
4207  affect the retrieved result. This for example includes 1:1 left joins
4208  that are not part of the restriction specification (WHERE/HAVING) nor are
4209  a part of the query selection.
4210
4211 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
4212
4213 =head2 collapse
4214
4215 =over 4
4216
4217 =item Value: (0 | 1)
4218
4219 =back
4220
4221 When set to a true value, indicates that any rows fetched from joined has_many
4222 relationships are to be aggregated into the corresponding "parent" object. For
4223 example, the resultset:
4224
4225   my $rs = $schema->resultset('CD')->search({}, {
4226     '+columns' => [ qw/ tracks.title tracks.position / ],
4227     join => 'tracks',
4228     collapse => 1,
4229   });
4230
4231 While executing the following query:
4232
4233   SELECT me.*, tracks.title, tracks.position
4234     FROM cd me
4235     LEFT JOIN track tracks
4236       ON tracks.cdid = me.cdid
4237
4238 Will return only as many objects as there are rows in the CD source, even
4239 though the result of the query may span many rows. Each of these CD objects
4240 will in turn have multiple "Track" objects hidden behind the has_many
4241 generated accessor C<tracks>. Without C<< collapse => 1 >>, the return values
4242 of this resultset would be as many CD objects as there are tracks (a "Cartesian
4243 product"), with each CD object containing exactly one of all fetched Track data.
4244
4245 When a collapse is requested on a non-ordered resultset, an order by some
4246 unique part of the main source (the left-most table) is inserted automatically.
4247 This is done so that the resultset is allowed to be "lazy" - calling
4248 L<< $rs->next|/next >> will fetch only as many rows as it needs to build the next
4249 object with all of its related data.
4250
4251 If an L</order_by> is already declared, and orders the resultset in a way that
4252 makes collapsing as described above impossible (e.g. C<< ORDER BY
4253 has_many_rel.column >> or C<ORDER BY RANDOM()>), DBIC will automatically
4254 switch to "eager" mode and slurp the entire resultset before constructing the
4255 first object returned by L</next>.
4256
4257 Setting this attribute on a resultset that does not join any has_many
4258 relations is a no-op.
4259
4260 For a more in-depth discussion, see L</PREFETCHING>.
4261
4262 =head2 prefetch
4263
4264 =over 4
4265
4266 =item Value: ($rel_name | \@rel_names | \%rel_names)
4267
4268 =back
4269
4270 This attribute is a shorthand for specifying a L</join> spec, adding all
4271 columns from the joined related sources as L</+columns> and setting
4272 L</collapse> to a true value. For example, the following two queries are
4273 equivalent:
4274
4275   my $rs = $schema->resultset('Artist')->search({}, {
4276     prefetch => { cds => ['genre', 'tracks' ] },
4277   });
4278
4279 and
4280
4281   my $rs = $schema->resultset('Artist')->search({}, {
4282     join => { cds => ['genre', 'tracks' ] },
4283     collapse => 1,
4284     '+columns' => [
4285       (map
4286         { +{ "cds.$_" => "cds.$_" } }
4287         $schema->source('Artist')->related_source('cds')->columns
4288       ),
4289       (map
4290         { +{ "cds.genre.$_" => "genre.$_" } }
4291         $schema->source('Artist')->related_source('cds')->related_source('genre')->columns
4292       ),
4293       (map
4294         { +{ "cds.tracks.$_" => "tracks.$_" } }
4295         $schema->source('Artist')->related_source('cds')->related_source('tracks')->columns
4296       ),
4297     ],
4298   });
4299
4300 Both producing the following SQL:
4301
4302   SELECT  me.artistid, me.name, me.rank, me.charfield,
4303           cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track,
4304           genre.genreid, genre.name,
4305           tracks.trackid, tracks.cd, tracks.position, tracks.title, tracks.last_updated_on, tracks.last_updated_at
4306     FROM artist me
4307     LEFT JOIN cd cds
4308       ON cds.artist = me.artistid
4309     LEFT JOIN genre genre
4310       ON genre.genreid = cds.genreid
4311     LEFT JOIN track tracks
4312       ON tracks.cd = cds.cdid
4313   ORDER BY me.artistid
4314
4315 While L</prefetch> implies a L</join>, it is ok to mix the two together, as
4316 the arguments are properly merged and generally do the right thing. For
4317 example, you may want to do the following:
4318
4319   my $artists_and_cds_without_genre = $schema->resultset('Artist')->search(
4320     { 'genre.genreid' => undef },
4321     {
4322       join => { cds => 'genre' },
4323       prefetch => 'cds',
4324     }
4325   );
4326
4327 Which generates the following SQL:
4328
4329   SELECT  me.artistid, me.name, me.rank, me.charfield,
4330           cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track
4331     FROM artist me
4332     LEFT JOIN cd cds
4333       ON cds.artist = me.artistid
4334     LEFT JOIN genre genre
4335       ON genre.genreid = cds.genreid
4336   WHERE genre.genreid IS NULL
4337   ORDER BY me.artistid
4338
4339 For a more in-depth discussion, see L</PREFETCHING>.
4340
4341 =head2 alias
4342
4343 =over 4
4344
4345 =item Value: $source_alias
4346
4347 =back
4348
4349 Sets the source alias for the query.  Normally, this defaults to C<me>, but
4350 nested search queries (sub-SELECTs) might need specific aliases set to
4351 reference inner queries.  For example:
4352
4353    my $q = $rs
4354       ->related_resultset('CDs')
4355       ->related_resultset('Tracks')
4356       ->search({
4357          'track.id' => { -ident => 'none_search.id' },
4358       })
4359       ->as_query;
4360
4361    my $ids = $self->search({
4362       -not_exists => $q,
4363    }, {
4364       alias    => 'none_search',
4365       group_by => 'none_search.id',
4366    })->get_column('id')->as_query;
4367
4368    $self->search({ id => { -in => $ids } })
4369
4370 This attribute is directly tied to L</current_source_alias>.
4371
4372 =head2 page
4373
4374 =over 4
4375
4376 =item Value: $page
4377
4378 =back
4379
4380 Makes the resultset paged and specifies the page to retrieve. Effectively
4381 identical to creating a non-pages resultset and then calling ->page($page)
4382 on it.
4383
4384 If L</rows> attribute is not specified it defaults to 10 rows per page.
4385
4386 When you have a paged resultset, L</count> will only return the number
4387 of rows in the page. To get the total, use the L</pager> and call
4388 C<total_entries> on it.
4389
4390 =head2 rows
4391
4392 =over 4
4393
4394 =item Value: $rows
4395
4396 =back
4397
4398 Specifies the maximum number of rows for direct retrieval or the number of
4399 rows per page if the page attribute or method is used.
4400
4401 =head2 offset
4402
4403 =over 4
4404
4405 =item Value: $offset
4406
4407 =back
4408
4409 Specifies the (zero-based) row number for the  first row to be returned, or the
4410 of the first row of the first page if paging is used.
4411
4412 =head2 software_limit
4413
4414 =over 4
4415
4416 =item Value: (0 | 1)
4417
4418 =back
4419
4420 When combined with L</rows> and/or L</offset> the generated SQL will not
4421 include any limit dialect stanzas. Instead the entire result will be selected
4422 as if no limits were specified, and DBIC will perform the limit locally, by
4423 artificially advancing and finishing the resulting L</cursor>.
4424
4425 This is the recommended way of performing resultset limiting when no sane RDBMS
4426 implementation is available (e.g.
4427 L<Sybase ASE|DBIx::Class::Storage::DBI::Sybase::ASE> using the
4428 L<Generic Sub Query|DBIx::Class::SQLMaker::LimitDialects/GenericSubQ> hack)
4429
4430 =head2 group_by
4431
4432 =over 4
4433
4434 =item Value: \@columns
4435
4436 =back
4437
4438 A arrayref of columns to group by. Can include columns of joined tables.
4439
4440   group_by => [qw/ column1 column2 ... /]
4441
4442 =head2 having
4443
4444 =over 4
4445
4446 =item Value: $condition
4447
4448 =back
4449
4450 HAVING is a select statement attribute that is applied between GROUP BY and
4451 ORDER BY. It is applied to the after the grouping calculations have been
4452 done.
4453
4454   having => { 'count_employee' => { '>=', 100 } }
4455
4456 or with an in-place function in which case literal SQL is required:
4457
4458   having => \[ 'count(employee) >= ?', [ count => 100 ] ]
4459
4460 =head2 distinct
4461
4462 =over 4
4463
4464 =item Value: (0 | 1)
4465
4466 =back
4467
4468 Set to 1 to group by all columns. If the resultset already has a group_by
4469 attribute, this setting is ignored and an appropriate warning is issued.
4470
4471 =head2 where
4472
4473 =over 4
4474
4475 Adds to the WHERE clause.
4476
4477   # only return rows WHERE deleted IS NULL for all searches
4478   __PACKAGE__->resultset_attributes({ where => { deleted => undef } });
4479
4480 Can be overridden by passing C<< { where => undef } >> as an attribute
4481 to a resultset.
4482
4483 For more complicated where clauses see L<SQL::Abstract/WHERE CLAUSES>.
4484
4485 =back
4486
4487 =head2 cache
4488
4489 Set to 1 to cache search results. This prevents extra SQL queries if you
4490 revisit rows in your ResultSet:
4491
4492   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
4493
4494   while( my $artist = $resultset->next ) {
4495     ... do stuff ...
4496   }
4497
4498   $rs->first; # without cache, this would issue a query
4499
4500 By default, searches are not cached.
4501
4502 For more examples of using these attributes, see
4503 L<DBIx::Class::Manual::Cookbook>.
4504
4505 =head2 for
4506
4507 =over 4
4508
4509 =item Value: ( 'update' | 'shared' | \$scalar )
4510
4511 =back
4512
4513 Set to 'update' for a SELECT ... FOR UPDATE or 'shared' for a SELECT
4514 ... FOR SHARED. If \$scalar is passed, this is taken directly and embedded in the
4515 query.
4516
4517 =head1 PREFETCHING
4518
4519 DBIx::Class supports arbitrary related data prefetching from multiple related
4520 sources. Any combination of relationship types and column sets are supported.
4521 If L<collapsing|/collapse> is requested, there is an additional requirement of
4522 selecting enough data to make every individual object uniquely identifiable.
4523
4524 Here are some more involved examples, based on the following relationship map:
4525
4526   # Assuming:
4527   My::Schema::CD->belongs_to( artist      => 'My::Schema::Artist'     );
4528   My::Schema::CD->might_have( liner_note  => 'My::Schema::LinerNotes' );
4529   My::Schema::CD->has_many(   tracks      => 'My::Schema::Track'      );
4530
4531   My::Schema::Artist->belongs_to( record_label => 'My::Schema::RecordLabel' );
4532
4533   My::Schema::Track->has_many( guests => 'My::Schema::Guest' );
4534
4535
4536
4537   my $rs = $schema->resultset('Tag')->search(
4538     undef,
4539     {
4540       prefetch => {
4541         cd => 'artist'
4542       }
4543     }
4544   );
4545
4546 The initial search results in SQL like the following:
4547
4548   SELECT tag.*, cd.*, artist.* FROM tag
4549   JOIN cd ON tag.cd = cd.cdid
4550   JOIN artist ON cd.artist = artist.artistid
4551
4552 L<DBIx::Class> has no need to go back to the database when we access the
4553 C<cd> or C<artist> relationships, which saves us two SQL statements in this
4554 case.
4555
4556 Simple prefetches will be joined automatically, so there is no need
4557 for a C<join> attribute in the above search.
4558
4559 The L</prefetch> attribute can be used with any of the relationship types
4560 and multiple prefetches can be specified together. Below is a more complex
4561 example that prefetches a CD's artist, its liner notes (if present),
4562 the cover image, the tracks on that CD, and the guests on those
4563 tracks.
4564
4565   my $rs = $schema->resultset('CD')->search(
4566     undef,
4567     {
4568       prefetch => [
4569         { artist => 'record_label'},  # belongs_to => belongs_to
4570         'liner_note',                 # might_have
4571         'cover_image',                # has_one
4572         { tracks => 'guests' },       # has_many => has_many
4573       ]
4574     }
4575   );
4576
4577 This will produce SQL like the following:
4578
4579   SELECT cd.*, artist.*, record_label.*, liner_note.*, cover_image.*,
4580          tracks.*, guests.*
4581     FROM cd me
4582     JOIN artist artist
4583       ON artist.artistid = me.artistid
4584     JOIN record_label record_label
4585       ON record_label.labelid = artist.labelid
4586     LEFT JOIN track tracks
4587       ON tracks.cdid = me.cdid
4588     LEFT JOIN guest guests
4589       ON guests.trackid = track.trackid
4590     LEFT JOIN liner_notes liner_note
4591       ON liner_note.cdid = me.cdid
4592     JOIN cd_artwork cover_image
4593       ON cover_image.cdid = me.cdid
4594   ORDER BY tracks.cd
4595
4596 Now the C<artist>, C<record_label>, C<liner_note>, C<cover_image>,
4597 C<tracks>, and C<guests> of the CD will all be available through the
4598 relationship accessors without the need for additional queries to the
4599 database.
4600
4601 =head3 CAVEATS
4602
4603 Prefetch does a lot of deep magic. As such, it may not behave exactly
4604 as you might expect.
4605
4606 =over 4
4607
4608 =item *
4609
4610 Prefetch uses the L</cache> to populate the prefetched relationships. This
4611 may or may not be what you want.
4612
4613 =item *
4614
4615 If you specify a condition on a prefetched relationship, ONLY those
4616 rows that match the prefetched condition will be fetched into that relationship.
4617 This means that adding prefetch to a search() B<may alter> what is returned by
4618 traversing a relationship. So, if you have C<< Artist->has_many(CDs) >> and you do
4619
4620   my $artist_rs = $schema->resultset('Artist')->search({
4621       'cds.year' => 2008,
4622   }, {
4623       join => 'cds',
4624   });
4625
4626   my $count = $artist_rs->first->cds->count;
4627
4628   my $artist_rs_prefetch = $artist_rs->search( {}, { prefetch => 'cds' } );
4629
4630   my $prefetch_count = $artist_rs_prefetch->first->cds->count;
4631
4632   cmp_ok( $count, '==', $prefetch_count, "Counts should be the same" );
4633
4634 That cmp_ok() may or may not pass depending on the datasets involved. In other
4635 words the C<WHERE> condition would apply to the entire dataset, just like
4636 it would in regular SQL. If you want to add a condition only to the "right side"
4637 of a C<LEFT JOIN> - consider declaring and using a L<relationship with a custom
4638 condition|DBIx::Class::Relationship::Base/condition>
4639
4640 =back
4641
4642 =head1 DBIC BIND VALUES
4643
4644 Because DBIC may need more information to bind values than just the column name
4645 and value itself, it uses a special format for both passing and receiving bind
4646 values.  Each bind value should be composed of an arrayref of
4647 C<< [ \%args => $val ] >>.  The format of C<< \%args >> is currently:
4648
4649 =over 4
4650
4651 =item dbd_attrs
4652
4653 If present (in any form), this is what is being passed directly to bind_param.
4654 Note that different DBD's expect different bind args.  (e.g. DBD::SQLite takes
4655 a single numerical type, while DBD::Pg takes a hashref if bind options.)
4656
4657 If this is specified, all other bind options described below are ignored.
4658
4659 =item sqlt_datatype
4660
4661 If present, this is used to infer the actual bind attribute by passing to
4662 C<< $resolved_storage->bind_attribute_by_data_type() >>.  Defaults to the
4663 "data_type" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>.
4664
4665 Note that the data type is somewhat freeform (hence the sqlt_ prefix);
4666 currently drivers are expected to "Do the Right Thing" when given a common
4667 datatype name.  (Not ideal, but that's what we got at this point.)
4668
4669 =item sqlt_size
4670
4671 Currently used to correctly allocate buffers for bind_param_inout().
4672 Defaults to "size" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>,
4673 or to a sensible value based on the "data_type".
4674
4675 =item dbic_colname
4676
4677 Used to fill in missing sqlt_datatype and sqlt_size attributes (if they are
4678 explicitly specified they are never overridden).  Also used by some weird DBDs,
4679 where the column name should be available at bind_param time (e.g. Oracle).
4680
4681 =back
4682
4683 For backwards compatibility and convenience, the following shortcuts are
4684 supported:
4685
4686   [ $name => $val ] === [ { dbic_colname => $name }, $val ]
4687   [ \$dt  => $val ] === [ { sqlt_datatype => $dt }, $val ]
4688   [ undef,   $val ] === [ {}, $val ]
4689   $val              === [ {}, $val ]
4690
4691 =head1 AUTHOR AND CONTRIBUTORS
4692
4693 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
4694
4695 =head1 LICENSE
4696
4697 You may distribute this code under the same terms as Perl itself.
4698