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