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