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