lib/DBIx/Class/ResultSet.pm

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