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