lib/DBIx/Class/ResultSet.pm

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