lib/DBIx/Class/ResultSet.pm

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