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