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'   => sub { 1; },
   8         fallback => 1;
   9 use Carp::Clan qw/^DBIx::Class/;
  10 use Data::Page;
  11 use Storable;
  12 use DBIx::Class::ResultSetColumn;
  13 use base qw/DBIx::Class/;
  14
  15 __PACKAGE__->load_components(qw/AccessorGroup/);
  16 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
  17
  18 =head1 NAME
  19
  20 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
  21
  22 =head1 SYNOPSIS
  23
  24   my $rs   = $schema->resultset('User')->search(registered => 1);
  25   my @rows = $schema->resultset('CD')->search(year => 2005);
  26
  27 =head1 DESCRIPTION
  28
  29 The resultset is also known as an iterator. It is responsible for handling
  30 queries that may return an arbitrary number of rows, e.g. via L</search>
  31 or a C<has_many> relationship.
  32
  33 In the examples below, the following table classes are used:
  34
  35   package MyApp::Schema::Artist;
  36   use base qw/DBIx::Class/;
  37   __PACKAGE__->load_components(qw/Core/);
  38   __PACKAGE__->table('artist');
  39   __PACKAGE__->add_columns(qw/artistid name/);
  40   __PACKAGE__->set_primary_key('artistid');
  41   __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
  42   1;
  43
  44   package MyApp::Schema::CD;
  45   use base qw/DBIx::Class/;
  46   __PACKAGE__->load_components(qw/Core/);
  47   __PACKAGE__->table('cd');
  48   __PACKAGE__->add_columns(qw/cdid artist title year/);
  49   __PACKAGE__->set_primary_key('cdid');
  50   __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
  51   1;
  52
  53 =head1 METHODS
  54
  55 =head2 new
  56
  57 =over 4
  58
  59 =item Arguments: $source, \%$attrs
  60
  61 =item Return Value: $rs
  62
  63 =back
  64
  65 The resultset constructor. Takes a source object (usually a
  66 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
  67 L</ATTRIBUTES> below).  Does not perform any queries -- these are
  68 executed as needed by the other methods.
  69
  70 Generally you won't need to construct a resultset manually.  You'll
  71 automatically get one from e.g. a L</search> called in scalar context:
  72
  73   my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
  74
  75 IMPORTANT: If called on an object, proxies to new_result instead so
  76
  77   my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
  78
  79 will return a CD object, not a ResultSet.
  80
  81 =cut
  82
  83 sub new {
  84   my $class = shift;
  85   return $class->new_result(@_) if ref $class;
  86
  87   my ($source, $attrs) = @_;
  88   #weaken $source;
  89
  90   if ($attrs->{page}) {
  91     $attrs->{rows} ||= 10;
  92     $attrs->{offset} ||= 0;
  93     $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
  94   }
  95
  96   $attrs->{alias} ||= 'me';
  97
  98   bless {
  99     result_source => $source,
 100     result_class => $attrs->{result_class} || $source->result_class,
 101     cond => $attrs->{where},
 102     count => undef,
 103     pager => undef,
 104     attrs => $attrs
 105   }, $class;
 106 }
 107
 108 =head2 search
 109
 110 =over 4
 111
 112 =item Arguments: $cond, \%attrs?
 113
 114 =item Return Value: $resultset (scalar context), @row_objs (list context)
 115
 116 =back
 117
 118   my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
 119   my $new_rs = $cd_rs->search({ year => 2005 });
 120
 121   my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
 122                  # year = 2005 OR year = 2004
 123
 124 If you need to pass in additional attributes but no additional condition,
 125 call it as C<search(undef, \%attrs)>.
 126
 127   # "SELECT name, artistid FROM $artist_table"
 128   my @all_artists = $schema->resultset('Artist')->search(undef, {
 129     columns => [qw/name artistid/],
 130   });
 131
 132 =cut
 133
 134 sub search {
 135   my $self = shift;
 136   my $rs = $self->search_rs( @_ );
 137   return (wantarray ? $rs->all : $rs);
 138 }
 139
 140 =head2 search_rs
 141
 142 =over 4
 143
 144 =item Arguments: $cond, \%attrs?
 145
 146 =item Return Value: $resultset
 147
 148 =back
 149
 150 This method does the same exact thing as search() except it will
 151 always return a resultset, even in list context.
 152
 153 =cut
 154
 155 sub search_rs {
 156   my $self = shift;
 157
 158   my $rows;
 159
 160   unless (@_) {                 # no search, effectively just a clone
 161     $rows = $self->get_cache;
 162   }
 163
 164   my $attrs = {};
 165   $attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
 166   my $our_attrs = { %{$self->{attrs}} };
 167   my $having = delete $our_attrs->{having};
 168
 169   # merge new attrs into inherited
 170   foreach my $key (qw/join prefetch/) {
 171     next unless exists $attrs->{$key};
 172     $our_attrs->{$key} = $self->_merge_attr($our_attrs->{$key}, delete $attrs->{$key});
 173   }
 174
 175   my $new_attrs = { %{$our_attrs}, %{$attrs} };
 176   my $where = (@_
 177     ? (
 178         (@_ == 1 || ref $_[0] eq "HASH")
 179           ? shift
 180           : (
 181               (@_ % 2)
 182                 ? $self->throw_exception("Odd number of arguments to search")
 183                 : {@_}
 184              )
 185       )
 186     : undef
 187   );
 188
 189   if (defined $where) {
 190     $new_attrs->{where} = (
 191       defined $new_attrs->{where}
 192         ? { '-and' => [
 193               map {
 194                 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
 195               } $where, $new_attrs->{where}
 196             ]
 197           }
 198         : $where);
 199   }
 200
 201   if (defined $having) {
 202     $new_attrs->{having} = (
 203       defined $new_attrs->{having}
 204         ? { '-and' => [
 205               map {
 206                 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
 207               } $having, $new_attrs->{having}
 208             ]
 209           }
 210         : $having);
 211   }
 212
 213   my $rs = (ref $self)->new($self->result_source, $new_attrs);
 214   if ($rows) {
 215     $rs->set_cache($rows);
 216   }
 217   return $rs;
 218 }
 219
 220 =head2 search_literal
 221
 222 =over 4
 223
 224 =item Arguments: $sql_fragment, @bind_values
 225
 226 =item Return Value: $resultset (scalar context), @row_objs (list context)
 227
 228 =back
 229
 230   my @cds   = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
 231   my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
 232
 233 Pass a literal chunk of SQL to be added to the conditional part of the
 234 resultset query.
 235
 236 =cut
 237
 238 sub search_literal {
 239   my ($self, $cond, @vals) = @_;
 240   my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
 241   $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
 242   return $self->search(\$cond, $attrs);
 243 }
 244
 245 =head2 find
 246
 247 =over 4
 248
 249 =item Arguments: @values | \%cols, \%attrs?
 250
 251 =item Return Value: $row_object
 252
 253 =back
 254
 255 Finds a row based on its primary key or unique constraint. For example, to find
 256 a row by its primary key:
 257
 258   my $cd = $schema->resultset('CD')->find(5);
 259
 260 You can also find a row by a specific unique constraint using the C<key>
 261 attribute. For example:
 262
 263   my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', {
 264     key => 'cd_artist_title'
 265   });
 266
 267 Additionally, you can specify the columns explicitly by name:
 268
 269   my $cd = $schema->resultset('CD')->find(
 270     {
 271       artist => 'Massive Attack',
 272       title  => 'Mezzanine',
 273     },
 274     { key => 'cd_artist_title' }
 275   );
 276
 277 If the C<key> is specified as C<primary>, it searches only on the primary key.
 278
 279 If no C<key> is specified, it searches on all unique constraints defined on the
 280 source, including the primary key.
 281
 282 See also L</find_or_create> and L</update_or_create>. For information on how to
 283 declare unique constraints, see
 284 L<DBIx::Class::ResultSource/add_unique_constraint>.
 285
 286 =cut
 287
 288 sub find {
 289   my $self = shift;
 290   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 291
 292   # Default to the primary key, but allow a specific key
 293   my @cols = exists $attrs->{key}
 294     ? $self->result_source->unique_constraint_columns($attrs->{key})
 295     : $self->result_source->primary_columns;
 296   $self->throw_exception(
 297     "Can't find unless a primary key or unique constraint is defined"
 298   ) unless @cols;
 299
 300   # Parse out a hashref from input
 301   my $input_query;
 302   if (ref $_[0] eq 'HASH') {
 303     $input_query = { %{$_[0]} };
 304   }
 305   elsif (@_ == @cols) {
 306     $input_query = {};
 307     @{$input_query}{@cols} = @_;
 308   }
 309   else {
 310     # Compatibility: Allow e.g. find(id => $value)
 311     carp "Find by key => value deprecated; please use a hashref instead";
 312     $input_query = {@_};
 313   }
 314
 315   my @unique_queries = $self->_unique_queries($input_query, $attrs);
 316
 317   # Handle cases where the ResultSet defines the query, or where the user is
 318   # abusing find
 319   my $query = @unique_queries ? \@unique_queries : $input_query;
 320
 321   # Run the query
 322   if (keys %$attrs) {
 323     my $rs = $self->search($query, $attrs);
 324     return keys %{$rs->_resolved_attrs->{collapse}} ? $rs->next : $rs->single;
 325   }
 326   else {
 327     return keys %{$self->_resolved_attrs->{collapse}}
 328       ? $self->search($query)->next
 329       : $self->single($query);
 330   }
 331 }
 332
 333 # _unique_queries
 334 #
 335 # Build a list of queries which satisfy unique constraints.
 336
 337 sub _unique_queries {
 338   my ($self, $query, $attrs) = @_;
 339
 340   my $alias = $self->{attrs}{alias};
 341   my @constraint_names = exists $attrs->{key}
 342     ? ($attrs->{key})
 343     : $self->result_source->unique_constraint_names;
 344
 345   my @unique_queries;
 346   foreach my $name (@constraint_names) {
 347     my @unique_cols = $self->result_source->unique_constraint_columns($name);
 348     my $unique_query = $self->_build_unique_query($query, \@unique_cols);
 349
 350     my $num_query = scalar keys %$unique_query;
 351     next unless $num_query;
 352
 353     # Add the ResultSet's alias
 354     foreach my $col (grep { ! m/\./ } keys %$unique_query) {
 355       $unique_query->{"$alias.$col"} = delete $unique_query->{$col};
 356     }
 357
 358     # XXX: Assuming quite a bit about $self->{attrs}{where}
 359     my $num_cols = scalar @unique_cols;
 360     my $num_where = exists $self->{attrs}{where}
 361       ? scalar keys %{ $self->{attrs}{where} }
 362       : 0;
 363     push @unique_queries, $unique_query
 364       if $num_query + $num_where == $num_cols;
 365   }
 366
 367   return @unique_queries;
 368 }
 369
 370 # _build_unique_query
 371 #
 372 # Constrain the specified query hash based on the specified column names.
 373
 374 sub _build_unique_query {
 375   my ($self, $query, $unique_cols) = @_;
 376
 377   return {
 378     map  { $_ => $query->{$_} }
 379     grep { exists $query->{$_} }
 380       @$unique_cols
 381   };
 382 }
 383
 384 =head2 search_related
 385
 386 =over 4
 387
 388 =item Arguments: $rel, $cond, \%attrs?
 389
 390 =item Return Value: $new_resultset
 391
 392 =back
 393
 394   $new_rs = $cd_rs->search_related('artist', {
 395     name => 'Emo-R-Us',
 396   });
 397
 398 Searches the specified relationship, optionally specifying a condition and
 399 attributes for matching records. See L</ATTRIBUTES> for more information.
 400
 401 =cut
 402
 403 sub search_related {
 404   return shift->related_resultset(shift)->search(@_);
 405 }
 406
 407 =head2 cursor
 408
 409 =over 4
 410
 411 =item Arguments: none
 412
 413 =item Return Value: $cursor
 414
 415 =back
 416
 417 Returns a storage-driven cursor to the given resultset. See
 418 L<DBIx::Class::Cursor> for more information.
 419
 420 =cut
 421
 422 sub cursor {
 423   my ($self) = @_;
 424
 425   my $attrs = { %{$self->_resolved_attrs} };
 426   return $self->{cursor}
 427     ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
 428           $attrs->{where},$attrs);
 429 }
 430
 431 =head2 single
 432
 433 =over 4
 434
 435 =item Arguments: $cond?
 436
 437 =item Return Value: $row_object?
 438
 439 =back
 440
 441   my $cd = $schema->resultset('CD')->single({ year => 2001 });
 442
 443 Inflates the first result without creating a cursor if the resultset has
 444 any records in it; if not returns nothing. Used by L</find> as an optimisation.
 445
 446 Can optionally take an additional condition *only* - this is a fast-code-path
 447 method; if you need to add extra joins or similar call ->search and then
 448 ->single without a condition on the $rs returned from that.
 449
 450 =cut
 451
 452 sub single {
 453   my ($self, $where) = @_;
 454   my $attrs = { %{$self->_resolved_attrs} };
 455   if ($where) {
 456     if (defined $attrs->{where}) {
 457       $attrs->{where} = {
 458         '-and' =>
 459             [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
 460                $where, delete $attrs->{where} ]
 461       };
 462     } else {
 463       $attrs->{where} = $where;
 464     }
 465   }
 466
 467   unless ($self->_is_unique_query($attrs->{where})) {
 468     carp "Query not guaranteed to return a single row"
 469       . "; please declare your unique constraints or use search instead";
 470   }
 471
 472   my @data = $self->result_source->storage->select_single(
 473     $attrs->{from}, $attrs->{select},
 474     $attrs->{where}, $attrs
 475   );
 476
 477   return (@data ? $self->_construct_object(@data) : ());
 478 }
 479
 480 # _is_unique_query
 481 #
 482 # Try to determine if the specified query is guaranteed to be unique, based on
 483 # the declared unique constraints.
 484
 485 sub _is_unique_query {
 486   my ($self, $query) = @_;
 487
 488   my $collapsed = $self->_collapse_query($query);
 489   my $alias = $self->{attrs}{alias};
 490
 491   foreach my $name ($self->result_source->unique_constraint_names) {
 492     my @unique_cols = map {
 493       "$alias.$_"
 494     } $self->result_source->unique_constraint_columns($name);
 495
 496     # Count the values for each unique column
 497     my %seen = map { $_ => 0 } @unique_cols;
 498
 499     foreach my $key (keys %$collapsed) {
 500       my $aliased = $key =~ /\./ ? $key : "$alias.$key";
 501       next unless exists $seen{$aliased};  # Additional constraints are okay
 502       $seen{$aliased} = scalar keys %{ $collapsed->{$key} };
 503     }
 504
 505     # If we get 0 or more than 1 value for a column, it's not necessarily unique
 506     return 1 unless grep { $_ != 1 } values %seen;
 507   }
 508
 509   return 0;
 510 }
 511
 512 # _collapse_query
 513 #
 514 # Recursively collapse the query, accumulating values for each column.
 515
 516 sub _collapse_query {
 517   my ($self, $query, $collapsed) = @_;
 518
 519   $collapsed ||= {};
 520
 521   if (ref $query eq 'ARRAY') {
 522     foreach my $subquery (@$query) {
 523       next unless ref $subquery;  # -or
 524 #      warn "ARRAY: " . Dumper $subquery;
 525       $collapsed = $self->_collapse_query($subquery, $collapsed);
 526     }
 527   }
 528   elsif (ref $query eq 'HASH') {
 529     if (keys %$query and (keys %$query)[0] eq '-and') {
 530       foreach my $subquery (@{$query->{-and}}) {
 531 #        warn "HASH: " . Dumper $subquery;
 532         $collapsed = $self->_collapse_query($subquery, $collapsed);
 533       }
 534     }
 535     else {
 536 #      warn "LEAF: " . Dumper $query;
 537       foreach my $col (keys %$query) {
 538         my $value = $query->{$col};
 539         $collapsed->{$col}{$value}++;
 540       }
 541     }
 542   }
 543
 544   return $collapsed;
 545 }
 546
 547 =head2 get_column
 548
 549 =over 4
 550
 551 =item Arguments: $cond?
 552
 553 =item Return Value: $resultsetcolumn
 554
 555 =back
 556
 557   my $max_length = $rs->get_column('length')->max;
 558
 559 Returns a ResultSetColumn instance for $column based on $self
 560
 561 =cut
 562
 563 sub get_column {
 564   my ($self, $column) = @_;
 565   my $new = DBIx::Class::ResultSetColumn->new($self, $column);
 566   return $new;
 567 }
 568
 569 =head2 search_like
 570
 571 =over 4
 572
 573 =item Arguments: $cond, \%attrs?
 574
 575 =item Return Value: $resultset (scalar context), @row_objs (list context)
 576
 577 =back
 578
 579   # WHERE title LIKE '%blue%'
 580   $cd_rs = $rs->search_like({ title => '%blue%'});
 581
 582 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
 583 that this is simply a convenience method. You most likely want to use
 584 L</search> with specific operators.
 585
 586 For more information, see L<DBIx::Class::Manual::Cookbook>.
 587
 588 =cut
 589
 590 sub search_like {
 591   my $class = shift;
 592   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 593   my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
 594   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
 595   return $class->search($query, { %$attrs });
 596 }
 597
 598 =head2 slice
 599
 600 =over 4
 601
 602 =item Arguments: $first, $last
 603
 604 =item Return Value: $resultset (scalar context), @row_objs (list context)
 605
 606 =back
 607
 608 Returns a resultset or object list representing a subset of elements from the
 609 resultset slice is called on. Indexes are from 0, i.e., to get the first
 610 three records, call:
 611
 612   my ($one, $two, $three) = $rs->slice(0, 2);
 613
 614 =cut
 615
 616 sub slice {
 617   my ($self, $min, $max) = @_;
 618   my $attrs = {}; # = { %{ $self->{attrs} || {} } };
 619   $attrs->{offset} = $self->{attrs}{offset} || 0;
 620   $attrs->{offset} += $min;
 621   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
 622   return $self->search(undef(), $attrs);
 623   #my $slice = (ref $self)->new($self->result_source, $attrs);
 624   #return (wantarray ? $slice->all : $slice);
 625 }
 626
 627 =head2 next
 628
 629 =over 4
 630
 631 =item Arguments: none
 632
 633 =item Return Value: $result?
 634
 635 =back
 636
 637 Returns the next element in the resultset (C<undef> is there is none).
 638
 639 Can be used to efficiently iterate over records in the resultset:
 640
 641   my $rs = $schema->resultset('CD')->search;
 642   while (my $cd = $rs->next) {
 643     print $cd->title;
 644   }
 645
 646 Note that you need to store the resultset object, and call C<next> on it.
 647 Calling C<< resultset('Table')->next >> repeatedly will always return the
 648 first record from the resultset.
 649
 650 =cut
 651
 652 sub next {
 653   my ($self) = @_;
 654   if (my $cache = $self->get_cache) {
 655     $self->{all_cache_position} ||= 0;
 656     return $cache->[$self->{all_cache_position}++];
 657   }
 658   if ($self->{attrs}{cache}) {
 659     $self->{all_cache_position} = 1;
 660     return ($self->all)[0];
 661   }
 662   my @row = (
 663     exists $self->{stashed_row}
 664       ? @{delete $self->{stashed_row}}
 665       : $self->cursor->next
 666   );
 667   return unless (@row);
 668   return $self->_construct_object(@row);
 669 }
 670
 671 sub _construct_object {
 672   my ($self, @row) = @_;
 673   my $info = $self->_collapse_result($self->{_attrs}{as}, \@row);
 674   my $new = $self->result_class->inflate_result($self->result_source, @$info);
 675   $new = $self->{_attrs}{record_filter}->($new)
 676     if exists $self->{_attrs}{record_filter};
 677   return $new;
 678 }
 679
 680 sub _collapse_result {
 681   my ($self, $as, $row, $prefix) = @_;
 682
 683   my %const;
 684   my @copy = @$row;
 685
 686   foreach my $this_as (@$as) {
 687     my $val = shift @copy;
 688     if (defined $prefix) {
 689       if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
 690         my $remain = $1;
 691         $remain =~ /^(?:(.*)\.)?([^.]+)$/;
 692         $const{$1||''}{$2} = $val;
 693       }
 694     } else {
 695       $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
 696       $const{$1||''}{$2} = $val;
 697     }
 698   }
 699
 700   my $alias = $self->{attrs}{alias};
 701   my $info = [ {}, {} ];
 702   foreach my $key (keys %const) {
 703     if (length $key && $key ne $alias) {
 704       my $target = $info;
 705       my @parts = split(/\./, $key);
 706       foreach my $p (@parts) {
 707         $target = $target->[1]->{$p} ||= [];
 708       }
 709       $target->[0] = $const{$key};
 710     } else {
 711       $info->[0] = $const{$key};
 712     }
 713   }
 714
 715   my @collapse;
 716   if (defined $prefix) {
 717     @collapse = map {
 718         m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
 719     } keys %{$self->{_attrs}{collapse}}
 720   } else {
 721     @collapse = keys %{$self->{_attrs}{collapse}};
 722   };
 723
 724   if (@collapse) {
 725     my ($c) = sort { length $a <=> length $b } @collapse;
 726     my $target = $info;
 727     foreach my $p (split(/\./, $c)) {
 728       $target = $target->[1]->{$p} ||= [];
 729     }
 730     my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
 731     my @co_key = @{$self->{_attrs}{collapse}{$c_prefix}};
 732     my $tree = $self->_collapse_result($as, $row, $c_prefix);
 733     my %co_check = map { ($_, $tree->[0]->{$_}); } @co_key;
 734     my (@final, @raw);
 735
 736     while (
 737       !(
 738         grep {
 739           !defined($tree->[0]->{$_}) || $co_check{$_} ne $tree->[0]->{$_}
 740         } @co_key
 741         )
 742     ) {
 743       push(@final, $tree);
 744       last unless (@raw = $self->cursor->next);
 745       $row = $self->{stashed_row} = \@raw;
 746       $tree = $self->_collapse_result($as, $row, $c_prefix);
 747     }
 748     @$target = (@final ? @final : [ {}, {} ]);
 749       # single empty result to indicate an empty prefetched has_many
 750   }
 751
 752   #print "final info: " . Dumper($info);
 753   return $info;
 754 }
 755
 756 =head2 result_source
 757
 758 =over 4
 759
 760 =item Arguments: $result_source?
 761
 762 =item Return Value: $result_source
 763
 764 =back
 765
 766 An accessor for the primary ResultSource object from which this ResultSet
 767 is derived.
 768
 769 =head2 result_class
 770
 771 =over 4
 772
 773 =item Arguments: $result_class?
 774
 775 =item Return Value: $result_class
 776
 777 =back
 778
 779 An accessor for the class to use when creating row objects. Defaults to
 780 C<< result_source->result_class >> - which in most cases is the name of the
 781 L<"table"|DBIx::Class::Manual::Glossary/"ResultSource"> class.
 782
 783 =cut
 784
 785
 786 =head2 count
 787
 788 =over 4
 789
 790 =item Arguments: $cond, \%attrs??
 791
 792 =item Return Value: $count
 793
 794 =back
 795
 796 Performs an SQL C<COUNT> with the same query as the resultset was built
 797 with to find the number of elements. If passed arguments, does a search
 798 on the resultset and counts the results of that.
 799
 800 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
 801 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
 802 not support C<DISTINCT> with multiple columns. If you are using such a
 803 database, you should only use columns from the main table in your C<group_by>
 804 clause.
 805
 806 =cut
 807
 808 sub count {
 809   my $self = shift;
 810   return $self->search(@_)->count if @_ and defined $_[0];
 811   return scalar @{ $self->get_cache } if $self->get_cache;
 812   my $count = $self->_count;
 813   return 0 unless $count;
 814
 815   $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
 816   $count = $self->{attrs}{rows} if
 817     $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
 818   return $count;
 819 }
 820
 821 sub _count { # Separated out so pager can get the full count
 822   my $self = shift;
 823   my $select = { count => '*' };
 824
 825   my $attrs = { %{$self->_resolved_attrs} };
 826   if (my $group_by = delete $attrs->{group_by}) {
 827     delete $attrs->{having};
 828     my @distinct = (ref $group_by ?  @$group_by : ($group_by));
 829     # todo: try CONCAT for multi-column pk
 830     my @pk = $self->result_source->primary_columns;
 831     if (@pk == 1) {
 832       my $alias = $attrs->{alias};
 833       foreach my $column (@distinct) {
 834         if ($column =~ qr/^(?:\Q${alias}.\E)?$pk[0]$/) {
 835           @distinct = ($column);
 836           last;
 837         }
 838       }
 839     }
 840
 841     $select = { count => { distinct => \@distinct } };
 842   }
 843
 844   $attrs->{select} = $select;
 845   $attrs->{as} = [qw/count/];
 846
 847   # offset, order by and page are not needed to count. record_filter is cdbi
 848   delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
 849
 850   my $tmp_rs = (ref $self)->new($self->result_source, $attrs);
 851   my ($count) = $tmp_rs->cursor->next;
 852   return $count;
 853 }
 854
 855 =head2 count_literal
 856
 857 =over 4
 858
 859 =item Arguments: $sql_fragment, @bind_values
 860
 861 =item Return Value: $count
 862
 863 =back
 864
 865 Counts the results in a literal query. Equivalent to calling L</search_literal>
 866 with the passed arguments, then L</count>.
 867
 868 =cut
 869
 870 sub count_literal { shift->search_literal(@_)->count; }
 871
 872 =head2 all
 873
 874 =over 4
 875
 876 =item Arguments: none
 877
 878 =item Return Value: @objects
 879
 880 =back
 881
 882 Returns all elements in the resultset. Called implicitly if the resultset
 883 is returned in list context.
 884
 885 =cut
 886
 887 sub all {
 888   my ($self) = @_;
 889   return @{ $self->get_cache } if $self->get_cache;
 890
 891   my @obj;
 892
 893   # TODO: don't call resolve here
 894   if (keys %{$self->_resolved_attrs->{collapse}}) {
 895 #  if ($self->{attrs}{prefetch}) {
 896       # Using $self->cursor->all is really just an optimisation.
 897       # If we're collapsing has_many prefetches it probably makes
 898       # very little difference, and this is cleaner than hacking
 899       # _construct_object to survive the approach
 900     my @row = $self->cursor->next;
 901     while (@row) {
 902       push(@obj, $self->_construct_object(@row));
 903       @row = (exists $self->{stashed_row}
 904                ? @{delete $self->{stashed_row}}
 905                : $self->cursor->next);
 906     }
 907   } else {
 908     @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
 909   }
 910
 911   $self->set_cache(\@obj) if $self->{attrs}{cache};
 912   return @obj;
 913 }
 914
 915 =head2 reset
 916
 917 =over 4
 918
 919 =item Arguments: none
 920
 921 =item Return Value: $self
 922
 923 =back
 924
 925 Resets the resultset's cursor, so you can iterate through the elements again.
 926
 927 =cut
 928
 929 sub reset {
 930   my ($self) = @_;
 931   delete $self->{_attrs} if exists $self->{_attrs};
 932   $self->{all_cache_position} = 0;
 933   $self->cursor->reset;
 934   return $self;
 935 }
 936
 937 =head2 first
 938
 939 =over 4
 940
 941 =item Arguments: none
 942
 943 =item Return Value: $object?
 944
 945 =back
 946
 947 Resets the resultset and returns an object for the first result (if the
 948 resultset returns anything).
 949
 950 =cut
 951
 952 sub first {
 953   return $_[0]->reset->next;
 954 }
 955
 956 # _cond_for_update_delete
 957 #
 958 # update/delete require the condition to be modified to handle
 959 # the differing SQL syntax available.  This transforms the $self->{cond}
 960 # appropriately, returning the new condition.
 961
 962 sub _cond_for_update_delete {
 963   my ($self) = @_;
 964   my $cond = {};
 965
 966   # No-op. No condition, we're updating/deleting everything
 967   return $cond unless ref $self->{cond};
 968
 969   if (ref $self->{cond} eq 'ARRAY') {
 970     $cond = [
 971       map {
 972         my %hash;
 973         foreach my $key (keys %{$_}) {
 974           $key =~ /([^.]+)$/;
 975           $hash{$1} = $_->{$key};
 976         }
 977         \%hash;
 978       } @{$self->{cond}}
 979     ];
 980   }
 981   elsif (ref $self->{cond} eq 'HASH') {
 982     if ((keys %{$self->{cond}})[0] eq '-and') {
 983       $cond->{-and} = [];
 984
 985       my @cond = @{$self->{cond}{-and}};
 986       for (my $i = 0; $i < @cond; $i++) {
 987         my $entry = $cond[$i];
 988
 989         my %hash;
 990         if (ref $entry eq 'HASH') {
 991           foreach my $key (keys %{$entry}) {
 992             $key =~ /([^.]+)$/;
 993             $hash{$1} = $entry->{$key};
 994           }
 995         }
 996         else {
 997           $entry =~ /([^.]+)$/;
 998           $hash{$1} = $cond[++$i];
 999         }
1000
1001         push @{$cond->{-and}}, \%hash;
1002       }
1003     }
1004     else {
1005       foreach my $key (keys %{$self->{cond}}) {
1006         $key =~ /([^.]+)$/;
1007         $cond->{$1} = $self->{cond}{$key};
1008       }
1009     }
1010   }
1011   else {
1012     $self->throw_exception(
1013       "Can't update/delete on resultset with condition unless hash or array"
1014     );
1015   }
1016
1017   return $cond;
1018 }
1019
1020
1021 =head2 update
1022
1023 =over 4
1024
1025 =item Arguments: \%values
1026
1027 =item Return Value: $storage_rv
1028
1029 =back
1030
1031 Sets the specified columns in the resultset to the supplied values in a
1032 single query. Return value will be true if the update succeeded or false
1033 if no records were updated; exact type of success value is storage-dependent.
1034
1035 =cut
1036
1037 sub update {
1038   my ($self, $values) = @_;
1039   $self->throw_exception("Values for update must be a hash")
1040     unless ref $values eq 'HASH';
1041
1042   my $cond = $self->_cond_for_update_delete;
1043
1044   return $self->result_source->storage->update(
1045     $self->result_source->from, $values, $cond
1046   );
1047 }
1048
1049 =head2 update_all
1050
1051 =over 4
1052
1053 =item Arguments: \%values
1054
1055 =item Return Value: 1
1056
1057 =back
1058
1059 Fetches all objects and updates them one at a time. Note that C<update_all>
1060 will run DBIC cascade triggers, while L</update> will not.
1061
1062 =cut
1063
1064 sub update_all {
1065   my ($self, $values) = @_;
1066   $self->throw_exception("Values for update must be a hash")
1067     unless ref $values eq 'HASH';
1068   foreach my $obj ($self->all) {
1069     $obj->set_columns($values)->update;
1070   }
1071   return 1;
1072 }
1073
1074 =head2 delete
1075
1076 =over 4
1077
1078 =item Arguments: none
1079
1080 =item Return Value: 1
1081
1082 =back
1083
1084 Deletes the contents of the resultset from its result source. Note that this
1085 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1086 to run.
1087
1088 =cut
1089
1090 sub delete {
1091   my ($self) = @_;
1092
1093   my $cond = $self->_cond_for_update_delete;
1094
1095   $self->result_source->storage->delete($self->result_source->from, $cond);
1096   return 1;
1097 }
1098
1099 =head2 delete_all
1100
1101 =over 4
1102
1103 =item Arguments: none
1104
1105 =item Return Value: 1
1106
1107 =back
1108
1109 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1110 will run DBIC cascade triggers, while L</delete> will not.
1111
1112 =cut
1113
1114 sub delete_all {
1115   my ($self) = @_;
1116   $_->delete for $self->all;
1117   return 1;
1118 }
1119
1120 =head2 pager
1121
1122 =over 4
1123
1124 =item Arguments: none
1125
1126 =item Return Value: $pager
1127
1128 =back
1129
1130 Return Value a L<Data::Page> object for the current resultset. Only makes
1131 sense for queries with a C<page> attribute.
1132
1133 =cut
1134
1135 sub pager {
1136   my ($self) = @_;
1137   my $attrs = $self->{attrs};
1138   $self->throw_exception("Can't create pager for non-paged rs")
1139     unless $self->{attrs}{page};
1140   $attrs->{rows} ||= 10;
1141   return $self->{pager} ||= Data::Page->new(
1142     $self->_count, $attrs->{rows}, $self->{attrs}{page});
1143 }
1144
1145 =head2 page
1146
1147 =over 4
1148
1149 =item Arguments: $page_number
1150
1151 =item Return Value: $rs
1152
1153 =back
1154
1155 Returns a resultset for the $page_number page of the resultset on which page
1156 is called, where each page contains a number of rows equal to the 'rows'
1157 attribute set on the resultset (10 by default).
1158
1159 =cut
1160
1161 sub page {
1162   my ($self, $page) = @_;
1163   return (ref $self)->new($self->result_source, { %{$self->{attrs}}, page => $page });
1164 }
1165
1166 =head2 new_result
1167
1168 =over 4
1169
1170 =item Arguments: \%vals
1171
1172 =item Return Value: $object
1173
1174 =back
1175
1176 Creates an object in the resultset's result class and returns it.
1177
1178 =cut
1179
1180 sub new_result {
1181   my ($self, $values) = @_;
1182   $self->throw_exception( "new_result needs a hash" )
1183     unless (ref $values eq 'HASH');
1184   $self->throw_exception(
1185     "Can't abstract implicit construct, condition not a hash"
1186   ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1187   my %new = %$values;
1188   my $alias = $self->{attrs}{alias};
1189   foreach my $key (keys %{$self->{cond}||{}}) {
1190     $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1191   }
1192   my $obj = $self->result_class->new(\%new);
1193   $obj->result_source($self->result_source) if $obj->can('result_source');
1194   return $obj;
1195 }
1196
1197 =head2 find_or_new
1198
1199 =over 4
1200
1201 =item Arguments: \%vals, \%attrs?
1202
1203 =item Return Value: $object
1204
1205 =back
1206
1207 Find an existing record from this resultset. If none exists, instantiate a new
1208 result object and return it. The object will not be saved into your storage
1209 until you call L<DBIx::Class::Row/insert> on it.
1210
1211 If you want objects to be saved immediately, use L</find_or_create> instead.
1212
1213 =cut
1214
1215 sub find_or_new {
1216   my $self     = shift;
1217   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1218   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1219   my $exists   = $self->find($hash, $attrs);
1220   return defined $exists ? $exists : $self->new_result($hash);
1221 }
1222
1223 =head2 create
1224
1225 =over 4
1226
1227 =item Arguments: \%vals
1228
1229 =item Return Value: $object
1230
1231 =back
1232
1233 Inserts a record into the resultset and returns the object representing it.
1234
1235 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1236
1237 =cut
1238
1239 sub create {
1240   my ($self, $attrs) = @_;
1241   $self->throw_exception( "create needs a hashref" )
1242     unless ref $attrs eq 'HASH';
1243   return $self->new_result($attrs)->insert;
1244 }
1245
1246 =head2 find_or_create
1247
1248 =over 4
1249
1250 =item Arguments: \%vals, \%attrs?
1251
1252 =item Return Value: $object
1253
1254 =back
1255
1256   $class->find_or_create({ key => $val, ... });
1257
1258 Tries to find a record based on its primary key or unique constraint; if none
1259 is found, creates one and returns that instead.
1260
1261   my $cd = $schema->resultset('CD')->find_or_create({
1262     cdid   => 5,
1263     artist => 'Massive Attack',
1264     title  => 'Mezzanine',
1265     year   => 2005,
1266   });
1267
1268 Also takes an optional C<key> attribute, to search by a specific key or unique
1269 constraint. For example:
1270
1271   my $cd = $schema->resultset('CD')->find_or_create(
1272     {
1273       artist => 'Massive Attack',
1274       title  => 'Mezzanine',
1275     },
1276     { key => 'cd_artist_title' }
1277   );
1278
1279 See also L</find> and L</update_or_create>. For information on how to declare
1280 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1281
1282 =cut
1283
1284 sub find_or_create {
1285   my $self     = shift;
1286   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1287   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
1288   my $exists   = $self->find($hash, $attrs);
1289   return defined $exists ? $exists : $self->create($hash);
1290 }
1291
1292 =head2 update_or_create
1293
1294 =over 4
1295
1296 =item Arguments: \%col_values, { key => $unique_constraint }?
1297
1298 =item Return Value: $object
1299
1300 =back
1301
1302   $class->update_or_create({ col => $val, ... });
1303
1304 First, searches for an existing row matching one of the unique constraints
1305 (including the primary key) on the source of this resultset. If a row is
1306 found, updates it with the other given column values. Otherwise, creates a new
1307 row.
1308
1309 Takes an optional C<key> attribute to search on a specific unique constraint.
1310 For example:
1311
1312   # In your application
1313   my $cd = $schema->resultset('CD')->update_or_create(
1314     {
1315       artist => 'Massive Attack',
1316       title  => 'Mezzanine',
1317       year   => 1998,
1318     },
1319     { key => 'cd_artist_title' }
1320   );
1321
1322 If no C<key> is specified, it searches on all unique constraints defined on the
1323 source, including the primary key.
1324
1325 If the C<key> is specified as C<primary>, it searches only on the primary key.
1326
1327 See also L</find> and L</find_or_create>. For information on how to declare
1328 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1329
1330 =cut
1331
1332 sub update_or_create {
1333   my $self = shift;
1334   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1335   my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
1336
1337   my $row = $self->find($cond);
1338   if (defined $row) {
1339     $row->update($cond);
1340     return $row;
1341   }
1342
1343   return $self->create($cond);
1344 }
1345
1346 =head2 get_cache
1347
1348 =over 4
1349
1350 =item Arguments: none
1351
1352 =item Return Value: \@cache_objects?
1353
1354 =back
1355
1356 Gets the contents of the cache for the resultset, if the cache is set.
1357
1358 =cut
1359
1360 sub get_cache {
1361   shift->{all_cache};
1362 }
1363
1364 =head2 set_cache
1365
1366 =over 4
1367
1368 =item Arguments: \@cache_objects
1369
1370 =item Return Value: \@cache_objects
1371
1372 =back
1373
1374 Sets the contents of the cache for the resultset. Expects an arrayref
1375 of objects of the same class as those produced by the resultset. Note that
1376 if the cache is set the resultset will return the cached objects rather
1377 than re-querying the database even if the cache attr is not set.
1378
1379 =cut
1380
1381 sub set_cache {
1382   my ( $self, $data ) = @_;
1383   $self->throw_exception("set_cache requires an arrayref")
1384       if defined($data) && (ref $data ne 'ARRAY');
1385   $self->{all_cache} = $data;
1386 }
1387
1388 =head2 clear_cache
1389
1390 =over 4
1391
1392 =item Arguments: none
1393
1394 =item Return Value: []
1395
1396 =back
1397
1398 Clears the cache for the resultset.
1399
1400 =cut
1401
1402 sub clear_cache {
1403   shift->set_cache(undef);
1404 }
1405
1406 =head2 related_resultset
1407
1408 =over 4
1409
1410 =item Arguments: $relationship_name
1411
1412 =item Return Value: $resultset
1413
1414 =back
1415
1416 Returns a related resultset for the supplied relationship name.
1417
1418   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1419
1420 =cut
1421
1422 sub related_resultset {
1423   my ($self, $rel) = @_;
1424
1425   $self->{related_resultsets} ||= {};
1426   return $self->{related_resultsets}{$rel} ||= do {
1427     my $rel_obj = $self->result_source->relationship_info($rel);
1428
1429     $self->throw_exception(
1430       "search_related: result source '" . $self->result_source->name .
1431         "' has no such relationship $rel")
1432       unless $rel_obj;
1433
1434     my ($from,$seen) = $self->_resolve_from($rel);
1435
1436     my $join_count = $seen->{$rel};
1437     my $alias = ($join_count > 1 ? join('_', $rel, $join_count) : $rel);
1438
1439     $self->result_source->schema->resultset($rel_obj->{class})->search_rs(
1440       undef, {
1441         %{$self->{attrs}||{}},
1442         join => undef,
1443         prefetch => undef,
1444         select => undef,
1445         as => undef,
1446         alias => $alias,
1447         where => $self->{cond},
1448         seen_join => $seen,
1449         from => $from,
1450     });
1451   };
1452 }
1453
1454 sub _resolve_from {
1455   my ($self, $extra_join) = @_;
1456   my $source = $self->result_source;
1457   my $attrs = $self->{attrs};
1458
1459   my $from = $attrs->{from}
1460     || [ { $attrs->{alias} => $source->from } ];
1461
1462   my $seen = { %{$attrs->{seen_join}||{}} };
1463
1464   my $join = ($attrs->{join}
1465                ? [ $attrs->{join}, $extra_join ]
1466                : $extra_join);
1467   $from = [
1468     @$from,
1469     ($join ? $source->resolve_join($join, $attrs->{alias}, $seen) : ()),
1470   ];
1471
1472   return ($from,$seen);
1473 }
1474
1475 sub _resolved_attrs {
1476   my $self = shift;
1477   return $self->{_attrs} if $self->{_attrs};
1478
1479   my $attrs = { %{$self->{attrs}||{}} };
1480   my $source = $self->{result_source};
1481   my $alias = $attrs->{alias};
1482
1483   $attrs->{columns} ||= delete $attrs->{cols} if exists $attrs->{cols};
1484   if ($attrs->{columns}) {
1485     delete $attrs->{as};
1486   } elsif (!$attrs->{select}) {
1487     $attrs->{columns} = [ $source->columns ];
1488   }
1489
1490   $attrs->{select} =
1491     ($attrs->{select}
1492       ? (ref $attrs->{select} eq 'ARRAY'
1493           ? [ @{$attrs->{select}} ]
1494           : [ $attrs->{select} ])
1495       : [ map { m/\./ ? $_ : "${alias}.$_" } @{delete $attrs->{columns}} ]
1496     );
1497   $attrs->{as} =
1498     ($attrs->{as}
1499       ? (ref $attrs->{as} eq 'ARRAY'
1500           ? [ @{$attrs->{as}} ]
1501           : [ $attrs->{as} ])
1502       : [ map { m/^\Q${alias}.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}} ]
1503     );
1504
1505   my $adds;
1506   if ($adds = delete $attrs->{include_columns}) {
1507     $adds = [$adds] unless ref $adds eq 'ARRAY';
1508     push(@{$attrs->{select}}, @$adds);
1509     push(@{$attrs->{as}}, map { m/([^.]+)$/; $1 } @$adds);
1510   }
1511   if ($adds = delete $attrs->{'+select'}) {
1512     $adds = [$adds] unless ref $adds eq 'ARRAY';
1513     push(@{$attrs->{select}},
1514            map { /\./ || ref $_ ? $_ : "${alias}.$_" } @$adds);
1515   }
1516   if (my $adds = delete $attrs->{'+as'}) {
1517     $adds = [$adds] unless ref $adds eq 'ARRAY';
1518     push(@{$attrs->{as}}, @$adds);
1519   }
1520
1521   $attrs->{from} ||= [ { 'me' => $source->from } ];
1522
1523   if (exists $attrs->{join} || exists $attrs->{prefetch}) {
1524     my $join = delete $attrs->{join} || {};
1525
1526     if (defined $attrs->{prefetch}) {
1527       $join = $self->_merge_attr(
1528         $join, $attrs->{prefetch}
1529       );
1530     }
1531
1532     $attrs->{from} =   # have to copy here to avoid corrupting the original
1533       [
1534         @{$attrs->{from}},
1535         $source->resolve_join($join, $alias, { %{$attrs->{seen_join}||{}} })
1536       ];
1537   }
1538
1539   $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
1540   if ($attrs->{order_by}) {
1541     $attrs->{order_by} = (ref($attrs->{order_by}) eq 'ARRAY'
1542                            ? [ @{$attrs->{order_by}} ]
1543                            : [ $attrs->{order_by} ]);
1544   } else {
1545     $attrs->{order_by} = [];
1546   }
1547
1548   my $collapse = $attrs->{collapse} || {};
1549   if (my $prefetch = delete $attrs->{prefetch}) {
1550     my @pre_order;
1551     foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
1552       # bring joins back to level of current class
1553       my @prefetch = $source->resolve_prefetch(
1554         $p, $alias, { %{$attrs->{seen_join}||{}} }, \@pre_order, $collapse
1555       );
1556       push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
1557       push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
1558     }
1559     push(@{$attrs->{order_by}}, @pre_order);
1560   }
1561   $attrs->{collapse} = $collapse;
1562
1563   return $self->{_attrs} = $attrs;
1564 }
1565
1566 sub _merge_attr {
1567   my ($self, $a, $b) = @_;
1568   return $b unless $a;
1569
1570   if (ref $b eq 'HASH' && ref $a eq 'HASH') {
1571     foreach my $key (keys %{$b}) {
1572       if (exists $a->{$key}) {
1573         $a->{$key} = $self->_merge_attr($a->{$key}, $b->{$key});
1574       } else {
1575         $a->{$key} = $b->{$key};
1576       }
1577     }
1578     return $a;
1579   } else {
1580     $a = [$a] unless ref $a eq 'ARRAY';
1581     $b = [$b] unless ref $b eq 'ARRAY';
1582
1583     my $hash = {};
1584     my @array;
1585     foreach my $x ($a, $b) {
1586       foreach my $element (@{$x}) {
1587         if (ref $element eq 'HASH') {
1588           $hash = $self->_merge_attr($hash, $element);
1589         } elsif (ref $element eq 'ARRAY') {
1590           push(@array, @{$element});
1591         } else {
1592           push(@array, $element) unless $b == $x
1593             && grep { $_ eq $element } @array;
1594         }
1595       }
1596     }
1597
1598     @array = grep { !exists $hash->{$_} } @array;
1599
1600     return keys %{$hash}
1601       ? ( scalar(@array)
1602             ? [$hash, @array]
1603             : $hash
1604         )
1605       : \@array;
1606   }
1607 }
1608
1609 =head2 throw_exception
1610
1611 See L<DBIx::Class::Schema/throw_exception> for details.
1612
1613 =cut
1614
1615 sub throw_exception {
1616   my $self=shift;
1617   $self->result_source->schema->throw_exception(@_);
1618 }
1619
1620 # XXX: FIXME: Attributes docs need clearing up
1621
1622 =head1 ATTRIBUTES
1623
1624 The resultset takes various attributes that modify its behavior. Here's an
1625 overview of them:
1626
1627 =head2 order_by
1628
1629 =over 4
1630
1631 =item Value: ($order_by | \@order_by)
1632
1633 =back
1634
1635 Which column(s) to order the results by. This is currently passed
1636 through directly to SQL, so you can give e.g. C<year DESC> for a
1637 descending order on the column `year'.
1638
1639 Please note that if you have quoting enabled (see
1640 L<DBIx::Class::Storage/quote_char>) you will need to do C<\'year DESC' > to
1641 specify an order. (The scalar ref causes it to be passed as raw sql to the DB,
1642 so you will need to manually quote things as appropriate.)
1643
1644 =head2 columns
1645
1646 =over 4
1647
1648 =item Value: \@columns
1649
1650 =back
1651
1652 Shortcut to request a particular set of columns to be retrieved.  Adds
1653 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1654 from that, then auto-populates C<as> from C<select> as normal. (You may also
1655 use the C<cols> attribute, as in earlier versions of DBIC.)
1656
1657 =head2 include_columns
1658
1659 =over 4
1660
1661 =item Value: \@columns
1662
1663 =back
1664
1665 Shortcut to include additional columns in the returned results - for example
1666
1667   $schema->resultset('CD')->search(undef, {
1668     include_columns => ['artist.name'],
1669     join => ['artist']
1670   });
1671
1672 would return all CDs and include a 'name' column to the information
1673 passed to object inflation
1674
1675 =head2 select
1676
1677 =over 4
1678
1679 =item Value: \@select_columns
1680
1681 =back
1682
1683 Indicates which columns should be selected from the storage. You can use
1684 column names, or in the case of RDBMS back ends, function or stored procedure
1685 names:
1686
1687   $rs = $schema->resultset('Employee')->search(undef, {
1688     select => [
1689       'name',
1690       { count => 'employeeid' },
1691       { sum => 'salary' }
1692     ]
1693   });
1694
1695 When you use function/stored procedure names and do not supply an C<as>
1696 attribute, the column names returned are storage-dependent. E.g. MySQL would
1697 return a column named C<count(employeeid)> in the above example.
1698
1699 =head2 +select
1700
1701 =over 4
1702
1703 Indicates additional columns to be selected from storage.  Works the same as
1704 L<select> but adds columns to the selection.
1705
1706 =back
1707
1708 =head2 +as
1709
1710 =over 4
1711
1712 Indicates additional column names for those added via L<+select>.
1713
1714 =back
1715
1716 =head2 as
1717
1718 =over 4
1719
1720 =item Value: \@inflation_names
1721
1722 =back
1723
1724 Indicates column names for object inflation. This is used in conjunction with
1725 C<select>, usually when C<select> contains one or more function or stored
1726 procedure names:
1727
1728   $rs = $schema->resultset('Employee')->search(undef, {
1729     select => [
1730       'name',
1731       { count => 'employeeid' }
1732     ],
1733     as => ['name', 'employee_count'],
1734   });
1735
1736   my $employee = $rs->first(); # get the first Employee
1737
1738 If the object against which the search is performed already has an accessor
1739 matching a column name specified in C<as>, the value can be retrieved using
1740 the accessor as normal:
1741
1742   my $name = $employee->name();
1743
1744 If on the other hand an accessor does not exist in the object, you need to
1745 use C<get_column> instead:
1746
1747   my $employee_count = $employee->get_column('employee_count');
1748
1749 You can create your own accessors if required - see
1750 L<DBIx::Class::Manual::Cookbook> for details.
1751
1752 Please note: This will NOT insert an C<AS employee_count> into the SQL statement
1753 produced, it is used for internal access only. Thus attempting to use the accessor
1754 in an C<order_by> clause or similar will fail misrably.
1755
1756 =head2 join
1757
1758 =over 4
1759
1760 =item Value: ($rel_name | \@rel_names | \%rel_names)
1761
1762 =back
1763
1764 Contains a list of relationships that should be joined for this query.  For
1765 example:
1766
1767   # Get CDs by Nine Inch Nails
1768   my $rs = $schema->resultset('CD')->search(
1769     { 'artist.name' => 'Nine Inch Nails' },
1770     { join => 'artist' }
1771   );
1772
1773 Can also contain a hash reference to refer to the other relation's relations.
1774 For example:
1775
1776   package MyApp::Schema::Track;
1777   use base qw/DBIx::Class/;
1778   __PACKAGE__->table('track');
1779   __PACKAGE__->add_columns(qw/trackid cd position title/);
1780   __PACKAGE__->set_primary_key('trackid');
1781   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1782   1;
1783
1784   # In your application
1785   my $rs = $schema->resultset('Artist')->search(
1786     { 'track.title' => 'Teardrop' },
1787     {
1788       join     => { cd => 'track' },
1789       order_by => 'artist.name',
1790     }
1791   );
1792
1793 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1794 similarly for a third time). For e.g.
1795
1796   my $rs = $schema->resultset('Artist')->search({
1797     'cds.title'   => 'Down to Earth',
1798     'cds_2.title' => 'Popular',
1799   }, {
1800     join => [ qw/cds cds/ ],
1801   });
1802
1803 will return a set of all artists that have both a cd with title 'Down
1804 to Earth' and a cd with title 'Popular'.
1805
1806 If you want to fetch related objects from other tables as well, see C<prefetch>
1807 below.
1808
1809 =head2 prefetch
1810
1811 =over 4
1812
1813 =item Value: ($rel_name | \@rel_names | \%rel_names)
1814
1815 =back
1816
1817 Contains one or more relationships that should be fetched along with the main
1818 query (when they are accessed afterwards they will have already been
1819 "prefetched").  This is useful for when you know you will need the related
1820 objects, because it saves at least one query:
1821
1822   my $rs = $schema->resultset('Tag')->search(
1823     undef,
1824     {
1825       prefetch => {
1826         cd => 'artist'
1827       }
1828     }
1829   );
1830
1831 The initial search results in SQL like the following:
1832
1833   SELECT tag.*, cd.*, artist.* FROM tag
1834   JOIN cd ON tag.cd = cd.cdid
1835   JOIN artist ON cd.artist = artist.artistid
1836
1837 L<DBIx::Class> has no need to go back to the database when we access the
1838 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1839 case.
1840
1841 Simple prefetches will be joined automatically, so there is no need
1842 for a C<join> attribute in the above search. If you're prefetching to
1843 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1844 specify the join as well.
1845
1846 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1847 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1848 with an accessor type of 'single' or 'filter').
1849
1850 =head2 page
1851
1852 =over 4
1853
1854 =item Value: $page
1855
1856 =back
1857
1858 Makes the resultset paged and specifies the page to retrieve. Effectively
1859 identical to creating a non-pages resultset and then calling ->page($page)
1860 on it.
1861
1862 If L<rows> attribute is not specified it defualts to 10 rows per page.
1863
1864 =head2 rows
1865
1866 =over 4
1867
1868 =item Value: $rows
1869
1870 =back
1871
1872 Specifes the maximum number of rows for direct retrieval or the number of
1873 rows per page if the page attribute or method is used.
1874
1875 =head2 offset
1876
1877 =over 4
1878
1879 =item Value: $offset
1880
1881 =back
1882
1883 Specifies the (zero-based) row number for the  first row to be returned, or the
1884 of the first row of the first page if paging is used.
1885
1886 =head2 group_by
1887
1888 =over 4
1889
1890 =item Value: \@columns
1891
1892 =back
1893
1894 A arrayref of columns to group by. Can include columns of joined tables.
1895
1896   group_by => [qw/ column1 column2 ... /]
1897
1898 =head2 having
1899
1900 =over 4
1901
1902 =item Value: $condition
1903
1904 =back
1905
1906 HAVING is a select statement attribute that is applied between GROUP BY and
1907 ORDER BY. It is applied to the after the grouping calculations have been
1908 done.
1909
1910   having => { 'count(employee)' => { '>=', 100 } }
1911
1912 =head2 distinct
1913
1914 =over 4
1915
1916 =item Value: (0 | 1)
1917
1918 =back
1919
1920 Set to 1 to group by all columns.
1921
1922 =head2 where
1923
1924 =over 4
1925
1926 Adds to the WHERE clause.
1927
1928   # only return rows WHERE deleted IS NULL for all searches
1929   __PACKAGE__->resultset_attributes({ where => { deleted => undef } }); )
1930
1931 Can be overridden by passing C<{ where => undef }> as an attribute
1932 to a resulset.
1933
1934 =back
1935
1936 =head2 cache
1937
1938 Set to 1 to cache search results. This prevents extra SQL queries if you
1939 revisit rows in your ResultSet:
1940
1941   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1942
1943   while( my $artist = $resultset->next ) {
1944     ... do stuff ...
1945   }
1946
1947   $rs->first; # without cache, this would issue a query
1948
1949 By default, searches are not cached.
1950
1951 For more examples of using these attributes, see
1952 L<DBIx::Class::Manual::Cookbook>.
1953
1954 =head2 from
1955
1956 =over 4
1957
1958 =item Value: \@from_clause
1959
1960 =back
1961
1962 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1963 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1964 clauses.
1965
1966 NOTE: Use this on your own risk.  This allows you to shoot off your foot!
1967
1968 C<join> will usually do what you need and it is strongly recommended that you
1969 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1970 And we really do mean "cannot", not just tried and failed. Attempting to use
1971 this because you're having problems with C<join> is like trying to use x86
1972 ASM because you've got a syntax error in your C. Trust us on this.
1973
1974 Now, if you're still really, really sure you need to use this (and if you're
1975 not 100% sure, ask the mailing list first), here's an explanation of how this
1976 works.
1977
1978 The syntax is as follows -
1979
1980   [
1981     { <alias1> => <table1> },
1982     [
1983       { <alias2> => <table2>, -join_type => 'inner|left|right' },
1984       [], # nested JOIN (optional)
1985       { <table1.column1> => <table2.column2>, ... (more conditions) },
1986     ],
1987     # More of the above [ ] may follow for additional joins
1988   ]
1989
1990   <table1> <alias1>
1991   JOIN
1992     <table2> <alias2>
1993     [JOIN ...]
1994   ON <table1.column1> = <table2.column2>
1995   <more joins may follow>
1996
1997 An easy way to follow the examples below is to remember the following:
1998
1999     Anything inside "[]" is a JOIN
2000     Anything inside "{}" is a condition for the enclosing JOIN
2001
2002 The following examples utilize a "person" table in a family tree application.
2003 In order to express parent->child relationships, this table is self-joined:
2004
2005     # Person->belongs_to('father' => 'Person');
2006     # Person->belongs_to('mother' => 'Person');
2007
2008 C<from> can be used to nest joins. Here we return all children with a father,
2009 then search against all mothers of those children:
2010
2011   $rs = $schema->resultset('Person')->search(
2012       undef,
2013       {
2014           alias => 'mother', # alias columns in accordance with "from"
2015           from => [
2016               { mother => 'person' },
2017               [
2018                   [
2019                       { child => 'person' },
2020                       [
2021                           { father => 'person' },
2022                           { 'father.person_id' => 'child.father_id' }
2023                       ]
2024                   ],
2025                   { 'mother.person_id' => 'child.mother_id' }
2026               ],
2027           ]
2028       },
2029   );
2030
2031   # Equivalent SQL:
2032   # SELECT mother.* FROM person mother
2033   # JOIN (
2034   #   person child
2035   #   JOIN person father
2036   #   ON ( father.person_id = child.father_id )
2037   # )
2038   # ON ( mother.person_id = child.mother_id )
2039
2040 The type of any join can be controlled manually. To search against only people
2041 with a father in the person table, we could explicitly use C<INNER JOIN>:
2042
2043     $rs = $schema->resultset('Person')->search(
2044         undef,
2045         {
2046             alias => 'child', # alias columns in accordance with "from"
2047             from => [
2048                 { child => 'person' },
2049                 [
2050                     { father => 'person', -join_type => 'inner' },
2051                     { 'father.id' => 'child.father_id' }
2052                 ],
2053             ]
2054         },
2055     );
2056
2057     # Equivalent SQL:
2058     # SELECT child.* FROM person child
2059     # INNER JOIN person father ON child.father_id = father.id
2060
2061 =cut
2062
2063 1;