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