lib/DBIx/Class/ResultSet.pm

   1 package DBIx::Class::ResultSet;
   2
   3 use strict;
   4 use warnings;
   5 use overload
   6         '0+'     => "count",
   7         'bool'   => "_bool",
   8         fallback => 1;
   9 use Carp::Clan qw/^DBIx::Class/;
  10 use Data::Page;
  11 use Storable;
  12 use DBIx::Class::ResultSetColumn;
  13 use DBIx::Class::ResultSourceHandle;
  14 use List::Util ();
  15 use Scalar::Util ();
  16 use base qw/DBIx::Class/;
  17
  18 __PACKAGE__->mk_group_accessors('simple' => qw/result_class _source_handle/);
  19
  20 =head1 NAME
  21
  22 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
  23
  24 =head1 SYNOPSIS
  25
  26   my $rs   = $schema->resultset('User')->search({ registered => 1 });
  27   my @rows = $schema->resultset('CD')->search({ year => 2005 })->all();
  28
  29 =head1 DESCRIPTION
  30
  31 The resultset is also known as an iterator. It is responsible for handling
  32 queries that may return an arbitrary number of rows, e.g. via L</search>
  33 or a C<has_many> relationship.
  34
  35 In the examples below, the following table classes are used:
  36
  37   package MyApp::Schema::Artist;
  38   use base qw/DBIx::Class/;
  39   __PACKAGE__->load_components(qw/Core/);
  40   __PACKAGE__->table('artist');
  41   __PACKAGE__->add_columns(qw/artistid name/);
  42   __PACKAGE__->set_primary_key('artistid');
  43   __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
  44   1;
  45
  46   package MyApp::Schema::CD;
  47   use base qw/DBIx::Class/;
  48   __PACKAGE__->load_components(qw/Core/);
  49   __PACKAGE__->table('cd');
  50   __PACKAGE__->add_columns(qw/cdid artist title year/);
  51   __PACKAGE__->set_primary_key('cdid');
  52   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
  53   1;
  54
  55 =head1 OVERLOADING
  56
  57 If a resultset is used in a numeric context it returns the L</count>.
  58 However, if it is used in a booleand context it is always true.  So if
  59 you want to check if a resultset has any results use C<if $rs != 0>.
  60 C<if $rs> will always be true.
  61
  62 =head1 METHODS
  63
  64 =head2 new
  65
  66 =over 4
  67
  68 =item Arguments: $source, \%$attrs
  69
  70 =item Return Value: $rs
  71
  72 =back
  73
  74 The resultset constructor. Takes a source object (usually a
  75 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
  76 L</ATTRIBUTES> below).  Does not perform any queries -- these are
  77 executed as needed by the other methods.
  78
  79 Generally you won't need to construct a resultset manually.  You'll
  80 automatically get one from e.g. a L</search> called in scalar context:
  81
  82   my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
  83
  84 IMPORTANT: If called on an object, proxies to new_result instead so
  85
  86   my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
  87
  88 will return a CD object, not a ResultSet.
  89
  90 =cut
  91
  92 sub new {
  93   my $class = shift;
  94   return $class->new_result(@_) if ref $class;
  95
  96   my ($source, $attrs) = @_;
  97   $source = $source->handle
  98     unless $source->isa('DBIx::Class::ResultSourceHandle');
  99   $attrs = { %{$attrs||{}} };
 100
 101   if ($attrs->{page}) {
 102     $attrs->{rows} ||= 10;
 103   }
 104
 105   $attrs->{alias} ||= 'me';
 106
 107   # Creation of {} and bless separated to mitigate RH perl bug
 108   # see https://bugzilla.redhat.com/show_bug.cgi?id=196836
 109   my $self = {
 110     _source_handle => $source,
 111     result_class => $attrs->{result_class} || $source->resolve->result_class,
 112     cond => $attrs->{where},
 113     count => undef,
 114     pager => undef,
 115     attrs => $attrs
 116   };
 117
 118   bless $self, $class;
 119
 120   return $self;
 121 }
 122
 123 =head2 search
 124
 125 =over 4
 126
 127 =item Arguments: $cond, \%attrs?
 128
 129 =item Return Value: $resultset (scalar context), @row_objs (list context)
 130
 131 =back
 132
 133   my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
 134   my $new_rs = $cd_rs->search({ year => 2005 });
 135
 136   my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
 137                  # year = 2005 OR year = 2004
 138
 139 If you need to pass in additional attributes but no additional condition,
 140 call it as C<search(undef, \%attrs)>.
 141
 142   # "SELECT name, artistid FROM $artist_table"
 143   my @all_artists = $schema->resultset('Artist')->search(undef, {
 144     columns => [qw/name artistid/],
 145   });
 146
 147 For a list of attributes that can be passed to C<search>, see
 148 L</ATTRIBUTES>. For more examples of using this function, see
 149 L<Searching|DBIx::Class::Manual::Cookbook/Searching>. For a complete
 150 documentation for the first argument, see L<SQL::Abstract>.
 151
 152 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
 153
 154 =cut
 155
 156 sub search {
 157   my $self = shift;
 158   my $rs = $self->search_rs( @_ );
 159   return (wantarray ? $rs->all : $rs);
 160 }
 161
 162 =head2 search_rs
 163
 164 =over 4
 165
 166 =item Arguments: $cond, \%attrs?
 167
 168 =item Return Value: $resultset
 169
 170 =back
 171
 172 This method does the same exact thing as search() except it will
 173 always return a resultset, even in list context.
 174
 175 =cut
 176
 177 sub search_rs {
 178   my $self = shift;
 179
 180   my $attrs = {};
 181   $attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
 182   my $our_attrs = { %{$self->{attrs}} };
 183   my $having = delete $our_attrs->{having};
 184   my $where = delete $our_attrs->{where};
 185
 186   my $rows;
 187
 188   my %safe = (alias => 1, cache => 1);
 189
 190   unless (
 191     (@_ && defined($_[0])) # @_ == () or (undef)
 192     ||
 193     (keys %$attrs # empty attrs or only 'safe' attrs
 194     && List::Util::first { !$safe{$_} } keys %$attrs)
 195   ) {
 196     # no search, effectively just a clone
 197     $rows = $self->get_cache;
 198   }
 199
 200   my $new_attrs = { %{$our_attrs}, %{$attrs} };
 201
 202   # merge new attrs into inherited
 203   foreach my $key (qw/join prefetch +select +as/) {
 204     next unless exists $attrs->{$key};
 205     $new_attrs->{$key} = $self->_merge_attr($our_attrs->{$key}, $attrs->{$key});
 206   }
 207
 208   my $cond = (@_
 209     ? (
 210         (@_ == 1 || ref $_[0] eq "HASH")
 211           ? (
 212               (ref $_[0] eq 'HASH')
 213                 ? (
 214                     (keys %{ $_[0] }  > 0)
 215                       ? shift
 216                       : undef
 217                    )
 218                 :  shift
 219              )
 220           : (
 221               (@_ % 2)
 222                 ? $self->throw_exception("Odd number of arguments to search")
 223                 : {@_}
 224              )
 225       )
 226     : undef
 227   );
 228
 229   if (defined $where) {
 230     $new_attrs->{where} = (
 231       defined $new_attrs->{where}
 232         ? { '-and' => [
 233               map {
 234                 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
 235               } $where, $new_attrs->{where}
 236             ]
 237           }
 238         : $where);
 239   }
 240
 241   if (defined $cond) {
 242     $new_attrs->{where} = (
 243       defined $new_attrs->{where}
 244         ? { '-and' => [
 245               map {
 246                 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
 247               } $cond, $new_attrs->{where}
 248             ]
 249           }
 250         : $cond);
 251   }
 252
 253   if (defined $having) {
 254     $new_attrs->{having} = (
 255       defined $new_attrs->{having}
 256         ? { '-and' => [
 257               map {
 258                 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
 259               } $having, $new_attrs->{having}
 260             ]
 261           }
 262         : $having);
 263   }
 264
 265   my $rs = (ref $self)->new($self->result_source, $new_attrs);
 266   if ($rows) {
 267     $rs->set_cache($rows);
 268   }
 269   return $rs;
 270 }
 271
 272 =head2 search_literal
 273
 274 =over 4
 275
 276 =item Arguments: $sql_fragment, @bind_values
 277
 278 =item Return Value: $resultset (scalar context), @row_objs (list context)
 279
 280 =back
 281
 282   my @cds   = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
 283   my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
 284
 285 Pass a literal chunk of SQL to be added to the conditional part of the
 286 resultset query.
 287
 288 CAVEAT: C<search_literal> is provided for Class::DBI compatibility and should
 289 only be used in that context. There are known problems using C<search_literal>
 290 in chained queries; it can result in bind values in the wrong order.  See
 291 L<DBIx::Class::Manual::Cookbook/Searching> and
 292 L<DBIx::Class::Manual::FAQ/Searching> for searching techniques that do not
 293 require C<search_literal>.
 294
 295 =cut
 296
 297 sub search_literal {
 298   my ($self, $cond, @vals) = @_;
 299   my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
 300   $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
 301   return $self->search(\$cond, $attrs);
 302 }
 303
 304 =head2 find
 305
 306 =over 4
 307
 308 =item Arguments: @values | \%cols, \%attrs?
 309
 310 =item Return Value: $row_object | undef
 311
 312 =back
 313
 314 Finds a row based on its primary key or unique constraint. For example, to find
 315 a row by its primary key:
 316
 317   my $cd = $schema->resultset('CD')->find(5);
 318
 319 You can also find a row by a specific unique constraint using the C<key>
 320 attribute. For example:
 321
 322   my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', {
 323     key => 'cd_artist_title'
 324   });
 325
 326 Additionally, you can specify the columns explicitly by name:
 327
 328   my $cd = $schema->resultset('CD')->find(
 329     {
 330       artist => 'Massive Attack',
 331       title  => 'Mezzanine',
 332     },
 333     { key => 'cd_artist_title' }
 334   );
 335
 336 If the C<key> is specified as C<primary>, it searches only on the primary key.
 337
 338 If no C<key> is specified, it searches on all unique constraints defined on the
 339 source for which column data is provided, including the primary key.
 340
 341 If your table does not have a primary key, you B<must> provide a value for the
 342 C<key> attribute matching one of the unique constraints on the source.
 343
 344 In addition to C<key>, L</find> recognizes and applies standard
 345 L<resultset attributes|/ATTRIBUTES> in the same way as L</search> does.
 346
 347 Note: If your query does not return only one row, a warning is generated:
 348
 349   Query returned more than one row
 350
 351 See also L</find_or_create> and L</update_or_create>. For information on how to
 352 declare unique constraints, see
 353 L<DBIx::Class::ResultSource/add_unique_constraint>.
 354
 355 =cut
 356
 357 sub find {
 358   my $self = shift;
 359   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 360
 361   # Default to the primary key, but allow a specific key
 362   my @cols = exists $attrs->{key}
 363     ? $self->result_source->unique_constraint_columns($attrs->{key})
 364     : $self->result_source->primary_columns;
 365   $self->throw_exception(
 366     "Can't find unless a primary key is defined or unique constraint is specified"
 367   ) unless @cols;
 368
 369   # Parse out a hashref from input
 370   my $input_query;
 371   if (ref $_[0] eq 'HASH') {
 372     $input_query = { %{$_[0]} };
 373   }
 374   elsif (@_ == @cols) {
 375     $input_query = {};
 376     @{$input_query}{@cols} = @_;
 377   }
 378   else {
 379     # Compatibility: Allow e.g. find(id => $value)
 380     carp "Find by key => value deprecated; please use a hashref instead";
 381     $input_query = {@_};
 382   }
 383
 384   my (%related, $info);
 385
 386   KEY: foreach my $key (keys %$input_query) {
 387     if (ref($input_query->{$key})
 388         && ($info = $self->result_source->relationship_info($key))) {
 389       my $val = delete $input_query->{$key};
 390       next KEY if (ref($val) eq 'ARRAY'); # has_many for multi_create
 391       my $rel_q = $self->result_source->resolve_condition(
 392                     $info->{cond}, $val, $key
 393                   );
 394       die "Can't handle OR join condition in find" if ref($rel_q) eq 'ARRAY';
 395       @related{keys %$rel_q} = values %$rel_q;
 396     }
 397   }
 398   if (my @keys = keys %related) {
 399     @{$input_query}{@keys} = values %related;
 400   }
 401
 402
 403   # Build the final query: Default to the disjunction of the unique queries,
 404   # but allow the input query in case the ResultSet defines the query or the
 405   # user is abusing find
 406   my $alias = exists $attrs->{alias} ? $attrs->{alias} : $self->{attrs}{alias};
 407   my $query;
 408   if (exists $attrs->{key}) {
 409     my @unique_cols = $self->result_source->unique_constraint_columns($attrs->{key});
 410     my $unique_query = $self->_build_unique_query($input_query, \@unique_cols);
 411     $query = $self->_add_alias($unique_query, $alias);
 412   }
 413   else {
 414     my @unique_queries = $self->_unique_queries($input_query, $attrs);
 415     $query = @unique_queries
 416       ? [ map { $self->_add_alias($_, $alias) } @unique_queries ]
 417       : $self->_add_alias($input_query, $alias);
 418   }
 419
 420   # Run the query
 421   if (keys %$attrs) {
 422     my $rs = $self->search($query, $attrs);
 423     if (keys %{$rs->_resolved_attrs->{collapse}}) {
 424       my $row = $rs->next;
 425       carp "Query returned more than one row" if $rs->next;
 426       return $row;
 427     }
 428     else {
 429       return $rs->single;
 430     }
 431   }
 432   else {
 433     if (keys %{$self->_resolved_attrs->{collapse}}) {
 434       my $rs = $self->search($query);
 435       my $row = $rs->next;
 436       carp "Query returned more than one row" if $rs->next;
 437       return $row;
 438     }
 439     else {
 440       return $self->single($query);
 441     }
 442   }
 443 }
 444
 445 # _add_alias
 446 #
 447 # Add the specified alias to the specified query hash. A copy is made so the
 448 # original query is not modified.
 449
 450 sub _add_alias {
 451   my ($self, $query, $alias) = @_;
 452
 453   my %aliased = %$query;
 454   foreach my $col (grep { ! m/\./ } keys %aliased) {
 455     $aliased{"$alias.$col"} = delete $aliased{$col};
 456   }
 457
 458   return \%aliased;
 459 }
 460
 461 # _unique_queries
 462 #
 463 # Build a list of queries which satisfy unique constraints.
 464
 465 sub _unique_queries {
 466   my ($self, $query, $attrs) = @_;
 467
 468   my @constraint_names = exists $attrs->{key}
 469     ? ($attrs->{key})
 470     : $self->result_source->unique_constraint_names;
 471
 472   my $where = $self->_collapse_cond($self->{attrs}{where} || {});
 473   my $num_where = scalar keys %$where;
 474
 475   my @unique_queries;
 476   foreach my $name (@constraint_names) {
 477     my @unique_cols = $self->result_source->unique_constraint_columns($name);
 478     my $unique_query = $self->_build_unique_query($query, \@unique_cols);
 479
 480     my $num_cols = scalar @unique_cols;
 481     my $num_query = scalar keys %$unique_query;
 482
 483     my $total = $num_query + $num_where;
 484     if ($num_query && ($num_query == $num_cols || $total == $num_cols)) {
 485       # The query is either unique on its own or is unique in combination with
 486       # the existing where clause
 487       push @unique_queries, $unique_query;
 488     }
 489   }
 490
 491   return @unique_queries;
 492 }
 493
 494 # _build_unique_query
 495 #
 496 # Constrain the specified query hash based on the specified column names.
 497
 498 sub _build_unique_query {
 499   my ($self, $query, $unique_cols) = @_;
 500
 501   return {
 502     map  { $_ => $query->{$_} }
 503     grep { exists $query->{$_} }
 504       @$unique_cols
 505   };
 506 }
 507
 508 =head2 search_related
 509
 510 =over 4
 511
 512 =item Arguments: $rel, $cond, \%attrs?
 513
 514 =item Return Value: $new_resultset
 515
 516 =back
 517
 518   $new_rs = $cd_rs->search_related('artist', {
 519     name => 'Emo-R-Us',
 520   });
 521
 522 Searches the specified relationship, optionally specifying a condition and
 523 attributes for matching records. See L</ATTRIBUTES> for more information.
 524
 525 =cut
 526
 527 sub search_related {
 528   return shift->related_resultset(shift)->search(@_);
 529 }
 530
 531 =head2 search_related_rs
 532
 533 This method works exactly the same as search_related, except that
 534 it guarantees a restultset, even in list context.
 535
 536 =cut
 537
 538 sub search_related_rs {
 539   return shift->related_resultset(shift)->search_rs(@_);
 540 }
 541
 542 =head2 cursor
 543
 544 =over 4
 545
 546 =item Arguments: none
 547
 548 =item Return Value: $cursor
 549
 550 =back
 551
 552 Returns a storage-driven cursor to the given resultset. See
 553 L<DBIx::Class::Cursor> for more information.
 554
 555 =cut
 556
 557 sub cursor {
 558   my ($self) = @_;
 559
 560   my $attrs = { %{$self->_resolved_attrs} };
 561   return $self->{cursor}
 562     ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
 563           $attrs->{where},$attrs);
 564 }
 565
 566 =head2 single
 567
 568 =over 4
 569
 570 =item Arguments: $cond?
 571
 572 =item Return Value: $row_object?
 573
 574 =back
 575
 576   my $cd = $schema->resultset('CD')->single({ year => 2001 });
 577
 578 Inflates the first result without creating a cursor if the resultset has
 579 any records in it; if not returns nothing. Used by L</find> as a lean version of
 580 L</search>.
 581
 582 While this method can take an optional search condition (just like L</search>)
 583 being a fast-code-path it does not recognize search attributes. If you need to
 584 add extra joins or similar, call L</search> and then chain-call L</single> on the
 585 L<DBIx::Class::ResultSet> returned.
 586
 587 =over
 588
 589 =item B<Note>
 590
 591 As of 0.08100, this method enforces the assumption that the preceeding
 592 query returns only one row. If more than one row is returned, you will receive
 593 a warning:
 594
 595   Query returned more than one row
 596
 597 In this case, you should be using L</first> or L</find> instead, or if you really
 598 know what you are doing, use the L</rows> attribute to explicitly limit the size
 599 of the resultset.
 600
 601 =back
 602
 603 =cut
 604
 605 sub single {
 606   my ($self, $where) = @_;
 607   my $attrs = { %{$self->_resolved_attrs} };
 608   if ($where) {
 609     if (defined $attrs->{where}) {
 610       $attrs->{where} = {
 611         '-and' =>
 612             [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
 613                $where, delete $attrs->{where} ]
 614       };
 615     } else {
 616       $attrs->{where} = $where;
 617     }
 618   }
 619
 620 #  XXX: Disabled since it doesn't infer uniqueness in all cases
 621 #  unless ($self->_is_unique_query($attrs->{where})) {
 622 #    carp "Query not guaranteed to return a single row"
 623 #      . "; please declare your unique constraints or use search instead";
 624 #  }
 625
 626   my @data = $self->result_source->storage->select_single(
 627     $attrs->{from}, $attrs->{select},
 628     $attrs->{where}, $attrs
 629   );
 630
 631   return (@data ? ($self->_construct_object(@data))[0] : undef);
 632 }
 633
 634 # _is_unique_query
 635 #
 636 # Try to determine if the specified query is guaranteed to be unique, based on
 637 # the declared unique constraints.
 638
 639 sub _is_unique_query {
 640   my ($self, $query) = @_;
 641
 642   my $collapsed = $self->_collapse_query($query);
 643   my $alias = $self->{attrs}{alias};
 644
 645   foreach my $name ($self->result_source->unique_constraint_names) {
 646     my @unique_cols = map {
 647       "$alias.$_"
 648     } $self->result_source->unique_constraint_columns($name);
 649
 650     # Count the values for each unique column
 651     my %seen = map { $_ => 0 } @unique_cols;
 652
 653     foreach my $key (keys %$collapsed) {
 654       my $aliased = $key =~ /\./ ? $key : "$alias.$key";
 655       next unless exists $seen{$aliased};  # Additional constraints are okay
 656       $seen{$aliased} = scalar keys %{ $collapsed->{$key} };
 657     }
 658
 659     # If we get 0 or more than 1 value for a column, it's not necessarily unique
 660     return 1 unless grep { $_ != 1 } values %seen;
 661   }
 662
 663   return 0;
 664 }
 665
 666 # _collapse_query
 667 #
 668 # Recursively collapse the query, accumulating values for each column.
 669
 670 sub _collapse_query {
 671   my ($self, $query, $collapsed) = @_;
 672
 673   $collapsed ||= {};
 674
 675   if (ref $query eq 'ARRAY') {
 676     foreach my $subquery (@$query) {
 677       next unless ref $subquery;  # -or
 678 #      warn "ARRAY: " . Dumper $subquery;
 679       $collapsed = $self->_collapse_query($subquery, $collapsed);
 680     }
 681   }
 682   elsif (ref $query eq 'HASH') {
 683     if (keys %$query and (keys %$query)[0] eq '-and') {
 684       foreach my $subquery (@{$query->{-and}}) {
 685 #        warn "HASH: " . Dumper $subquery;
 686         $collapsed = $self->_collapse_query($subquery, $collapsed);
 687       }
 688     }
 689     else {
 690 #      warn "LEAF: " . Dumper $query;
 691       foreach my $col (keys %$query) {
 692         my $value = $query->{$col};
 693         $collapsed->{$col}{$value}++;
 694       }
 695     }
 696   }
 697
 698   return $collapsed;
 699 }
 700
 701 =head2 get_column
 702
 703 =over 4
 704
 705 =item Arguments: $cond?
 706
 707 =item Return Value: $resultsetcolumn
 708
 709 =back
 710
 711   my $max_length = $rs->get_column('length')->max;
 712
 713 Returns a L<DBIx::Class::ResultSetColumn> instance for a column of the ResultSet.
 714
 715 =cut
 716
 717 sub get_column {
 718   my ($self, $column) = @_;
 719   my $new = DBIx::Class::ResultSetColumn->new($self, $column);
 720   return $new;
 721 }
 722
 723 =head2 search_like
 724
 725 =over 4
 726
 727 =item Arguments: $cond, \%attrs?
 728
 729 =item Return Value: $resultset (scalar context), @row_objs (list context)
 730
 731 =back
 732
 733   # WHERE title LIKE '%blue%'
 734   $cd_rs = $rs->search_like({ title => '%blue%'});
 735
 736 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
 737 that this is simply a convenience method. You most likely want to use
 738 L</search> with specific operators.
 739
 740 For more information, see L<DBIx::Class::Manual::Cookbook>.
 741
 742 =cut
 743
 744 sub search_like {
 745   my $class = shift;
 746   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 747   my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
 748   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
 749   return $class->search($query, { %$attrs });
 750 }
 751
 752 =head2 slice
 753
 754 =over 4
 755
 756 =item Arguments: $first, $last
 757
 758 =item Return Value: $resultset (scalar context), @row_objs (list context)
 759
 760 =back
 761
 762 Returns a resultset or object list representing a subset of elements from the
 763 resultset slice is called on. Indexes are from 0, i.e., to get the first
 764 three records, call:
 765
 766   my ($one, $two, $three) = $rs->slice(0, 2);
 767
 768 =cut
 769
 770 sub slice {
 771   my ($self, $min, $max) = @_;
 772   my $attrs = {}; # = { %{ $self->{attrs} || {} } };
 773   $attrs->{offset} = $self->{attrs}{offset} || 0;
 774   $attrs->{offset} += $min;
 775   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
 776   return $self->search(undef(), $attrs);
 777   #my $slice = (ref $self)->new($self->result_source, $attrs);
 778   #return (wantarray ? $slice->all : $slice);
 779 }
 780
 781 =head2 next
 782
 783 =over 4
 784
 785 =item Arguments: none
 786
 787 =item Return Value: $result?
 788
 789 =back
 790
 791 Returns the next element in the resultset (C<undef> is there is none).
 792
 793 Can be used to efficiently iterate over records in the resultset:
 794
 795   my $rs = $schema->resultset('CD')->search;
 796   while (my $cd = $rs->next) {
 797     print $cd->title;
 798   }
 799
 800 Note that you need to store the resultset object, and call C<next> on it.
 801 Calling C<< resultset('Table')->next >> repeatedly will always return the
 802 first record from the resultset.
 803
 804 =cut
 805
 806 sub next {
 807   my ($self) = @_;
 808   if (my $cache = $self->get_cache) {
 809     $self->{all_cache_position} ||= 0;
 810     return $cache->[$self->{all_cache_position}++];
 811   }
 812   if ($self->{attrs}{cache}) {
 813     $self->{all_cache_position} = 1;
 814     return ($self->all)[0];
 815   }
 816   if ($self->{stashed_objects}) {
 817     my $obj = shift(@{$self->{stashed_objects}});
 818     delete $self->{stashed_objects} unless @{$self->{stashed_objects}};
 819     return $obj;
 820   }
 821   my @row = (
 822     exists $self->{stashed_row}
 823       ? @{delete $self->{stashed_row}}
 824       : $self->cursor->next
 825   );
 826   return undef unless (@row);
 827   my ($row, @more) = $self->_construct_object(@row);
 828   $self->{stashed_objects} = \@more if @more;
 829   return $row;
 830 }
 831
 832 sub _construct_object {
 833   my ($self, @row) = @_;
 834   my $info = $self->_collapse_result($self->{_attrs}{as}, \@row);
 835   my @new = $self->result_class->inflate_result($self->result_source, @$info);
 836   @new = $self->{_attrs}{record_filter}->(@new)
 837     if exists $self->{_attrs}{record_filter};
 838   return @new;
 839 }
 840
 841 sub _collapse_result {
 842   my ($self, $as_proto, $row) = @_;
 843
 844   my @copy = @$row;
 845
 846   # 'foo'         => [ undef, 'foo' ]
 847   # 'foo.bar'     => [ 'foo', 'bar' ]
 848   # 'foo.bar.baz' => [ 'foo.bar', 'baz' ]
 849
 850   my @construct_as = map { [ (/^(?:(.*)\.)?([^.]+)$/) ] } @$as_proto;
 851
 852   my %collapse = %{$self->{_attrs}{collapse}||{}};
 853
 854   my @pri_index;
 855
 856   # if we're doing collapsing (has_many prefetch) we need to grab records
 857   # until the PK changes, so fill @pri_index. if not, we leave it empty so
 858   # we know we don't have to bother.
 859
 860   # the reason for not using the collapse stuff directly is because if you
 861   # had for e.g. two artists in a row with no cds, the collapse info for
 862   # both would be NULL (undef) so you'd lose the second artist
 863
 864   # store just the index so we can check the array positions from the row
 865   # without having to contruct the full hash
 866
 867   if (keys %collapse) {
 868     my %pri = map { ($_ => 1) } $self->result_source->primary_columns;
 869     foreach my $i (0 .. $#construct_as) {
 870       next if defined($construct_as[$i][0]); # only self table
 871       if (delete $pri{$construct_as[$i][1]}) {
 872         push(@pri_index, $i);
 873       }
 874       last unless keys %pri; # short circuit (Johnny Five Is Alive!)
 875     }
 876   }
 877
 878   # no need to do an if, it'll be empty if @pri_index is empty anyway
 879
 880   my %pri_vals = map { ($_ => $copy[$_]) } @pri_index;
 881
 882   my @const_rows;
 883
 884   do { # no need to check anything at the front, we always want the first row
 885
 886     my %const;
 887
 888     foreach my $this_as (@construct_as) {
 889       $const{$this_as->[0]||''}{$this_as->[1]} = shift(@copy);
 890     }
 891
 892     push(@const_rows, \%const);
 893
 894   } until ( # no pri_index => no collapse => drop straight out
 895       !@pri_index
 896     or
 897       do { # get another row, stash it, drop out if different PK
 898
 899         @copy = $self->cursor->next;
 900         $self->{stashed_row} = \@copy;
 901
 902         # last thing in do block, counts as true if anything doesn't match
 903
 904         # check xor defined first for NULL vs. NOT NULL then if one is
 905         # defined the other must be so check string equality
 906
 907         grep {
 908           (defined $pri_vals{$_} ^ defined $copy[$_])
 909           || (defined $pri_vals{$_} && ($pri_vals{$_} ne $copy[$_]))
 910         } @pri_index;
 911       }
 912   );
 913
 914   my $alias = $self->{attrs}{alias};
 915   my $info = [];
 916
 917   my %collapse_pos;
 918
 919   my @const_keys;
 920
 921   foreach my $const (@const_rows) {
 922     scalar @const_keys or do {
 923       @const_keys = sort { length($a) <=> length($b) } keys %$const;
 924     };
 925     foreach my $key (@const_keys) {
 926       if (length $key) {
 927         my $target = $info;
 928         my @parts = split(/\./, $key);
 929         my $cur = '';
 930         my $data = $const->{$key};
 931         foreach my $p (@parts) {
 932           $target = $target->[1]->{$p} ||= [];
 933           $cur .= ".${p}";
 934           if ($cur eq ".${key}" && (my @ckey = @{$collapse{$cur}||[]})) {
 935             # collapsing at this point and on final part
 936             my $pos = $collapse_pos{$cur};
 937             CK: foreach my $ck (@ckey) {
 938               if (!defined $pos->{$ck} || $pos->{$ck} ne $data->{$ck}) {
 939                 $collapse_pos{$cur} = $data;
 940                 delete @collapse_pos{ # clear all positioning for sub-entries
 941                   grep { m/^\Q${cur}.\E/ } keys %collapse_pos
 942                 };
 943                 push(@$target, []);
 944                 last CK;
 945               }
 946             }
 947           }
 948           if (exists $collapse{$cur}) {
 949             $target = $target->[-1];
 950           }
 951         }
 952         $target->[0] = $data;
 953       } else {
 954         $info->[0] = $const->{$key};
 955       }
 956     }
 957   }
 958
 959   return $info;
 960 }
 961
 962 =head2 result_source
 963
 964 =over 4
 965
 966 =item Arguments: $result_source?
 967
 968 =item Return Value: $result_source
 969
 970 =back
 971
 972 An accessor for the primary ResultSource object from which this ResultSet
 973 is derived.
 974
 975 =head2 result_class
 976
 977 =over 4
 978
 979 =item Arguments: $result_class?
 980
 981 =item Return Value: $result_class
 982
 983 =back
 984
 985 An accessor for the class to use when creating row objects. Defaults to
 986 C<< result_source->result_class >> - which in most cases is the name of the
 987 L<"table"|DBIx::Class::Manual::Glossary/"ResultSource"> class.
 988
 989 =cut
 990
 991
 992 =head2 count
 993
 994 =over 4
 995
 996 =item Arguments: $cond, \%attrs??
 997
 998 =item Return Value: $count
 999
1000 =back
1001
1002 Performs an SQL C<COUNT> with the same query as the resultset was built
1003 with to find the number of elements. If passed arguments, does a search
1004 on the resultset and counts the results of that.
1005
1006 Note: When using C<count> with C<group_by>, L<DBIx::Class> emulates C<GROUP BY>
1007 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
1008 not support C<DISTINCT> with multiple columns. If you are using such a
1009 database, you should only use columns from the main table in your C<group_by>
1010 clause.
1011
1012 =cut
1013
1014 sub count {
1015   my $self = shift;
1016   return $self->search(@_)->count if @_ and defined $_[0];
1017   return scalar @{ $self->get_cache } if $self->get_cache;
1018   my $count = $self->_count;
1019   return 0 unless $count;
1020
1021   # need to take offset from resolved attrs
1022
1023   $count -= $self->{_attrs}{offset} if $self->{_attrs}{offset};
1024   $count = $self->{attrs}{rows} if
1025     $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
1026   $count = 0 if ($count < 0);
1027   return $count;
1028 }
1029
1030 sub _count { # Separated out so pager can get the full count
1031   my $self = shift;
1032   my $select = { count => '*' };
1033
1034   my $attrs = { %{$self->_resolved_attrs} };
1035   if (my $group_by = delete $attrs->{group_by}) {
1036     delete $attrs->{having};
1037     my @distinct = (ref $group_by ?  @$group_by : ($group_by));
1038     # todo: try CONCAT for multi-column pk
1039     my @pk = $self->result_source->primary_columns;
1040     if (@pk == 1) {
1041       my $alias = $attrs->{alias};
1042       foreach my $column (@distinct) {
1043         if ($column =~ qr/^(?:\Q${alias}.\E)?$pk[0]$/) {
1044           @distinct = ($column);
1045           last;
1046         }
1047       }
1048     }
1049
1050     $select = { count => { distinct => \@distinct } };
1051   }
1052
1053   $attrs->{select} = $select;
1054   $attrs->{as} = [qw/count/];
1055
1056   # offset, order by and page are not needed to count. record_filter is cdbi
1057   delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
1058
1059   my $tmp_rs = (ref $self)->new($self->result_source, $attrs);
1060   my ($count) = $tmp_rs->cursor->next;
1061   return $count;
1062 }
1063
1064 sub _bool {
1065   return 1;
1066 }
1067
1068 =head2 count_literal
1069
1070 =over 4
1071
1072 =item Arguments: $sql_fragment, @bind_values
1073
1074 =item Return Value: $count
1075
1076 =back
1077
1078 Counts the results in a literal query. Equivalent to calling L</search_literal>
1079 with the passed arguments, then L</count>.
1080
1081 =cut
1082
1083 sub count_literal { shift->search_literal(@_)->count; }
1084
1085 =head2 all
1086
1087 =over 4
1088
1089 =item Arguments: none
1090
1091 =item Return Value: @objects
1092
1093 =back
1094
1095 Returns all elements in the resultset. Called implicitly if the resultset
1096 is returned in list context.
1097
1098 =cut
1099
1100 sub all {
1101   my ($self) = @_;
1102   return @{ $self->get_cache } if $self->get_cache;
1103
1104   my @obj;
1105
1106   # TODO: don't call resolve here
1107   if (keys %{$self->_resolved_attrs->{collapse}}) {
1108 #  if ($self->{attrs}{prefetch}) {
1109       # Using $self->cursor->all is really just an optimisation.
1110       # If we're collapsing has_many prefetches it probably makes
1111       # very little difference, and this is cleaner than hacking
1112       # _construct_object to survive the approach
1113     my @row = $self->cursor->next;
1114     while (@row) {
1115       push(@obj, $self->_construct_object(@row));
1116       @row = (exists $self->{stashed_row}
1117                ? @{delete $self->{stashed_row}}
1118                : $self->cursor->next);
1119     }
1120   } else {
1121     @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
1122   }
1123
1124   $self->set_cache(\@obj) if $self->{attrs}{cache};
1125   return @obj;
1126 }
1127
1128 =head2 reset
1129
1130 =over 4
1131
1132 =item Arguments: none
1133
1134 =item Return Value: $self
1135
1136 =back
1137
1138 Resets the resultset's cursor, so you can iterate through the elements again.
1139
1140 =cut
1141
1142 sub reset {
1143   my ($self) = @_;
1144   delete $self->{_attrs} if exists $self->{_attrs};
1145   $self->{all_cache_position} = 0;
1146   $self->cursor->reset;
1147   return $self;
1148 }
1149
1150 =head2 first
1151
1152 =over 4
1153
1154 =item Arguments: none
1155
1156 =item Return Value: $object?
1157
1158 =back
1159
1160 Resets the resultset and returns an object for the first result (if the
1161 resultset returns anything).
1162
1163 =cut
1164
1165 sub first {
1166   return $_[0]->reset->next;
1167 }
1168
1169 # _cond_for_update_delete
1170 #
1171 # update/delete require the condition to be modified to handle
1172 # the differing SQL syntax available.  This transforms the $self->{cond}
1173 # appropriately, returning the new condition.
1174
1175 sub _cond_for_update_delete {
1176   my ($self, $full_cond) = @_;
1177   my $cond = {};
1178
1179   $full_cond ||= $self->{cond};
1180   # No-op. No condition, we're updating/deleting everything
1181   return $cond unless ref $full_cond;
1182
1183   if (ref $full_cond eq 'ARRAY') {
1184     $cond = [
1185       map {
1186         my %hash;
1187         foreach my $key (keys %{$_}) {
1188           $key =~ /([^.]+)$/;
1189           $hash{$1} = $_->{$key};
1190         }
1191         \%hash;
1192       } @{$full_cond}
1193     ];
1194   }
1195   elsif (ref $full_cond eq 'HASH') {
1196     if ((keys %{$full_cond})[0] eq '-and') {
1197       $cond->{-and} = [];
1198
1199       my @cond = @{$full_cond->{-and}};
1200       for (my $i = 0; $i < @cond; $i++) {
1201         my $entry = $cond[$i];
1202
1203         my $hash;
1204         if (ref $entry eq 'HASH') {
1205           $hash = $self->_cond_for_update_delete($entry);
1206         }
1207         else {
1208           $entry =~ /([^.]+)$/;
1209           $hash->{$1} = $cond[++$i];
1210         }
1211
1212         push @{$cond->{-and}}, $hash;
1213       }
1214     }
1215     else {
1216       foreach my $key (keys %{$full_cond}) {
1217         $key =~ /([^.]+)$/;
1218         $cond->{$1} = $full_cond->{$key};
1219       }
1220     }
1221   }
1222   else {
1223     $self->throw_exception(
1224       "Can't update/delete on resultset with condition unless hash or array"
1225     );
1226   }
1227
1228   return $cond;
1229 }
1230
1231
1232 =head2 update
1233
1234 =over 4
1235
1236 =item Arguments: \%values
1237
1238 =item Return Value: $storage_rv
1239
1240 =back
1241
1242 Sets the specified columns in the resultset to the supplied values in a
1243 single query. Return value will be true if the update succeeded or false
1244 if no records were updated; exact type of success value is storage-dependent.
1245
1246 =cut
1247
1248 sub update {
1249   my ($self, $values) = @_;
1250   $self->throw_exception("Values for update must be a hash")
1251     unless ref $values eq 'HASH';
1252
1253   my $cond = $self->_cond_for_update_delete;
1254
1255   return $self->result_source->storage->update(
1256     $self->result_source, $values, $cond
1257   );
1258 }
1259
1260 =head2 update_all
1261
1262 =over 4
1263
1264 =item Arguments: \%values
1265
1266 =item Return Value: 1
1267
1268 =back
1269
1270 Fetches all objects and updates them one at a time. Note that C<update_all>
1271 will run DBIC cascade triggers, while L</update> will not.
1272
1273 =cut
1274
1275 sub update_all {
1276   my ($self, $values) = @_;
1277   $self->throw_exception("Values for update must be a hash")
1278     unless ref $values eq 'HASH';
1279   foreach my $obj ($self->all) {
1280     $obj->set_columns($values)->update;
1281   }
1282   return 1;
1283 }
1284
1285 =head2 delete
1286
1287 =over 4
1288
1289 =item Arguments: none
1290
1291 =item Return Value: 1
1292
1293 =back
1294
1295 Deletes the contents of the resultset from its result source. Note that this
1296 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1297 to run. See also L<DBIx::Class::Row/delete>.
1298
1299 delete may not generate correct SQL for a query with joins or a resultset
1300 chained from a related resultset.  In this case it will generate a warning:-
1301
1302   WARNING! Currently $rs->delete() does not generate proper SQL on
1303   joined resultsets, and may delete rows well outside of the contents
1304   of $rs. Use at your own risk
1305
1306 In these cases you may find that delete_all is more appropriate, or you
1307 need to respecify your query in a way that can be expressed without a join.
1308
1309 =cut
1310
1311 sub delete {
1312   my ($self) = @_;
1313   $self->throw_exception("Delete should not be passed any arguments")
1314     if $_[1];
1315   carp(   'WARNING! Currently $rs->delete() does not generate proper SQL'
1316         . ' on joined resultsets, and may delete rows well outside of the'
1317         . ' contents of $rs. Use at your own risk' )
1318     if ( $self->{attrs}{seen_join} );
1319   my $cond = $self->_cond_for_update_delete;
1320
1321   $self->result_source->storage->delete($self->result_source, $cond);
1322   return 1;
1323 }
1324
1325 =head2 delete_all
1326
1327 =over 4
1328
1329 =item Arguments: none
1330
1331 =item Return Value: 1
1332
1333 =back
1334
1335 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1336 will run DBIC cascade triggers, while L</delete> will not.
1337
1338 =cut
1339
1340 sub delete_all {
1341   my ($self) = @_;
1342   $_->delete for $self->all;
1343   return 1;
1344 }
1345
1346 =head2 populate
1347
1348 =over 4
1349
1350 =item Arguments: \@data;
1351
1352 =back
1353
1354 Pass an arrayref of hashrefs. Each hashref should be a structure suitable for
1355 submitting to a $resultset->create(...) method.
1356
1357 In void context, C<insert_bulk> in L<DBIx::Class::Storage::DBI> is used
1358 to insert the data, as this is a faster method.
1359
1360 Otherwise, each set of data is inserted into the database using
1361 L<DBIx::Class::ResultSet/create>, and a arrayref of the resulting row
1362 objects is returned.
1363
1364 Example:  Assuming an Artist Class that has many CDs Classes relating:
1365
1366   my $Artist_rs = $schema->resultset("Artist");
1367
1368   ## Void Context Example
1369   $Artist_rs->populate([
1370      { artistid => 4, name => 'Manufactured Crap', cds => [
1371         { title => 'My First CD', year => 2006 },
1372         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
1373       ],
1374      },
1375      { artistid => 5, name => 'Angsty-Whiny Girl', cds => [
1376         { title => 'My parents sold me to a record company' ,year => 2005 },
1377         { title => 'Why Am I So Ugly?', year => 2006 },
1378         { title => 'I Got Surgery and am now Popular', year => 2007 }
1379       ],
1380      },
1381   ]);
1382
1383   ## Array Context Example
1384   my ($ArtistOne, $ArtistTwo, $ArtistThree) = $Artist_rs->populate([
1385     { name => "Artist One"},
1386     { name => "Artist Two"},
1387     { name => "Artist Three", cds=> [
1388     { title => "First CD", year => 2007},
1389     { title => "Second CD", year => 2008},
1390   ]}
1391   ]);
1392
1393   print $ArtistOne->name; ## response is 'Artist One'
1394   print $ArtistThree->cds->count ## reponse is '2'
1395
1396 Please note an important effect on your data when choosing between void and
1397 wantarray context. Since void context goes straight to C<insert_bulk> in
1398 L<DBIx::Class::Storage::DBI> this will skip any component that is overriding
1399 c<insert>.  So if you are using something like L<DBIx-Class-UUIDColumns> to
1400 create primary keys for you, you will find that your PKs are empty.  In this
1401 case you will have to use the wantarray context in order to create those
1402 values.
1403
1404 =cut
1405
1406 sub populate {
1407   my ($self, $data) = @_;
1408
1409   if(defined wantarray) {
1410     my @created;
1411     foreach my $item (@$data) {
1412       push(@created, $self->create($item));
1413     }
1414     return @created;
1415   } else {
1416     my ($first, @rest) = @$data;
1417
1418     my @names = grep {!ref $first->{$_}} keys %$first;
1419     my @rels = grep { $self->result_source->has_relationship($_) } keys %$first;
1420     my @pks = $self->result_source->primary_columns;
1421
1422     ## do the belongs_to relationships
1423     foreach my $index (0..$#$data) {
1424       if( grep { !defined $data->[$index]->{$_} } @pks ) {
1425         my @ret = $self->populate($data);
1426         return;
1427       }
1428
1429       foreach my $rel (@rels) {
1430         next unless $data->[$index]->{$rel} && ref $data->[$index]->{$rel} eq "HASH";
1431         my $result = $self->related_resultset($rel)->create($data->[$index]->{$rel});
1432         my ($reverse) = keys %{$self->result_source->reverse_relationship_info($rel)};
1433         my $related = $result->result_source->resolve_condition(
1434           $result->result_source->relationship_info($reverse)->{cond},
1435           $self,
1436           $result,
1437         );
1438
1439         delete $data->[$index]->{$rel};
1440         $data->[$index] = {%{$data->[$index]}, %$related};
1441
1442         push @names, keys %$related if $index == 0;
1443       }
1444     }
1445
1446     ## do bulk insert on current row
1447     my @values = map { [ @$_{@names} ] } @$data;
1448
1449     $self->result_source->storage->insert_bulk(
1450       $self->result_source,
1451       \@names,
1452       \@values,
1453     );
1454
1455     ## do the has_many relationships
1456     foreach my $item (@$data) {
1457
1458       foreach my $rel (@rels) {
1459         next unless $item->{$rel} && ref $item->{$rel} eq "ARRAY";
1460
1461         my $parent = $self->find(map {{$_=>$item->{$_}} } @pks)
1462      || $self->throw_exception('Cannot find the relating object.');
1463
1464         my $child = $parent->$rel;
1465
1466         my $related = $child->result_source->resolve_condition(
1467           $parent->result_source->relationship_info($rel)->{cond},
1468           $child,
1469           $parent,
1470         );
1471
1472         my @rows_to_add = ref $item->{$rel} eq 'ARRAY' ? @{$item->{$rel}} : ($item->{$rel});
1473         my @populate = map { {%$_, %$related} } @rows_to_add;
1474
1475         $child->populate( \@populate );
1476       }
1477     }
1478   }
1479 }
1480
1481 =head2 pager
1482
1483 =over 4
1484
1485 =item Arguments: none
1486
1487 =item Return Value: $pager
1488
1489 =back
1490
1491 Return Value a L<Data::Page> object for the current resultset. Only makes
1492 sense for queries with a C<page> attribute.
1493
1494 =cut
1495
1496 sub pager {
1497   my ($self) = @_;
1498   my $attrs = $self->{attrs};
1499   $self->throw_exception("Can't create pager for non-paged rs")
1500     unless $self->{attrs}{page};
1501   $attrs->{rows} ||= 10;
1502   return $self->{pager} ||= Data::Page->new(
1503     $self->_count, $attrs->{rows}, $self->{attrs}{page});
1504 }
1505
1506 =head2 page
1507
1508 =over 4
1509
1510 =item Arguments: $page_number
1511
1512 =item Return Value: $rs
1513
1514 =back
1515
1516 Returns a resultset for the $page_number page of the resultset on which page
1517 is called, where each page contains a number of rows equal to the 'rows'
1518 attribute set on the resultset (10 by default).
1519
1520 =cut
1521
1522 sub page {
1523   my ($self, $page) = @_;
1524   return (ref $self)->new($self->result_source, { %{$self->{attrs}}, page => $page });
1525 }
1526
1527 =head2 new_result
1528
1529 =over 4
1530
1531 =item Arguments: \%vals
1532
1533 =item Return Value: $rowobject
1534
1535 =back
1536
1537 Creates a new row object in the resultset's result class and returns
1538 it. The row is not inserted into the database at this point, call
1539 L<DBIx::Class::Row/insert> to do that. Calling L<DBIx::Class::Row/in_storage>
1540 will tell you whether the row object has been inserted or not.
1541
1542 Passes the hashref of input on to L<DBIx::Class::Row/new>.
1543
1544 =cut
1545
1546 sub new_result {
1547   my ($self, $values) = @_;
1548   $self->throw_exception( "new_result needs a hash" )
1549     unless (ref $values eq 'HASH');
1550
1551   my %new;
1552   my $alias = $self->{attrs}{alias};
1553
1554   if (
1555     defined $self->{cond}
1556     && $self->{cond} eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION
1557   ) {
1558     %new = %{$self->{attrs}{related_objects}};
1559   } else {
1560     $self->throw_exception(
1561       "Can't abstract implicit construct, condition not a hash"
1562     ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1563
1564     my $collapsed_cond = (
1565       $self->{cond}
1566         ? $self->_collapse_cond($self->{cond})
1567         : {}
1568     );
1569
1570     # precendence must be given to passed values over values inherited from
1571     # the cond, so the order here is important.
1572     my %implied =  %{$self->_remove_alias($collapsed_cond, $alias)};
1573     while( my($col,$value) = each %implied ){
1574       if(ref($value) eq 'HASH' && keys(%$value) && (keys %$value)[0] eq '='){
1575         $new{$col} = $value->{'='};
1576         next;
1577       }
1578       $new{$col} = $value if $self->_is_deterministic_value($value);
1579     }
1580   }
1581
1582   %new = (
1583     %new,
1584     %{ $self->_remove_alias($values, $alias) },
1585     -source_handle => $self->_source_handle,
1586     -result_source => $self->result_source, # DO NOT REMOVE THIS, REQUIRED
1587   );
1588
1589   return $self->result_class->new(\%new);
1590 }
1591
1592 # _is_deterministic_value
1593 #
1594 # Make an effor to strip non-deterministic values from the condition,
1595 # to make sure new_result chokes less
1596
1597 sub _is_deterministic_value {
1598   my $self = shift;
1599   my $value = shift;
1600   my $ref_type = ref $value;
1601   return 1 if $ref_type eq '' || $ref_type eq 'SCALAR';
1602   return 1 if Scalar::Util::blessed($value);
1603   return 0;
1604 }
1605
1606 # _collapse_cond
1607 #
1608 # Recursively collapse the condition.
1609
1610 sub _collapse_cond {
1611   my ($self, $cond, $collapsed) = @_;
1612
1613   $collapsed ||= {};
1614
1615   if (ref $cond eq 'ARRAY') {
1616     foreach my $subcond (@$cond) {
1617       next unless ref $subcond;  # -or
1618 #      warn "ARRAY: " . Dumper $subcond;
1619       $collapsed = $self->_collapse_cond($subcond, $collapsed);
1620     }
1621   }
1622   elsif (ref $cond eq 'HASH') {
1623     if (keys %$cond and (keys %$cond)[0] eq '-and') {
1624       foreach my $subcond (@{$cond->{-and}}) {
1625 #        warn "HASH: " . Dumper $subcond;
1626         $collapsed = $self->_collapse_cond($subcond, $collapsed);
1627       }
1628     }
1629     else {
1630 #      warn "LEAF: " . Dumper $cond;
1631       foreach my $col (keys %$cond) {
1632         my $value = $cond->{$col};
1633         $collapsed->{$col} = $value;
1634       }
1635     }
1636   }
1637
1638   return $collapsed;
1639 }
1640
1641 # _remove_alias
1642 #
1643 # Remove the specified alias from the specified query hash. A copy is made so
1644 # the original query is not modified.
1645
1646 sub _remove_alias {
1647   my ($self, $query, $alias) = @_;
1648
1649   my %orig = %{ $query || {} };
1650   my %unaliased;
1651
1652   foreach my $key (keys %orig) {
1653     if ($key !~ /\./) {
1654       $unaliased{$key} = $orig{$key};
1655       next;
1656     }
1657     $unaliased{$1} = $orig{$key}
1658       if $key =~ m/^(?:\Q$alias\E\.)?([^.]+)$/;
1659   }
1660
1661   return \%unaliased;
1662 }
1663
1664 =head2 find_or_new
1665
1666 =over 4
1667
1668 =item Arguments: \%vals, \%attrs?
1669
1670 =item Return Value: $rowobject
1671
1672 =back
1673
1674   my $artist = $schema->resultset('Artist')->find_or_new(
1675     { artist => 'fred' }, { key => 'artists' });
1676
1677   $cd->cd_to_producer->find_or_new({ producer => $producer },
1678                                    { key => 'primary });
1679
1680 Find an existing record from this resultset, based on it's primary
1681 key, or a unique constraint. If none exists, instantiate a new result
1682 object and return it. The object will not be saved into your storage
1683 until you call L<DBIx::Class::Row/insert> on it.
1684
1685 You most likely want this method when looking for existing rows using
1686 a unique constraint that is not the primary key, or looking for
1687 related rows.
1688
1689 If you want objects to be saved immediately, use L</find_or_create> instead.
1690
1691 B<Note>: C<find_or_new> is probably not what you want when creating a
1692 new row in a table that uses primary keys supplied by the
1693 database. Passing in a primary key column with a value of I<undef>
1694 will cause L</find> to attempt to search for a row with a value of
1695 I<NULL>.
1696
1697 =cut
1698
1699 sub find_or_new {
1700   my $self     = shift;
1701   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1702   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1703   my $exists   = $self->find($hash, $attrs);
1704   return defined $exists ? $exists : $self->new_result($hash);
1705 }
1706
1707 =head2 create
1708
1709 =over 4
1710
1711 =item Arguments: \%vals
1712
1713 =item Return Value: a L<DBIx::Class::Row> $object
1714
1715 =back
1716
1717 Attempt to create a single new row or a row with multiple related rows
1718 in the table represented by the resultset (and related tables). This
1719 will not check for duplicate rows before inserting, use
1720 L</find_or_create> to do that.
1721
1722 To create one row for this resultset, pass a hashref of key/value
1723 pairs representing the columns of the table and the values you wish to
1724 store. If the appropriate relationships are set up, foreign key fields
1725 can also be passed an object representing the foreign row, and the
1726 value will be set to it's primary key.
1727
1728 To create related objects, pass a hashref for the value if the related
1729 item is a foreign key relationship (L<DBIx::Class::Relationship/belongs_to>),
1730 and use the name of the relationship as the key. (NOT the name of the field,
1731 necessarily). For C<has_many> and C<has_one> relationships, pass an arrayref
1732 of hashrefs containing the data for each of the rows to create in the foreign
1733 tables, again using the relationship name as the key.
1734
1735 Instead of hashrefs of plain related data (key/value pairs), you may
1736 also pass new or inserted objects. New objects (not inserted yet, see
1737 L</new>), will be inserted into their appropriate tables.
1738
1739 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1740
1741 Example of creating a new row.
1742
1743   $person_rs->create({
1744     name=>"Some Person",
1745         email=>"somebody@someplace.com"
1746   });
1747
1748 Example of creating a new row and also creating rows in a related C<has_many>
1749 or C<has_one> resultset.  Note Arrayref.
1750
1751   $artist_rs->create(
1752      { artistid => 4, name => 'Manufactured Crap', cds => [
1753         { title => 'My First CD', year => 2006 },
1754         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
1755       ],
1756      },
1757   );
1758
1759 Example of creating a new row and also creating a row in a related
1760 C<belongs_to>resultset. Note Hashref.
1761
1762   $cd_rs->create({
1763     title=>"Music for Silly Walks",
1764         year=>2000,
1765         artist => {
1766           name=>"Silly Musician",
1767         }
1768   });
1769
1770 =cut
1771
1772 sub create {
1773   my ($self, $attrs) = @_;
1774   $self->throw_exception( "create needs a hashref" )
1775     unless ref $attrs eq 'HASH';
1776   return $self->new_result($attrs)->insert;
1777 }
1778
1779 =head2 find_or_create
1780
1781 =over 4
1782
1783 =item Arguments: \%vals, \%attrs?
1784
1785 =item Return Value: $rowobject
1786
1787 =back
1788
1789   $cd->cd_to_producer->find_or_create({ producer => $producer },
1790                                       { key => 'primary });
1791
1792 Tries to find a record based on its primary key or unique constraints; if none
1793 is found, creates one and returns that instead.
1794
1795   my $cd = $schema->resultset('CD')->find_or_create({
1796     cdid   => 5,
1797     artist => 'Massive Attack',
1798     title  => 'Mezzanine',
1799     year   => 2005,
1800   });
1801
1802 Also takes an optional C<key> attribute, to search by a specific key or unique
1803 constraint. For example:
1804
1805   my $cd = $schema->resultset('CD')->find_or_create(
1806     {
1807       artist => 'Massive Attack',
1808       title  => 'Mezzanine',
1809     },
1810     { key => 'cd_artist_title' }
1811   );
1812
1813 B<Note>: Because find_or_create() reads from the database and then
1814 possibly inserts based on the result, this method is subject to a race
1815 condition. Another process could create a record in the table after
1816 the find has completed and before the create has started. To avoid
1817 this problem, use find_or_create() inside a transaction.
1818
1819 B<Note>: C<find_or_create> is probably not what you want when creating
1820 a new row in a table that uses primary keys supplied by the
1821 database. Passing in a primary key column with a value of I<undef>
1822 will cause L</find> to attempt to search for a row with a value of
1823 I<NULL>.
1824
1825 See also L</find> and L</update_or_create>. For information on how to declare
1826 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1827
1828 =cut
1829
1830 sub find_or_create {
1831   my $self     = shift;
1832   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1833   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1834   my $exists   = $self->find($hash, $attrs);
1835   return defined $exists ? $exists : $self->create($hash);
1836 }
1837
1838 =head2 update_or_create
1839
1840 =over 4
1841
1842 =item Arguments: \%col_values, { key => $unique_constraint }?
1843
1844 =item Return Value: $rowobject
1845
1846 =back
1847
1848   $resultset->update_or_create({ col => $val, ... });
1849
1850 First, searches for an existing row matching one of the unique constraints
1851 (including the primary key) on the source of this resultset. If a row is
1852 found, updates it with the other given column values. Otherwise, creates a new
1853 row.
1854
1855 Takes an optional C<key> attribute to search on a specific unique constraint.
1856 For example:
1857
1858   # In your application
1859   my $cd = $schema->resultset('CD')->update_or_create(
1860     {
1861       artist => 'Massive Attack',
1862       title  => 'Mezzanine',
1863       year   => 1998,
1864     },
1865     { key => 'cd_artist_title' }
1866   );
1867
1868   $cd->cd_to_producer->update_or_create({
1869     producer => $producer,
1870     name => 'harry',
1871   }, {
1872     key => 'primary,
1873   });
1874
1875
1876 If no C<key> is specified, it searches on all unique constraints defined on the
1877 source, including the primary key.
1878
1879 If the C<key> is specified as C<primary>, it searches only on the primary key.
1880
1881 See also L</find> and L</find_or_create>. For information on how to declare
1882 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1883
1884 B<Note>: C<update_or_create> is probably not what you want when
1885 looking for a row in a table that uses primary keys supplied by the
1886 database, unless you actually have a key value. Passing in a primary
1887 key column with a value of I<undef> will cause L</find> to attempt to
1888 search for a row with a value of I<NULL>.
1889
1890 =cut
1891
1892 sub update_or_create {
1893   my $self = shift;
1894   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1895   my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
1896
1897   my $row = $self->find($cond, $attrs);
1898   if (defined $row) {
1899     $row->update($cond);
1900     return $row;
1901   }
1902
1903   return $self->create($cond);
1904 }
1905
1906 =head2 get_cache
1907
1908 =over 4
1909
1910 =item Arguments: none
1911
1912 =item Return Value: \@cache_objects?
1913
1914 =back
1915
1916 Gets the contents of the cache for the resultset, if the cache is set.
1917
1918 The cache is populated either by using the L</prefetch> attribute to
1919 L</search> or by calling L</set_cache>.
1920
1921 =cut
1922
1923 sub get_cache {
1924   shift->{all_cache};
1925 }
1926
1927 =head2 set_cache
1928
1929 =over 4
1930
1931 =item Arguments: \@cache_objects
1932
1933 =item Return Value: \@cache_objects
1934
1935 =back
1936
1937 Sets the contents of the cache for the resultset. Expects an arrayref
1938 of objects of the same class as those produced by the resultset. Note that
1939 if the cache is set the resultset will return the cached objects rather
1940 than re-querying the database even if the cache attr is not set.
1941
1942 The contents of the cache can also be populated by using the
1943 L</prefetch> attribute to L</search>.
1944
1945 =cut
1946
1947 sub set_cache {
1948   my ( $self, $data ) = @_;
1949   $self->throw_exception("set_cache requires an arrayref")
1950       if defined($data) && (ref $data ne 'ARRAY');
1951   $self->{all_cache} = $data;
1952 }
1953
1954 =head2 clear_cache
1955
1956 =over 4
1957
1958 =item Arguments: none
1959
1960 =item Return Value: []
1961
1962 =back
1963
1964 Clears the cache for the resultset.
1965
1966 =cut
1967
1968 sub clear_cache {
1969   shift->set_cache(undef);
1970 }
1971
1972 =head2 related_resultset
1973
1974 =over 4
1975
1976 =item Arguments: $relationship_name
1977
1978 =item Return Value: $resultset
1979
1980 =back
1981
1982 Returns a related resultset for the supplied relationship name.
1983
1984   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1985
1986 =cut
1987
1988 sub related_resultset {
1989   my ($self, $rel) = @_;
1990
1991   $self->{related_resultsets} ||= {};
1992   return $self->{related_resultsets}{$rel} ||= do {
1993     my $rel_obj = $self->result_source->relationship_info($rel);
1994
1995     $self->throw_exception(
1996       "search_related: result source '" . $self->result_source->source_name .
1997         "' has no such relationship $rel")
1998       unless $rel_obj;
1999
2000     my ($from,$seen) = $self->_resolve_from($rel);
2001
2002     my $join_count = $seen->{$rel};
2003     my $alias = ($join_count > 1 ? join('_', $rel, $join_count) : $rel);
2004
2005     #XXX - temp fix for result_class bug. There likely is a more elegant fix -groditi
2006     my %attrs = %{$self->{attrs}||{}};
2007     delete @attrs{qw(result_class alias)};
2008
2009     my $new_cache;
2010
2011     if (my $cache = $self->get_cache) {
2012       if ($cache->[0] && $cache->[0]->related_resultset($rel)->get_cache) {
2013         $new_cache = [ map { @{$_->related_resultset($rel)->get_cache} }
2014                         @$cache ];
2015       }
2016     }
2017
2018     my $rel_source = $self->result_source->related_source($rel);
2019
2020     my $new = do {
2021
2022       # The reason we do this now instead of passing the alias to the
2023       # search_rs below is that if you wrap/overload resultset on the
2024       # source you need to know what alias it's -going- to have for things
2025       # to work sanely (e.g. RestrictWithObject wants to be able to add
2026       # extra query restrictions, and these may need to be $alias.)
2027
2028       my $attrs = $rel_source->resultset_attributes;
2029       local $attrs->{alias} = $alias;
2030
2031       $rel_source->resultset
2032                  ->search_rs(
2033                      undef, {
2034                        %attrs,
2035                        join => undef,
2036                        prefetch => undef,
2037                        select => undef,
2038                        as => undef,
2039                        where => $self->{cond},
2040                        seen_join => $seen,
2041                        from => $from,
2042                    });
2043     };
2044     $new->set_cache($new_cache) if $new_cache;
2045     $new;
2046   };
2047 }
2048
2049 sub _resolve_from {
2050   my ($self, $extra_join) = @_;
2051   my $source = $self->result_source;
2052   my $attrs = $self->{attrs};
2053
2054   my $from = $attrs->{from}
2055     || [ { $attrs->{alias} => $source->from } ];
2056
2057   my $seen = { %{$attrs->{seen_join}||{}} };
2058
2059   my $join = ($attrs->{join}
2060                ? [ $attrs->{join}, $extra_join ]
2061                : $extra_join);
2062
2063   # we need to take the prefetch the attrs into account before we
2064   # ->resolve_join as otherwise they get lost - captainL
2065   my $merged = $self->_merge_attr( $join, $attrs->{prefetch} );
2066
2067   $from = [
2068     @$from,
2069     ($join ? $source->resolve_join($merged, $attrs->{alias}, $seen) : ()),
2070   ];
2071
2072   return ($from,$seen);
2073 }
2074
2075 sub _resolved_attrs {
2076   my $self = shift;
2077   return $self->{_attrs} if $self->{_attrs};
2078
2079   my $attrs = { %{$self->{attrs}||{}} };
2080   my $source = $self->result_source;
2081   my $alias = $attrs->{alias};
2082
2083   $attrs->{columns} ||= delete $attrs->{cols} if exists $attrs->{cols};
2084   if ($attrs->{columns}) {
2085     delete $attrs->{as};
2086   } elsif (!$attrs->{select}) {
2087     $attrs->{columns} = [ $source->columns ];
2088   }
2089
2090   $attrs->{select} =
2091     ($attrs->{select}
2092       ? (ref $attrs->{select} eq 'ARRAY'
2093           ? [ @{$attrs->{select}} ]
2094           : [ $attrs->{select} ])
2095       : [ map { m/\./ ? $_ : "${alias}.$_" } @{delete $attrs->{columns}} ]
2096     );
2097   $attrs->{as} =
2098     ($attrs->{as}
2099       ? (ref $attrs->{as} eq 'ARRAY'
2100           ? [ @{$attrs->{as}} ]
2101           : [ $attrs->{as} ])
2102       : [ map { m/^\Q${alias}.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}} ]
2103     );
2104
2105   my $adds;
2106   if ($adds = delete $attrs->{include_columns}) {
2107     $adds = [$adds] unless ref $adds eq 'ARRAY';
2108     push(@{$attrs->{select}}, @$adds);
2109     push(@{$attrs->{as}}, map { m/([^.]+)$/; $1 } @$adds);
2110   }
2111   if ($adds = delete $attrs->{'+select'}) {
2112     $adds = [$adds] unless ref $adds eq 'ARRAY';
2113     push(@{$attrs->{select}},
2114            map { /\./ || ref $_ ? $_ : "${alias}.$_" } @$adds);
2115   }
2116   if (my $adds = delete $attrs->{'+as'}) {
2117     $adds = [$adds] unless ref $adds eq 'ARRAY';
2118     push(@{$attrs->{as}}, @$adds);
2119   }
2120
2121   $attrs->{from} ||= [ { 'me' => $source->from } ];
2122
2123   if (exists $attrs->{join} || exists $attrs->{prefetch}) {
2124     my $join = delete $attrs->{join} || {};
2125
2126     if (defined $attrs->{prefetch}) {
2127       $join = $self->_merge_attr(
2128         $join, $attrs->{prefetch}
2129       );
2130
2131     }
2132
2133     $attrs->{from} =   # have to copy here to avoid corrupting the original
2134       [
2135         @{$attrs->{from}},
2136         $source->resolve_join($join, $alias, { %{$attrs->{seen_join}||{}} })
2137       ];
2138
2139   }
2140
2141   $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
2142   if ($attrs->{order_by}) {
2143     $attrs->{order_by} = (ref($attrs->{order_by}) eq 'ARRAY'
2144                            ? [ @{$attrs->{order_by}} ]
2145                            : [ $attrs->{order_by} ]);
2146   } else {
2147     $attrs->{order_by} = [];
2148   }
2149
2150   my $collapse = $attrs->{collapse} || {};
2151   if (my $prefetch = delete $attrs->{prefetch}) {
2152     $prefetch = $self->_merge_attr({}, $prefetch);
2153     my @pre_order;
2154     my $seen = $attrs->{seen_join} || {};
2155     foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
2156       # bring joins back to level of current class
2157       my @prefetch = $source->resolve_prefetch(
2158         $p, $alias, $seen, \@pre_order, $collapse
2159       );
2160       push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
2161       push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
2162     }
2163     push(@{$attrs->{order_by}}, @pre_order);
2164   }
2165   $attrs->{collapse} = $collapse;
2166
2167   if ($attrs->{page}) {
2168     $attrs->{offset} ||= 0;
2169     $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
2170   }
2171
2172   return $self->{_attrs} = $attrs;
2173 }
2174
2175 sub _rollout_attr {
2176   my ($self, $attr) = @_;
2177
2178   if (ref $attr eq 'HASH') {
2179     return $self->_rollout_hash($attr);
2180   } elsif (ref $attr eq 'ARRAY') {
2181     return $self->_rollout_array($attr);
2182   } else {
2183     return [$attr];
2184   }
2185 }
2186
2187 sub _rollout_array {
2188   my ($self, $attr) = @_;
2189
2190   my @rolled_array;
2191   foreach my $element (@{$attr}) {
2192     if (ref $element eq 'HASH') {
2193       push( @rolled_array, @{ $self->_rollout_hash( $element ) } );
2194     } elsif (ref $element eq 'ARRAY') {
2195       #  XXX - should probably recurse here
2196       push( @rolled_array, @{$self->_rollout_array($element)} );
2197     } else {
2198       push( @rolled_array, $element );
2199     }
2200   }
2201   return \@rolled_array;
2202 }
2203
2204 sub _rollout_hash {
2205   my ($self, $attr) = @_;
2206
2207   my @rolled_array;
2208   foreach my $key (keys %{$attr}) {
2209     push( @rolled_array, { $key => $attr->{$key} } );
2210   }
2211   return \@rolled_array;
2212 }
2213
2214 sub _calculate_score {
2215   my ($self, $a, $b) = @_;
2216
2217   if (ref $b eq 'HASH') {
2218     my ($b_key) = keys %{$b};
2219     if (ref $a eq 'HASH') {
2220       my ($a_key) = keys %{$a};
2221       if ($a_key eq $b_key) {
2222         return (1 + $self->_calculate_score( $a->{$a_key}, $b->{$b_key} ));
2223       } else {
2224         return 0;
2225       }
2226     } else {
2227       return ($a eq $b_key) ? 1 : 0;
2228     }
2229   } else {
2230     if (ref $a eq 'HASH') {
2231       my ($a_key) = keys %{$a};
2232       return ($b eq $a_key) ? 1 : 0;
2233     } else {
2234       return ($b eq $a) ? 1 : 0;
2235     }
2236   }
2237 }
2238
2239 sub _merge_attr {
2240   my ($self, $orig, $import) = @_;
2241
2242   return $import unless defined($orig);
2243   return $orig unless defined($import);
2244
2245   $orig = $self->_rollout_attr($orig);
2246   $import = $self->_rollout_attr($import);
2247
2248   my $seen_keys;
2249   foreach my $import_element ( @{$import} ) {
2250     # find best candidate from $orig to merge $b_element into
2251     my $best_candidate = { position => undef, score => 0 }; my $position = 0;
2252     foreach my $orig_element ( @{$orig} ) {
2253       my $score = $self->_calculate_score( $orig_element, $import_element );
2254       if ($score > $best_candidate->{score}) {
2255         $best_candidate->{position} = $position;
2256         $best_candidate->{score} = $score;
2257       }
2258       $position++;
2259     }
2260     my ($import_key) = ( ref $import_element eq 'HASH' ) ? keys %{$import_element} : ($import_element);
2261
2262     if ($best_candidate->{score} == 0 || exists $seen_keys->{$import_key}) {
2263       push( @{$orig}, $import_element );
2264     } else {
2265       my $orig_best = $orig->[$best_candidate->{position}];
2266       # merge orig_best and b_element together and replace original with merged
2267       if (ref $orig_best ne 'HASH') {
2268         $orig->[$best_candidate->{position}] = $import_element;
2269       } elsif (ref $import_element eq 'HASH') {
2270         my ($key) = keys %{$orig_best};
2271         $orig->[$best_candidate->{position}] = { $key => $self->_merge_attr($orig_best->{$key}, $import_element->{$key}) };
2272       }
2273     }
2274     $seen_keys->{$import_key} = 1; # don't merge the same key twice
2275   }
2276
2277   return $orig;
2278 }
2279
2280 sub result_source {
2281     my $self = shift;
2282
2283     if (@_) {
2284         $self->_source_handle($_[0]->handle);
2285     } else {
2286         $self->_source_handle->resolve;
2287     }
2288 }
2289
2290 =head2 throw_exception
2291
2292 See L<DBIx::Class::Schema/throw_exception> for details.
2293
2294 =cut
2295
2296 sub throw_exception {
2297   my $self=shift;
2298   if (ref $self && $self->_source_handle->schema) {
2299     $self->_source_handle->schema->throw_exception(@_)
2300   } else {
2301     croak(@_);
2302   }
2303
2304 }
2305
2306 # XXX: FIXME: Attributes docs need clearing up
2307
2308 =head1 ATTRIBUTES
2309
2310 The resultset takes various attributes that modify its behavior. Here's an
2311 overview of them:
2312
2313 =head2 order_by
2314
2315 =over 4
2316
2317 =item Value: ($order_by | \@order_by)
2318
2319 =back
2320
2321 Which column(s) to order the results by. This is currently passed
2322 through directly to SQL, so you can give e.g. C<year DESC> for a
2323 descending order on the column `year'.
2324
2325 Please note that if you have C<quote_char> enabled (see
2326 L<DBIx::Class::Storage::DBI/connect_info>) you will need to do C<\'year DESC' > to
2327 specify an order. (The scalar ref causes it to be passed as raw sql to the DB,
2328 so you will need to manually quote things as appropriate.)
2329
2330 If your L<SQL::Abstract> version supports it (>=1.50), you can also use
2331 C<{-desc => 'year'}>, which takes care of the quoting for you. This is the
2332 recommended syntax.
2333
2334 =head2 columns
2335
2336 =over 4
2337
2338 =item Value: \@columns
2339
2340 =back
2341
2342 Shortcut to request a particular set of columns to be retrieved.  Adds
2343 C<me.> onto the start of any column without a C<.> in it and sets C<select>
2344 from that, then auto-populates C<as> from C<select> as normal. (You may also
2345 use the C<cols> attribute, as in earlier versions of DBIC.)
2346
2347 =head2 include_columns
2348
2349 =over 4
2350
2351 =item Value: \@columns
2352
2353 =back
2354
2355 Shortcut to include additional columns in the returned results - for example
2356
2357   $schema->resultset('CD')->search(undef, {
2358     include_columns => ['artist.name'],
2359     join => ['artist']
2360   });
2361
2362 would return all CDs and include a 'name' column to the information
2363 passed to object inflation. Note that the 'artist' is the name of the
2364 column (or relationship) accessor, and 'name' is the name of the column
2365 accessor in the related table.
2366
2367 =head2 select
2368
2369 =over 4
2370
2371 =item Value: \@select_columns
2372
2373 =back
2374
2375 Indicates which columns should be selected from the storage. You can use
2376 column names, or in the case of RDBMS back ends, function or stored procedure
2377 names:
2378
2379   $rs = $schema->resultset('Employee')->search(undef, {
2380     select => [
2381       'name',
2382       { count => 'employeeid' },
2383       { sum => 'salary' }
2384     ]
2385   });
2386
2387 When you use function/stored procedure names and do not supply an C<as>
2388 attribute, the column names returned are storage-dependent. E.g. MySQL would
2389 return a column named C<count(employeeid)> in the above example.
2390
2391 =head2 +select
2392
2393 =over 4
2394
2395 Indicates additional columns to be selected from storage.  Works the same as
2396 L</select> but adds columns to the selection.
2397
2398 =back
2399
2400 =head2 +as
2401
2402 =over 4
2403
2404 Indicates additional column names for those added via L</+select>.
2405
2406 =back
2407
2408 =head2 as
2409
2410 =over 4
2411
2412 =item Value: \@inflation_names
2413
2414 =back
2415
2416 Indicates column names for object inflation. That is, C<as>
2417 indicates the name that the column can be accessed as via the
2418 C<get_column> method (or via the object accessor, B<if one already
2419 exists>).  It has nothing to do with the SQL code C<SELECT foo AS bar>.
2420
2421 The C<as> attribute is used in conjunction with C<select>,
2422 usually when C<select> contains one or more function or stored
2423 procedure names:
2424
2425   $rs = $schema->resultset('Employee')->search(undef, {
2426     select => [
2427       'name',
2428       { count => 'employeeid' }
2429     ],
2430     as => ['name', 'employee_count'],
2431   });
2432
2433   my $employee = $rs->first(); # get the first Employee
2434
2435 If the object against which the search is performed already has an accessor
2436 matching a column name specified in C<as>, the value can be retrieved using
2437 the accessor as normal:
2438
2439   my $name = $employee->name();
2440
2441 If on the other hand an accessor does not exist in the object, you need to
2442 use C<get_column> instead:
2443
2444   my $employee_count = $employee->get_column('employee_count');
2445
2446 You can create your own accessors if required - see
2447 L<DBIx::Class::Manual::Cookbook> for details.
2448
2449 Please note: This will NOT insert an C<AS employee_count> into the SQL
2450 statement produced, it is used for internal access only. Thus
2451 attempting to use the accessor in an C<order_by> clause or similar
2452 will fail miserably.
2453
2454 To get around this limitation, you can supply literal SQL to your
2455 C<select> attibute that contains the C<AS alias> text, eg:
2456
2457   select => [\'myfield AS alias']
2458
2459 =head2 join
2460
2461 =over 4
2462
2463 =item Value: ($rel_name | \@rel_names | \%rel_names)
2464
2465 =back
2466
2467 Contains a list of relationships that should be joined for this query.  For
2468 example:
2469
2470   # Get CDs by Nine Inch Nails
2471   my $rs = $schema->resultset('CD')->search(
2472     { 'artist.name' => 'Nine Inch Nails' },
2473     { join => 'artist' }
2474   );
2475
2476 Can also contain a hash reference to refer to the other relation's relations.
2477 For example:
2478
2479   package MyApp::Schema::Track;
2480   use base qw/DBIx::Class/;
2481   __PACKAGE__->table('track');
2482   __PACKAGE__->add_columns(qw/trackid cd position title/);
2483   __PACKAGE__->set_primary_key('trackid');
2484   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
2485   1;
2486
2487   # In your application
2488   my $rs = $schema->resultset('Artist')->search(
2489     { 'track.title' => 'Teardrop' },
2490     {
2491       join     => { cd => 'track' },
2492       order_by => 'artist.name',
2493     }
2494   );
2495
2496 You need to use the relationship (not the table) name in  conditions,
2497 because they are aliased as such. The current table is aliased as "me", so
2498 you need to use me.column_name in order to avoid ambiguity. For example:
2499
2500   # Get CDs from 1984 with a 'Foo' track
2501   my $rs = $schema->resultset('CD')->search(
2502     {
2503       'me.year' => 1984,
2504       'tracks.name' => 'Foo'
2505     },
2506     { join => 'tracks' }
2507   );
2508
2509 If the same join is supplied twice, it will be aliased to <rel>_2 (and
2510 similarly for a third time). For e.g.
2511
2512   my $rs = $schema->resultset('Artist')->search({
2513     'cds.title'   => 'Down to Earth',
2514     'cds_2.title' => 'Popular',
2515   }, {
2516     join => [ qw/cds cds/ ],
2517   });
2518
2519 will return a set of all artists that have both a cd with title 'Down
2520 to Earth' and a cd with title 'Popular'.
2521
2522 If you want to fetch related objects from other tables as well, see C<prefetch>
2523 below.
2524
2525 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
2526
2527 =head2 prefetch
2528
2529 =over 4
2530
2531 =item Value: ($rel_name | \@rel_names | \%rel_names)
2532
2533 =back
2534
2535 Contains one or more relationships that should be fetched along with
2536 the main query (when they are accessed afterwards the data will
2537 already be available, without extra queries to the database).  This is
2538 useful for when you know you will need the related objects, because it
2539 saves at least one query:
2540
2541   my $rs = $schema->resultset('Tag')->search(
2542     undef,
2543     {
2544       prefetch => {
2545         cd => 'artist'
2546       }
2547     }
2548   );
2549
2550 The initial search results in SQL like the following:
2551
2552   SELECT tag.*, cd.*, artist.* FROM tag
2553   JOIN cd ON tag.cd = cd.cdid
2554   JOIN artist ON cd.artist = artist.artistid
2555
2556 L<DBIx::Class> has no need to go back to the database when we access the
2557 C<cd> or C<artist> relationships, which saves us two SQL statements in this
2558 case.
2559
2560 Simple prefetches will be joined automatically, so there is no need
2561 for a C<join> attribute in the above search.
2562
2563 C<prefetch> can be used with the following relationship types: C<belongs_to>,
2564 C<has_one> (or if you're using C<add_relationship>, any relationship declared
2565 with an accessor type of 'single' or 'filter'). A more complex example that
2566 prefetches an artists cds, the tracks on those cds, and the tags associted
2567 with that artist is given below (assuming many-to-many from artists to tags):
2568
2569  my $rs = $schema->resultset('Artist')->search(
2570    undef,
2571    {
2572      prefetch => [
2573        { cds => 'tracks' },
2574        { artist_tags => 'tags' }
2575      ]
2576    }
2577  );
2578
2579
2580 B<NOTE:> If you specify a C<prefetch> attribute, the C<join> and C<select>
2581 attributes will be ignored.
2582
2583 =head2 page
2584
2585 =over 4
2586
2587 =item Value: $page
2588
2589 =back
2590
2591 Makes the resultset paged and specifies the page to retrieve. Effectively
2592 identical to creating a non-pages resultset and then calling ->page($page)
2593 on it.
2594
2595 If L<rows> attribute is not specified it defualts to 10 rows per page.
2596
2597 =head2 rows
2598
2599 =over 4
2600
2601 =item Value: $rows
2602
2603 =back
2604
2605 Specifes the maximum number of rows for direct retrieval or the number of
2606 rows per page if the page attribute or method is used.
2607
2608 =head2 offset
2609
2610 =over 4
2611
2612 =item Value: $offset
2613
2614 =back
2615
2616 Specifies the (zero-based) row number for the  first row to be returned, or the
2617 of the first row of the first page if paging is used.
2618
2619 =head2 group_by
2620
2621 =over 4
2622
2623 =item Value: \@columns
2624
2625 =back
2626
2627 A arrayref of columns to group by. Can include columns of joined tables.
2628
2629   group_by => [qw/ column1 column2 ... /]
2630
2631 =head2 having
2632
2633 =over 4
2634
2635 =item Value: $condition
2636
2637 =back
2638
2639 HAVING is a select statement attribute that is applied between GROUP BY and
2640 ORDER BY. It is applied to the after the grouping calculations have been
2641 done.
2642
2643   having => { 'count(employee)' => { '>=', 100 } }
2644
2645 =head2 distinct
2646
2647 =over 4
2648
2649 =item Value: (0 | 1)
2650
2651 =back
2652
2653 Set to 1 to group by all columns.
2654
2655 =head2 where
2656
2657 =over 4
2658
2659 Adds to the WHERE clause.
2660
2661   # only return rows WHERE deleted IS NULL for all searches
2662   __PACKAGE__->resultset_attributes({ where => { deleted => undef } }); )
2663
2664 Can be overridden by passing C<{ where => undef }> as an attribute
2665 to a resulset.
2666
2667 =back
2668
2669 =head2 cache
2670
2671 Set to 1 to cache search results. This prevents extra SQL queries if you
2672 revisit rows in your ResultSet:
2673
2674   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
2675
2676   while( my $artist = $resultset->next ) {
2677     ... do stuff ...
2678   }
2679
2680   $rs->first; # without cache, this would issue a query
2681
2682 By default, searches are not cached.
2683
2684 For more examples of using these attributes, see
2685 L<DBIx::Class::Manual::Cookbook>.
2686
2687 =head2 from
2688
2689 =over 4
2690
2691 =item Value: \@from_clause
2692
2693 =back
2694
2695 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
2696 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
2697 clauses.
2698
2699 NOTE: Use this on your own risk.  This allows you to shoot off your foot!
2700
2701 C<join> will usually do what you need and it is strongly recommended that you
2702 avoid using C<from> unless you cannot achieve the desired result using C<join>.
2703 And we really do mean "cannot", not just tried and failed. Attempting to use
2704 this because you're having problems with C<join> is like trying to use x86
2705 ASM because you've got a syntax error in your C. Trust us on this.
2706
2707 Now, if you're still really, really sure you need to use this (and if you're
2708 not 100% sure, ask the mailing list first), here's an explanation of how this
2709 works.
2710
2711 The syntax is as follows -
2712
2713   [
2714     { <alias1> => <table1> },
2715     [
2716       { <alias2> => <table2>, -join_type => 'inner|left|right' },
2717       [], # nested JOIN (optional)
2718       { <table1.column1> => <table2.column2>, ... (more conditions) },
2719     ],
2720     # More of the above [ ] may follow for additional joins
2721   ]
2722
2723   <table1> <alias1>
2724   JOIN
2725     <table2> <alias2>
2726     [JOIN ...]
2727   ON <table1.column1> = <table2.column2>
2728   <more joins may follow>
2729
2730 An easy way to follow the examples below is to remember the following:
2731
2732     Anything inside "[]" is a JOIN
2733     Anything inside "{}" is a condition for the enclosing JOIN
2734
2735 The following examples utilize a "person" table in a family tree application.
2736 In order to express parent->child relationships, this table is self-joined:
2737
2738     # Person->belongs_to('father' => 'Person');
2739     # Person->belongs_to('mother' => 'Person');
2740
2741 C<from> can be used to nest joins. Here we return all children with a father,
2742 then search against all mothers of those children:
2743
2744   $rs = $schema->resultset('Person')->search(
2745       undef,
2746       {
2747           alias => 'mother', # alias columns in accordance with "from"
2748           from => [
2749               { mother => 'person' },
2750               [
2751                   [
2752                       { child => 'person' },
2753                       [
2754                           { father => 'person' },
2755                           { 'father.person_id' => 'child.father_id' }
2756                       ]
2757                   ],
2758                   { 'mother.person_id' => 'child.mother_id' }
2759               ],
2760           ]
2761       },
2762   );
2763
2764   # Equivalent SQL:
2765   # SELECT mother.* FROM person mother
2766   # JOIN (
2767   #   person child
2768   #   JOIN person father
2769   #   ON ( father.person_id = child.father_id )
2770   # )
2771   # ON ( mother.person_id = child.mother_id )
2772
2773 The type of any join can be controlled manually. To search against only people
2774 with a father in the person table, we could explicitly use C<INNER JOIN>:
2775
2776     $rs = $schema->resultset('Person')->search(
2777         undef,
2778         {
2779             alias => 'child', # alias columns in accordance with "from"
2780             from => [
2781                 { child => 'person' },
2782                 [
2783                     { father => 'person', -join_type => 'inner' },
2784                     { 'father.id' => 'child.father_id' }
2785                 ],
2786             ]
2787         },
2788     );
2789
2790     # Equivalent SQL:
2791     # SELECT child.* FROM person child
2792     # INNER JOIN person father ON child.father_id = father.id
2793
2794 =head2 for
2795
2796 =over 4
2797
2798 =item Value: ( 'update' | 'shared' )
2799
2800 =back
2801
2802 Set to 'update' for a SELECT ... FOR UPDATE or 'shared' for a SELECT
2803 ... FOR SHARED.
2804
2805 =cut
2806
2807 1;