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