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