lib/DBIx/Class/ResultSet.pm

   1 package DBIx::Class::ResultSet;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/DBIx::Class/;
   6 use DBIx::Class::Carp;
   7 use DBIx::Class::ResultSetColumn;
   8 use DBIx::Class::ResultClass::HashRefInflator;
   9 use Scalar::Util qw/blessed weaken reftype/;
  10 use DBIx::Class::_Util qw(
  11   fail_on_internal_wantarray fail_on_internal_call UNRESOLVABLE_CONDITION
  12 );
  13 use Try::Tiny;
  14
  15 # not importing first() as it will clash with our own method
  16 use List::Util ();
  17
  18 BEGIN {
  19   # De-duplication in _merge_attr() is disabled, but left in for reference
  20   # (the merger is used for other things that ought not to be de-duped)
  21   *__HM_DEDUP = sub () { 0 };
  22 }
  23
  24 use namespace::clean;
  25
  26 use overload
  27         '0+'     => "count",
  28         'bool'   => "_bool",
  29         fallback => 1;
  30
  31 # this is real - CDBICompat overrides it with insanity
  32 # yes, prototype won't matter, but that's for now ;)
  33 sub _bool () { 1 }
  34
  35 __PACKAGE__->mk_group_accessors('simple' => qw/_result_class result_source/);
  36
  37 =head1 NAME
  38
  39 DBIx::Class::ResultSet - Represents a query used for fetching a set of results.
  40
  41 =head1 SYNOPSIS
  42
  43   my $users_rs = $schema->resultset('User');
  44   while( $user = $users_rs->next) {
  45     print $user->username;
  46   }
  47
  48   my $registered_users_rs = $schema->resultset('User')->search({ registered => 1 });
  49   my @cds_in_2005 = $schema->resultset('CD')->search({ year => 2005 })->all();
  50
  51 =head1 DESCRIPTION
  52
  53 A ResultSet is an object which stores a set of conditions representing
  54 a query. It is the backbone of DBIx::Class (i.e. the really
  55 important/useful bit).
  56
  57 No SQL is executed on the database when a ResultSet is created, it
  58 just stores all the conditions needed to create the query.
  59
  60 A basic ResultSet representing the data of an entire table is returned
  61 by calling C<resultset> on a L<DBIx::Class::Schema> and passing in a
  62 L<Source|DBIx::Class::Manual::Glossary/ResultSource> name.
  63
  64   my $users_rs = $schema->resultset('User');
  65
  66 A new ResultSet is returned from calling L</search> on an existing
  67 ResultSet. The new one will contain all the conditions of the
  68 original, plus any new conditions added in the C<search> call.
  69
  70 A ResultSet also incorporates an implicit iterator. L</next> and L</reset>
  71 can be used to walk through all the L<DBIx::Class::Row>s the ResultSet
  72 represents.
  73
  74 The query that the ResultSet represents is B<only> executed against
  75 the database when these methods are called:
  76 L</find>, L</next>, L</all>, L</first>, L</single>, L</count>.
  77
  78 If a resultset is used in a numeric context it returns the L</count>.
  79 However, if it is used in a boolean context it is B<always> true.  So if
  80 you want to check if a resultset has any results, you must use C<if $rs
  81 != 0>.
  82
  83 =head1 EXAMPLES
  84
  85 =head2 Chaining resultsets
  86
  87 Let's say you've got a query that needs to be run to return some data
  88 to the user. But, you have an authorization system in place that
  89 prevents certain users from seeing certain information. So, you want
  90 to construct the basic query in one method, but add constraints to it in
  91 another.
  92
  93   sub get_data {
  94     my $self = shift;
  95     my $request = $self->get_request; # Get a request object somehow.
  96     my $schema = $self->result_source->schema;
  97
  98     my $cd_rs = $schema->resultset('CD')->search({
  99       title => $request->param('title'),
 100       year => $request->param('year'),
 101     });
 102
 103     $cd_rs = $self->apply_security_policy( $cd_rs );
 104
 105     return $cd_rs->all();
 106   }
 107
 108   sub apply_security_policy {
 109     my $self = shift;
 110     my ($rs) = @_;
 111
 112     return $rs->search({
 113       subversive => 0,
 114     });
 115   }
 116
 117 =head3 Resolving conditions and attributes
 118
 119 When a resultset is chained from another resultset (e.g.:
 120 C<< my $new_rs = $old_rs->search(\%extra_cond, \%attrs) >>), conditions
 121 and attributes with the same keys need resolving.
 122
 123 If any of L</columns>, L</select>, L</as> are present, they reset the
 124 original selection, and start the selection "clean".
 125
 126 The L</join>, L</prefetch>, L</+columns>, L</+select>, L</+as> attributes
 127 are merged into the existing ones from the original resultset.
 128
 129 The L</where> and L</having> attributes, and any search conditions, are
 130 merged with an SQL C<AND> to the existing condition from the original
 131 resultset.
 132
 133 All other attributes are overridden by any new ones supplied in the
 134 search attributes.
 135
 136 =head2 Multiple queries
 137
 138 Since a resultset just defines a query, you can do all sorts of
 139 things with it with the same object.
 140
 141   # Don't hit the DB yet.
 142   my $cd_rs = $schema->resultset('CD')->search({
 143     title => 'something',
 144     year => 2009,
 145   });
 146
 147   # Each of these hits the DB individually.
 148   my $count = $cd_rs->count;
 149   my $most_recent = $cd_rs->get_column('date_released')->max();
 150   my @records = $cd_rs->all;
 151
 152 And it's not just limited to SELECT statements.
 153
 154   $cd_rs->delete();
 155
 156 This is even cooler:
 157
 158   $cd_rs->create({ artist => 'Fred' });
 159
 160 Which is the same as:
 161
 162   $schema->resultset('CD')->create({
 163     title => 'something',
 164     year => 2009,
 165     artist => 'Fred'
 166   });
 167
 168 See: L</search>, L</count>, L</get_column>, L</all>, L</create>.
 169
 170 =head2 Custom ResultSet classes
 171
 172 To add methods to your resultsets, you can subclass L<DBIx::Class::ResultSet>, similar to:
 173
 174   package MyApp::Schema::ResultSet::User;
 175
 176   use strict;
 177   use warnings;
 178
 179   use base 'DBIx::Class::ResultSet';
 180
 181   sub active {
 182     my $self = shift;
 183     $self->search({ $self->current_source_alias . '.active' => 1 });
 184   }
 185
 186   sub unverified {
 187     my $self = shift;
 188     $self->search({ $self->current_source_alias . '.verified' => 0 });
 189   }
 190
 191   sub created_n_days_ago {
 192     my ($self, $days_ago) = @_;
 193     $self->search({
 194       $self->current_source_alias . '.create_date' => {
 195         '<=',
 196       $self->result_source->schema->storage->datetime_parser->format_datetime(
 197         DateTime->now( time_zone => 'UTC' )->subtract( days => $days_ago )
 198       )}
 199     });
 200   }
 201
 202   sub users_to_warn { shift->active->unverified->created_n_days_ago(7) }
 203
 204   1;
 205
 206 See L<DBIx::Class::Schema/load_namespaces> on how DBIC can discover and
 207 automatically attach L<Result|DBIx::Class::Manual::ResultClass>-specific
 208 L<ResulSet|DBIx::Class::ResultSet> classes.
 209
 210 =head3 ResultSet subclassing with Moose and similar constructor-providers
 211
 212 Using L<Moose> or L<Moo> in your ResultSet classes is usually overkill, but
 213 you may find it useful if your ResultSets contain a lot of business logic
 214 (e.g. C<has xml_parser>, C<has json>, etc) or if you just prefer to organize
 215 your code via roles.
 216
 217 In order to write custom ResultSet classes with L<Moo> you need to use the
 218 following template. The L<BUILDARGS|Moo/BUILDARGS> is necessary due to the
 219 unusual signature of the L<constructor provided by DBIC
 220 |DBIx::Class::ResultSet/new> C<< ->new($source, \%args) >>.
 221
 222   use Moo;
 223   extends 'DBIx::Class::ResultSet';
 224   sub BUILDARGS { $_[2] } # ::RS::new() expects my ($class, $rsrc, $args) = @_
 225
 226   ...your code...
 227
 228   1;
 229
 230 If you want to build your custom ResultSet classes with L<Moose>, you need
 231 a similar, though a little more elaborate template in order to interface the
 232 inlining of the L<Moose>-provided
 233 L<object constructor|Moose::Manual::Construction/WHERE'S THE CONSTRUCTOR?>,
 234 with the DBIC one.
 235
 236   package MyApp::Schema::ResultSet::User;
 237
 238   use Moose;
 239   use MooseX::NonMoose;
 240   extends 'DBIx::Class::ResultSet';
 241
 242   sub BUILDARGS { $_[2] } # ::RS::new() expects my ($class, $rsrc, $args) = @_
 243
 244   ...your code...
 245
 246   __PACKAGE__->meta->make_immutable;
 247
 248   1;
 249
 250 The L<MooseX::NonMoose> is necessary so that the L<Moose> constructor does not
 251 entirely overwrite the DBIC one (in contrast L<Moo> does this automatically).
 252 Alternatively, you can skip L<MooseX::NonMoose> and get by with just L<Moose>
 253 instead by doing:
 254
 255   __PACKAGE__->meta->make_immutable(inline_constructor => 0);
 256
 257 =head1 METHODS
 258
 259 =head2 new
 260
 261 =over 4
 262
 263 =item Arguments: L<$source|DBIx::Class::ResultSource>, L<\%attrs?|/ATTRIBUTES>
 264
 265 =item Return Value: L<$resultset|/search>
 266
 267 =back
 268
 269 The resultset constructor. Takes a source object (usually a
 270 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
 271 L</ATTRIBUTES> below).  Does not perform any queries -- these are
 272 executed as needed by the other methods.
 273
 274 Generally you never construct a resultset manually. Instead you get one
 275 from e.g. a
 276 C<< $schema->L<resultset|DBIx::Class::Schema/resultset>('$source_name') >>
 277 or C<< $another_resultset->L<search|/search>(...) >> (the later called in
 278 scalar context):
 279
 280   my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
 281
 282 =over
 283
 284 =item WARNING
 285
 286 If called on an object, proxies to L</new_result> instead, so
 287
 288   my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
 289
 290 will return a CD object, not a ResultSet, and is equivalent to:
 291
 292   my $cd = $schema->resultset('CD')->new_result({ title => 'Spoon' });
 293
 294 Please also keep in mind that many internals call L</new_result> directly,
 295 so overloading this method with the idea of intercepting new result object
 296 creation B<will not work>. See also warning pertaining to L</create>.
 297
 298 =back
 299
 300 =cut
 301
 302 sub new {
 303   my $class = shift;
 304
 305   if (ref $class) {
 306     DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
 307     return $class->new_result(@_);
 308   }
 309
 310   my ($source, $attrs) = @_;
 311   $source = $source->resolve
 312     if $source->isa('DBIx::Class::ResultSourceHandle');
 313
 314   $attrs = { %{$attrs||{}} };
 315   delete @{$attrs}{qw(_last_sqlmaker_alias_map _simple_passthrough_construction)};
 316
 317   if ($attrs->{page}) {
 318     $attrs->{rows} ||= 10;
 319   }
 320
 321   $attrs->{alias} ||= 'me';
 322
 323   my $self = bless {
 324     result_source => $source,
 325     cond => $attrs->{where},
 326     pager => undef,
 327     attrs => $attrs,
 328   }, $class;
 329
 330   # if there is a dark selector, this means we are already in a
 331   # chain and the cleanup/sanification was taken care of by
 332   # _search_rs already
 333   $self->_normalize_selection($attrs)
 334     unless $attrs->{_dark_selector};
 335
 336   $self->result_class(
 337     $attrs->{result_class} || $source->result_class
 338   );
 339
 340   $self;
 341 }
 342
 343 =head2 search
 344
 345 =over 4
 346
 347 =item Arguments: L<$cond|DBIx::Class::SQLMaker> | undef, L<\%attrs?|/ATTRIBUTES>
 348
 349 =item Return Value: $resultset (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 350
 351 =back
 352
 353   my @cds    = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
 354   my $new_rs = $cd_rs->search({ year => 2005 });
 355
 356   my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
 357                  # year = 2005 OR year = 2004
 358
 359 In list context, C<< ->all() >> is called implicitly on the resultset, thus
 360 returning a list of L<result|DBIx::Class::Manual::ResultClass> objects instead.
 361 To avoid that, use L</search_rs>.
 362
 363 If you need to pass in additional attributes but no additional condition,
 364 call it as C<search(undef, \%attrs)>.
 365
 366   # "SELECT name, artistid FROM $artist_table"
 367   my @all_artists = $schema->resultset('Artist')->search(undef, {
 368     columns => [qw/name artistid/],
 369   });
 370
 371 For a list of attributes that can be passed to C<search>, see
 372 L</ATTRIBUTES>. For more examples of using this function, see
 373 L<Searching|DBIx::Class::Manual::Cookbook/SEARCHING>. For a complete
 374 documentation for the first argument, see L<SQL::Abstract/"WHERE CLAUSES">
 375 and its extension L<DBIx::Class::SQLMaker>.
 376
 377 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
 378
 379 =head3 CAVEAT
 380
 381 Note that L</search> does not process/deflate any of the values passed in the
 382 L<SQL::Abstract>-compatible search condition structure. This is unlike other
 383 condition-bound methods L</new_result>, L</create> and L</find>. The user must ensure
 384 manually that any value passed to this method will stringify to something the
 385 RDBMS knows how to deal with. A notable example is the handling of L<DateTime>
 386 objects, for more info see:
 387 L<DBIx::Class::Manual::Cookbook/Formatting DateTime objects in queries>.
 388
 389 =cut
 390
 391 sub search {
 392   my $self = shift;
 393   my $rs = $self->search_rs( @_ );
 394
 395   if (wantarray) {
 396     DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_WANTARRAY and my $sog = fail_on_internal_wantarray;
 397     return $rs->all;
 398   }
 399   elsif (defined wantarray) {
 400     return $rs;
 401   }
 402   else {
 403     # we can be called by a relationship helper, which in
 404     # turn may be called in void context due to some braindead
 405     # overload or whatever else the user decided to be clever
 406     # at this particular day. Thus limit the exception to
 407     # external code calls only
 408     $self->throw_exception ('->search is *not* a mutator, calling it in void context makes no sense')
 409       if (caller)[0] !~ /^\QDBIx::Class::/;
 410
 411     return ();
 412   }
 413 }
 414
 415 =head2 search_rs
 416
 417 =over 4
 418
 419 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
 420
 421 =item Return Value: L<$resultset|/search>
 422
 423 =back
 424
 425 This method does the same exact thing as search() except it will
 426 always return a resultset, even in list context.
 427
 428 =cut
 429
 430 sub search_rs {
 431   my $self = shift;
 432
 433   my $rsrc = $self->result_source;
 434   my ($call_cond, $call_attrs);
 435
 436   # Special-case handling for (undef, undef) or (undef)
 437   # Note that (foo => undef) is valid deprecated syntax
 438   @_ = () if not scalar grep { defined $_ } @_;
 439
 440   # just a cond
 441   if (@_ == 1) {
 442     $call_cond = shift;
 443   }
 444   # fish out attrs in the ($condref, $attr) case
 445   elsif (@_ == 2 and ( ! defined $_[0] or (ref $_[0]) ne '') ) {
 446     ($call_cond, $call_attrs) = @_;
 447   }
 448   elsif (@_ % 2) {
 449     $self->throw_exception('Odd number of arguments to search')
 450   }
 451   # legacy search
 452   elsif (@_) {
 453     carp_unique 'search( %condition ) is deprecated, use search( \%condition ) instead'
 454       unless $rsrc->result_class->isa('DBIx::Class::CDBICompat');
 455
 456     for my $i (0 .. $#_) {
 457       next if $i % 2;
 458       $self->throw_exception ('All keys in condition key/value pairs must be plain scalars')
 459         if (! defined $_[$i] or ref $_[$i] ne '');
 460     }
 461
 462     $call_cond = { @_ };
 463   }
 464
 465   # see if we can keep the cache (no $rs changes)
 466   my $cache;
 467   my %safe = (alias => 1, cache => 1);
 468   if ( ! List::Util::first { !$safe{$_} } keys %$call_attrs and (
 469     ! defined $call_cond
 470       or
 471     ref $call_cond eq 'HASH' && ! keys %$call_cond
 472       or
 473     ref $call_cond eq 'ARRAY' && ! @$call_cond
 474   )) {
 475     $cache = $self->get_cache;
 476   }
 477
 478   my $old_attrs = { %{$self->{attrs}} };
 479   my ($old_having, $old_where) = delete @{$old_attrs}{qw(having where)};
 480
 481   my $new_attrs = { %$old_attrs };
 482
 483   # take care of call attrs (only if anything is changing)
 484   if ($call_attrs and keys %$call_attrs) {
 485
 486     # copy for _normalize_selection
 487     $call_attrs = { %$call_attrs };
 488
 489     my @selector_attrs = qw/select as columns cols +select +as +columns include_columns/;
 490
 491     # reset the current selector list if new selectors are supplied
 492     if (List::Util::first { exists $call_attrs->{$_} } qw/columns cols select as/) {
 493       delete @{$old_attrs}{(@selector_attrs, '_dark_selector')};
 494     }
 495
 496     # Normalize the new selector list (operates on the passed-in attr structure)
 497     # Need to do it on every chain instead of only once on _resolved_attrs, in
 498     # order to allow detection of empty vs partial 'as'
 499     $call_attrs->{_dark_selector} = $old_attrs->{_dark_selector}
 500       if $old_attrs->{_dark_selector};
 501     $self->_normalize_selection ($call_attrs);
 502
 503     # start with blind overwriting merge, exclude selector attrs
 504     $new_attrs = { %{$old_attrs}, %{$call_attrs} };
 505     delete @{$new_attrs}{@selector_attrs};
 506
 507     for (@selector_attrs) {
 508       $new_attrs->{$_} = $self->_merge_attr($old_attrs->{$_}, $call_attrs->{$_})
 509         if ( exists $old_attrs->{$_} or exists $call_attrs->{$_} );
 510     }
 511
 512     # older deprecated name, use only if {columns} is not there
 513     if (my $c = delete $new_attrs->{cols}) {
 514       carp_unique( "Resultset attribute 'cols' is deprecated, use 'columns' instead" );
 515       if ($new_attrs->{columns}) {
 516         carp "Resultset specifies both the 'columns' and the legacy 'cols' attributes - ignoring 'cols'";
 517       }
 518       else {
 519         $new_attrs->{columns} = $c;
 520       }
 521     }
 522
 523
 524     # join/prefetch use their own crazy merging heuristics
 525     foreach my $key (qw/join prefetch/) {
 526       $new_attrs->{$key} = $self->_merge_joinpref_attr($old_attrs->{$key}, $call_attrs->{$key})
 527         if exists $call_attrs->{$key};
 528     }
 529
 530     # stack binds together
 531     $new_attrs->{bind} = [ @{ $old_attrs->{bind} || [] }, @{ $call_attrs->{bind} || [] } ];
 532   }
 533
 534
 535   for ($old_where, $call_cond) {
 536     if (defined $_) {
 537       $new_attrs->{where} = $self->_stack_cond (
 538         $_, $new_attrs->{where}
 539       );
 540     }
 541   }
 542
 543   if (defined $old_having) {
 544     $new_attrs->{having} = $self->_stack_cond (
 545       $old_having, $new_attrs->{having}
 546     )
 547   }
 548
 549   my $rs = (ref $self)->new($rsrc, $new_attrs);
 550
 551   $rs->set_cache($cache) if ($cache);
 552
 553   return $rs;
 554 }
 555
 556 my $dark_sel_dumper;
 557 sub _normalize_selection {
 558   my ($self, $attrs) = @_;
 559
 560   # legacy syntax
 561   if ( exists $attrs->{include_columns} ) {
 562     carp_unique( "Resultset attribute 'include_columns' is deprecated, use '+columns' instead" );
 563     $attrs->{'+columns'} = $self->_merge_attr(
 564       $attrs->{'+columns'}, delete $attrs->{include_columns}
 565     );
 566   }
 567
 568   # columns are always placed first, however
 569
 570   # Keep the X vs +X separation until _resolved_attrs time - this allows to
 571   # delay the decision on whether to use a default select list ($rsrc->columns)
 572   # allowing stuff like the remove_columns helper to work
 573   #
 574   # select/as +select/+as pairs need special handling - the amount of select/as
 575   # elements in each pair does *not* have to be equal (think multicolumn
 576   # selectors like distinct(foo, bar) ). If the selector is bare (no 'as'
 577   # supplied at all) - try to infer the alias, either from the -as parameter
 578   # of the selector spec, or use the parameter whole if it looks like a column
 579   # name (ugly legacy heuristic). If all fails - leave the selector bare (which
 580   # is ok as well), but make sure no more additions to the 'as' chain take place
 581   for my $pref ('', '+') {
 582
 583     my ($sel, $as) = map {
 584       my $key = "${pref}${_}";
 585
 586       my $val = [ ref $attrs->{$key} eq 'ARRAY'
 587         ? @{$attrs->{$key}}
 588         : $attrs->{$key} || ()
 589       ];
 590       delete $attrs->{$key};
 591       $val;
 592     } qw/select as/;
 593
 594     if (! @$as and ! @$sel ) {
 595       next;
 596     }
 597     elsif (@$as and ! @$sel) {
 598       $self->throw_exception(
 599         "Unable to handle ${pref}as specification (@$as) without a corresponding ${pref}select"
 600       );
 601     }
 602     elsif( ! @$as ) {
 603       # no as part supplied at all - try to deduce (unless explicit end of named selection is declared)
 604       # if any @$as has been supplied we assume the user knows what (s)he is doing
 605       # and blindly keep stacking up pieces
 606       unless ($attrs->{_dark_selector}) {
 607         SELECTOR:
 608         for (@$sel) {
 609           if ( ref $_ eq 'HASH' and exists $_->{-as} ) {
 610             push @$as, $_->{-as};
 611           }
 612           # assume any plain no-space, no-parenthesis string to be a column spec
 613           # FIXME - this is retarded but is necessary to support shit like 'count(foo)'
 614           elsif ( ! ref $_ and $_ =~ /^ [^\s\(\)]+ $/x) {
 615             push @$as, $_;
 616           }
 617           # if all else fails - raise a flag that no more aliasing will be allowed
 618           else {
 619             $attrs->{_dark_selector} = {
 620               plus_stage => $pref,
 621               string => ($dark_sel_dumper ||= do {
 622                   require Data::Dumper::Concise;
 623                   Data::Dumper::Concise::DumperObject()->Indent(0);
 624                 })->Values([$_])->Dump
 625               ,
 626             };
 627             last SELECTOR;
 628           }
 629         }
 630       }
 631     }
 632     elsif (@$as < @$sel) {
 633       $self->throw_exception(
 634         "Unable to handle an ${pref}as specification (@$as) with less elements than the corresponding ${pref}select"
 635       );
 636     }
 637     elsif ($pref and $attrs->{_dark_selector}) {
 638       $self->throw_exception(
 639         "Unable to process named '+select', resultset contains an unnamed selector $attrs->{_dark_selector}{string}"
 640       );
 641     }
 642
 643
 644     # merge result
 645     $attrs->{"${pref}select"} = $self->_merge_attr($attrs->{"${pref}select"}, $sel);
 646     $attrs->{"${pref}as"} = $self->_merge_attr($attrs->{"${pref}as"}, $as);
 647   }
 648 }
 649
 650 sub _stack_cond {
 651   my ($self, $left, $right) = @_;
 652
 653   (
 654     (ref $_ eq 'ARRAY' and !@$_)
 655       or
 656     (ref $_ eq 'HASH' and ! keys %$_)
 657   ) and $_ = undef for ($left, $right);
 658
 659   # either one of the two undef
 660   if ( (defined $left) xor (defined $right) ) {
 661     return defined $left ? $left : $right;
 662   }
 663   # both undef
 664   elsif ( ! defined $left ) {
 665     return undef
 666   }
 667   else {
 668     return $self->result_source->schema->storage->_collapse_cond({ -and => [$left, $right] });
 669   }
 670 }
 671
 672 =head2 search_literal
 673
 674 B<CAVEAT>: C<search_literal> is provided for Class::DBI compatibility and
 675 should only be used in that context. C<search_literal> is a convenience
 676 method. It is equivalent to calling C<< $schema->search(\[]) >>, but if you
 677 want to ensure columns are bound correctly, use L</search>.
 678
 679 See L<DBIx::Class::Manual::Cookbook/SEARCHING> and
 680 L<DBIx::Class::Manual::FAQ/Searching> for searching techniques that do not
 681 require C<search_literal>.
 682
 683 =over 4
 684
 685 =item Arguments: $sql_fragment, @standalone_bind_values
 686
 687 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 688
 689 =back
 690
 691   my @cds   = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
 692   my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
 693
 694 Pass a literal chunk of SQL to be added to the conditional part of the
 695 resultset query.
 696
 697 Example of how to use C<search> instead of C<search_literal>
 698
 699   my @cds = $cd_rs->search_literal('cdid = ? AND (artist = ? OR artist = ?)', (2, 1, 2));
 700   my @cds = $cd_rs->search(\[ 'cdid = ? AND (artist = ? OR artist = ?)', [ 'cdid', 2 ], [ 'artist', 1 ], [ 'artist', 2 ] ]);
 701
 702 =cut
 703
 704 sub search_literal {
 705   my ($self, $sql, @bind) = @_;
 706   my $attr;
 707   if ( @bind && ref($bind[-1]) eq 'HASH' ) {
 708     $attr = pop @bind;
 709   }
 710   return $self->search(\[ $sql, map [ {} => $_ ], @bind ], ($attr || () ));
 711 }
 712
 713 =head2 find
 714
 715 =over 4
 716
 717 =item Arguments: \%columns_values | @pk_values, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
 718
 719 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
 720
 721 =back
 722
 723 Finds and returns a single row based on supplied criteria. Takes either a
 724 hashref with the same format as L</create> (including inference of foreign
 725 keys from related objects), or a list of primary key values in the same
 726 order as the L<primary columns|DBIx::Class::ResultSource/primary_columns>
 727 declaration on the L</result_source>.
 728
 729 In either case an attempt is made to combine conditions already existing on
 730 the resultset with the condition passed to this method.
 731
 732 To aid with preparing the correct query for the storage you may supply the
 733 C<key> attribute, which is the name of a
 734 L<unique constraint|DBIx::Class::ResultSource/add_unique_constraint> (the
 735 unique constraint corresponding to the
 736 L<primary columns|DBIx::Class::ResultSource/primary_columns> is always named
 737 C<primary>). If the C<key> attribute has been supplied, and DBIC is unable
 738 to construct a query that satisfies the named unique constraint fully (
 739 non-NULL values for each column member of the constraint) an exception is
 740 thrown.
 741
 742 If no C<key> is specified, the search is carried over all unique constraints
 743 which are fully defined by the available condition.
 744
 745 If no such constraint is found, C<find> currently defaults to a simple
 746 C<< search->(\%column_values) >> which may or may not do what you expect.
 747 Note that this fallback behavior may be deprecated in further versions. If
 748 you need to search with arbitrary conditions - use L</search>. If the query
 749 resulting from this fallback produces more than one row, a warning to the
 750 effect is issued, though only the first row is constructed and returned as
 751 C<$result_object>.
 752
 753 In addition to C<key>, L</find> recognizes and applies standard
 754 L<resultset attributes|/ATTRIBUTES> in the same way as L</search> does.
 755
 756 Note that if you have extra concerns about the correctness of the resulting
 757 query you need to specify the C<key> attribute and supply the entire condition
 758 as an argument to find (since it is not always possible to perform the
 759 combination of the resultset condition with the supplied one, especially if
 760 the resultset condition contains literal sql).
 761
 762 For example, to find a row by its primary key:
 763
 764   my $cd = $schema->resultset('CD')->find(5);
 765
 766 You can also find a row by a specific unique constraint:
 767
 768   my $cd = $schema->resultset('CD')->find(
 769     {
 770       artist => 'Massive Attack',
 771       title  => 'Mezzanine',
 772     },
 773     { key => 'cd_artist_title' }
 774   );
 775
 776 See also L</find_or_create> and L</update_or_create>.
 777
 778 =cut
 779
 780 sub find {
 781   my $self = shift;
 782   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 783
 784   my $rsrc = $self->result_source;
 785
 786   my $constraint_name;
 787   if (exists $attrs->{key}) {
 788     $constraint_name = defined $attrs->{key}
 789       ? $attrs->{key}
 790       : $self->throw_exception("An undefined 'key' resultset attribute makes no sense")
 791     ;
 792   }
 793
 794   # Parse out the condition from input
 795   my $call_cond;
 796
 797   if (ref $_[0] eq 'HASH') {
 798     $call_cond = { %{$_[0]} };
 799   }
 800   else {
 801     # if only values are supplied we need to default to 'primary'
 802     $constraint_name = 'primary' unless defined $constraint_name;
 803
 804     my @c_cols = $rsrc->unique_constraint_columns($constraint_name);
 805
 806     $self->throw_exception(
 807       "No constraint columns, maybe a malformed '$constraint_name' constraint?"
 808     ) unless @c_cols;
 809
 810     $self->throw_exception (
 811       'find() expects either a column/value hashref, or a list of values '
 812     . "corresponding to the columns of the specified unique constraint '$constraint_name'"
 813     ) unless @c_cols == @_;
 814
 815     @{$call_cond}{@c_cols} = @_;
 816   }
 817
 818   # process relationship data if any
 819   for my $key (keys %$call_cond) {
 820     if (
 821       length ref($call_cond->{$key})
 822         and
 823       my $relinfo = $rsrc->relationship_info($key)
 824         and
 825       # implicitly skip has_many's (likely MC)
 826       (ref (my $val = delete $call_cond->{$key}) ne 'ARRAY' )
 827     ) {
 828       my ($rel_cond, $crosstable) = $rsrc->_resolve_condition(
 829         $relinfo->{cond}, $val, $key, $key
 830       );
 831
 832       $self->throw_exception("Complex condition via relationship '$key' is unsupported in find()")
 833          if $crosstable or ref($rel_cond) ne 'HASH';
 834
 835       # supplement condition
 836       # relationship conditions take precedence (?)
 837       @{$call_cond}{keys %$rel_cond} = values %$rel_cond;
 838     }
 839   }
 840
 841   my $alias = exists $attrs->{alias} ? $attrs->{alias} : $self->{attrs}{alias};
 842   my $final_cond;
 843   if (defined $constraint_name) {
 844     $final_cond = $self->_qualify_cond_columns (
 845
 846       $self->result_source->_minimal_valueset_satisfying_constraint(
 847         constraint_name => $constraint_name,
 848         values => ($self->_merge_with_rscond($call_cond))[0],
 849         carp_on_nulls => 1,
 850       ),
 851
 852       $alias,
 853     );
 854   }
 855   elsif ($self->{attrs}{accessor} and $self->{attrs}{accessor} eq 'single') {
 856     # This means that we got here after a merger of relationship conditions
 857     # in ::Relationship::Base::search_related (the row method), and furthermore
 858     # the relationship is of the 'single' type. This means that the condition
 859     # provided by the relationship (already attached to $self) is sufficient,
 860     # as there can be only one row in the database that would satisfy the
 861     # relationship
 862   }
 863   else {
 864     my (@unique_queries, %seen_column_combinations, $ci, @fc_exceptions);
 865
 866     # no key was specified - fall down to heuristics mode:
 867     # run through all unique queries registered on the resultset, and
 868     # 'OR' all qualifying queries together
 869     #
 870     # always start from 'primary' if it exists at all
 871     for my $c_name ( sort {
 872         $a eq 'primary' ? -1
 873       : $b eq 'primary' ? 1
 874       : $a cmp $b
 875     } $rsrc->unique_constraint_names) {
 876
 877       next if $seen_column_combinations{
 878         join "\x00", sort $rsrc->unique_constraint_columns($c_name)
 879       }++;
 880
 881       try {
 882         push @unique_queries, $self->_qualify_cond_columns(
 883           $self->result_source->_minimal_valueset_satisfying_constraint(
 884             constraint_name => $c_name,
 885             values => ($self->_merge_with_rscond($call_cond))[0],
 886             columns_info => ($ci ||= $self->result_source->columns_info),
 887           ),
 888           $alias
 889         );
 890       }
 891       catch {
 892         push @fc_exceptions, $_ if $_ =~ /\bFilterColumn\b/;
 893       };
 894     }
 895
 896     $final_cond =
 897         @unique_queries   ? \@unique_queries
 898       : @fc_exceptions    ? $self->throw_exception(join "; ", map { $_ =~ /(.*) at .+ line \d+$/s } @fc_exceptions )
 899       :                     $self->_non_unique_find_fallback ($call_cond, $attrs)
 900     ;
 901   }
 902
 903   # Run the query, passing the result_class since it should propagate for find
 904   my $rs = $self->search ($final_cond, {result_class => $self->result_class, %$attrs});
 905   if ($rs->_resolved_attrs->{collapse}) {
 906     my $row = $rs->next;
 907     carp "Query returned more than one row" if $rs->next;
 908     return $row;
 909   }
 910   else {
 911     return $rs->single;
 912   }
 913 }
 914
 915 # This is a stop-gap method as agreed during the discussion on find() cleanup:
 916 # http://lists.scsys.co.uk/pipermail/dbix-class/2010-October/009535.html
 917 #
 918 # It is invoked when find() is called in legacy-mode with insufficiently-unique
 919 # condition. It is provided for overrides until a saner way forward is devised
 920 #
 921 # *NOTE* This is not a public method, and it's *GUARANTEED* to disappear down
 922 # the road. Please adjust your tests accordingly to catch this situation early
 923 # DBIx::Class::ResultSet->can('_non_unique_find_fallback') is reasonable
 924 #
 925 # The method will not be removed without an adequately complete replacement
 926 # for strict-mode enforcement
 927 sub _non_unique_find_fallback {
 928   my ($self, $cond, $attrs) = @_;
 929
 930   return $self->_qualify_cond_columns(
 931     $cond,
 932     exists $attrs->{alias}
 933       ? $attrs->{alias}
 934       : $self->{attrs}{alias}
 935   );
 936 }
 937
 938
 939 sub _qualify_cond_columns {
 940   my ($self, $cond, $alias) = @_;
 941
 942   my %aliased = %$cond;
 943   for (keys %aliased) {
 944     $aliased{"$alias.$_"} = delete $aliased{$_}
 945       if $_ !~ /\./;
 946   }
 947
 948   return \%aliased;
 949 }
 950
 951 sub _build_unique_cond {
 952   carp_unique sprintf
 953     '_build_unique_cond is a private method, and moreover is about to go '
 954   . 'away. Please contact the development team at %s if you believe you '
 955   . 'have a genuine use for this method, in order to discuss alternatives.',
 956     DBIx::Class::_ENV_::HELP_URL,
 957   ;
 958
 959   my ($self, $constraint_name, $cond, $croak_on_null) = @_;
 960
 961   $self->result_source->_minimal_valueset_satisfying_constraint(
 962     constraint_name => $constraint_name,
 963     values => $cond,
 964     carp_on_nulls => !$croak_on_null
 965   );
 966 }
 967
 968 =head2 search_related
 969
 970 =over 4
 971
 972 =item Arguments: $rel_name, $cond?, L<\%attrs?|/ATTRIBUTES>
 973
 974 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 975
 976 =back
 977
 978   $new_rs = $cd_rs->search_related('artist', {
 979     name => 'Emo-R-Us',
 980   });
 981
 982 Searches the specified relationship, optionally specifying a condition and
 983 attributes for matching records. See L</ATTRIBUTES> for more information.
 984
 985 In list context, C<< ->all() >> is called implicitly on the resultset, thus
 986 returning a list of result objects instead. To avoid that, use L</search_related_rs>.
 987
 988 See also L</search_related_rs>.
 989
 990 =cut
 991
 992 sub search_related {
 993   return shift->related_resultset(shift)->search(@_);
 994 }
 995
 996 =head2 search_related_rs
 997
 998 This method works exactly the same as search_related, except that
 999 it guarantees a resultset, even in list context.
1000
1001 =cut
1002
1003 sub search_related_rs {
1004   return shift->related_resultset(shift)->search_rs(@_);
1005 }
1006
1007 =head2 cursor
1008
1009 =over 4
1010
1011 =item Arguments: none
1012
1013 =item Return Value: L<$cursor|DBIx::Class::Cursor>
1014
1015 =back
1016
1017 Returns a storage-driven cursor to the given resultset. See
1018 L<DBIx::Class::Cursor> for more information.
1019
1020 =cut
1021
1022 sub cursor {
1023   my $self = shift;
1024
1025   return $self->{cursor} ||= do {
1026     my $attrs = $self->_resolved_attrs;
1027     $self->result_source->storage->select(
1028       $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
1029     );
1030   };
1031 }
1032
1033 =head2 single
1034
1035 =over 4
1036
1037 =item Arguments: L<$cond?|DBIx::Class::SQLMaker>
1038
1039 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1040
1041 =back
1042
1043   my $cd = $schema->resultset('CD')->single({ year => 2001 });
1044
1045 Inflates the first result without creating a cursor if the resultset has
1046 any records in it; if not returns C<undef>. Used by L</find> as a lean version
1047 of L</search>.
1048
1049 While this method can take an optional search condition (just like L</search>)
1050 being a fast-code-path it does not recognize search attributes. If you need to
1051 add extra joins or similar, call L</search> and then chain-call L</single> on the
1052 L<DBIx::Class::ResultSet> returned.
1053
1054 =over
1055
1056 =item B<Note>
1057
1058 As of 0.08100, this method enforces the assumption that the preceding
1059 query returns only one row. If more than one row is returned, you will receive
1060 a warning:
1061
1062   Query returned more than one row
1063
1064 In this case, you should be using L</next> or L</find> instead, or if you really
1065 know what you are doing, use the L</rows> attribute to explicitly limit the size
1066 of the resultset.
1067
1068 This method will also throw an exception if it is called on a resultset prefetching
1069 has_many, as such a prefetch implies fetching multiple rows from the database in
1070 order to assemble the resulting object.
1071
1072 =back
1073
1074 =cut
1075
1076 sub single {
1077   my ($self, $where) = @_;
1078   if(@_ > 2) {
1079       $self->throw_exception('single() only takes search conditions, no attributes. You want ->search( $cond, $attrs )->single()');
1080   }
1081
1082   my $attrs = { %{$self->_resolved_attrs} };
1083
1084   $self->throw_exception(
1085     'single() can not be used on resultsets collapsing a has_many. Use find( \%cond ) or next() instead'
1086   ) if $attrs->{collapse};
1087
1088   if ($where) {
1089     if (defined $attrs->{where}) {
1090       $attrs->{where} = {
1091         '-and' =>
1092             [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
1093                $where, delete $attrs->{where} ]
1094       };
1095     } else {
1096       $attrs->{where} = $where;
1097     }
1098   }
1099
1100   my $data = [ $self->result_source->storage->select_single(
1101     $attrs->{from}, $attrs->{select},
1102     $attrs->{where}, $attrs
1103   )];
1104
1105   return undef unless @$data;
1106   $self->{_stashed_rows} = [ $data ];
1107   $self->_construct_results->[0];
1108 }
1109
1110 =head2 get_column
1111
1112 =over 4
1113
1114 =item Arguments: L<$cond?|DBIx::Class::SQLMaker>
1115
1116 =item Return Value: L<$resultsetcolumn|DBIx::Class::ResultSetColumn>
1117
1118 =back
1119
1120   my $max_length = $rs->get_column('length')->max;
1121
1122 Returns a L<DBIx::Class::ResultSetColumn> instance for a column of the ResultSet.
1123
1124 =cut
1125
1126 sub get_column {
1127   my ($self, $column) = @_;
1128   my $new = DBIx::Class::ResultSetColumn->new($self, $column);
1129   return $new;
1130 }
1131
1132 =head2 search_like
1133
1134 =over 4
1135
1136 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1137
1138 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
1139
1140 =back
1141
1142   # WHERE title LIKE '%blue%'
1143   $cd_rs = $rs->search_like({ title => '%blue%'});
1144
1145 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
1146 that this is simply a convenience method retained for ex Class::DBI users.
1147 You most likely want to use L</search> with specific operators.
1148
1149 For more information, see L<DBIx::Class::Manual::Cookbook>.
1150
1151 This method is deprecated and will be removed in 0.09. Use L<search()|/search>
1152 instead. An example conversion is:
1153
1154   ->search_like({ foo => 'bar' });
1155
1156   # Becomes
1157
1158   ->search({ foo => { like => 'bar' } });
1159
1160 =cut
1161
1162 sub search_like {
1163   my $class = shift;
1164   carp_unique (
1165     'search_like() is deprecated and will be removed in DBIC version 0.09.'
1166    .' Instead use ->search({ x => { -like => "y%" } })'
1167    .' (note the outer pair of {}s - they are important!)'
1168   );
1169   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1170   my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
1171   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
1172   return $class->search($query, { %$attrs });
1173 }
1174
1175 =head2 slice
1176
1177 =over 4
1178
1179 =item Arguments: $first, $last
1180
1181 =item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
1182
1183 =back
1184
1185 Returns a resultset or object list representing a subset of elements from the
1186 resultset slice is called on. Indexes are from 0, i.e., to get the first
1187 three records, call:
1188
1189   my ($one, $two, $three) = $rs->slice(0, 2);
1190
1191 =cut
1192
1193 sub slice {
1194   my ($self, $min, $max) = @_;
1195   my $attrs = {}; # = { %{ $self->{attrs} || {} } };
1196   $attrs->{offset} = $self->{attrs}{offset} || 0;
1197   $attrs->{offset} += $min;
1198   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
1199   return $self->search(undef, $attrs);
1200 }
1201
1202 =head2 next
1203
1204 =over 4
1205
1206 =item Arguments: none
1207
1208 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1209
1210 =back
1211
1212 Returns the next element in the resultset (C<undef> is there is none).
1213
1214 Can be used to efficiently iterate over records in the resultset:
1215
1216   my $rs = $schema->resultset('CD')->search;
1217   while (my $cd = $rs->next) {
1218     print $cd->title;
1219   }
1220
1221 Note that you need to store the resultset object, and call C<next> on it.
1222 Calling C<< resultset('Table')->next >> repeatedly will always return the
1223 first record from the resultset.
1224
1225 =cut
1226
1227 sub next {
1228   my ($self) = @_;
1229
1230   if (my $cache = $self->get_cache) {
1231     $self->{all_cache_position} ||= 0;
1232     return $cache->[$self->{all_cache_position}++];
1233   }
1234
1235   if ($self->{attrs}{cache}) {
1236     delete $self->{pager};
1237     $self->{all_cache_position} = 1;
1238     return ($self->all)[0];
1239   }
1240
1241   return shift(@{$self->{_stashed_results}}) if @{ $self->{_stashed_results}||[] };
1242
1243   $self->{_stashed_results} = $self->_construct_results
1244     or return undef;
1245
1246   return shift @{$self->{_stashed_results}};
1247 }
1248
1249 # Constructs as many results as it can in one pass while respecting
1250 # cursor laziness. Several modes of operation:
1251 #
1252 # * Always builds everything present in @{$self->{_stashed_rows}}
1253 # * If called with $fetch_all true - pulls everything off the cursor and
1254 #   builds all result structures (or objects) in one pass
1255 # * If $self->_resolved_attrs->{collapse} is true, checks the order_by
1256 #   and if the resultset is ordered properly by the left side:
1257 #   * Fetches stuff off the cursor until the "master object" changes,
1258 #     and saves the last extra row (if any) in @{$self->{_stashed_rows}}
1259 #   OR
1260 #   * Just fetches, and collapses/constructs everything as if $fetch_all
1261 #     was requested (there is no other way to collapse except for an
1262 #     eager cursor)
1263 # * If no collapse is requested - just get the next row, construct and
1264 #   return
1265 sub _construct_results {
1266   my ($self, $fetch_all) = @_;
1267
1268   my $rsrc = $self->result_source;
1269   my $attrs = $self->_resolved_attrs;
1270
1271   if (
1272     ! $fetch_all
1273       and
1274     ! $attrs->{order_by}
1275       and
1276     $attrs->{collapse}
1277       and
1278     my @pcols = $rsrc->primary_columns
1279   ) {
1280     # default order for collapsing unless the user asked for something
1281     $attrs->{order_by} = [ map { join '.', $attrs->{alias}, $_} @pcols ];
1282     $attrs->{_ordered_for_collapse} = 1;
1283     $attrs->{_order_is_artificial} = 1;
1284   }
1285
1286   # this will be used as both initial raw-row collector AND as a RV of
1287   # _construct_results. Not regrowing the array twice matters a lot...
1288   # a surprising amount actually
1289   my $rows = delete $self->{_stashed_rows};
1290
1291   my $cursor; # we may not need one at all
1292
1293   my $did_fetch_all = $fetch_all;
1294
1295   if ($fetch_all) {
1296     # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1297     $rows = [ ($rows ? @$rows : ()), $self->cursor->all ];
1298   }
1299   elsif( $attrs->{collapse} ) {
1300
1301     # a cursor will need to be closed over in case of collapse
1302     $cursor = $self->cursor;
1303
1304     $attrs->{_ordered_for_collapse} = (
1305       (
1306         $attrs->{order_by}
1307           and
1308         $rsrc->schema
1309               ->storage
1310                ->_extract_colinfo_of_stable_main_source_order_by_portion($attrs)
1311       ) ? 1 : 0
1312     ) unless defined $attrs->{_ordered_for_collapse};
1313
1314     if (! $attrs->{_ordered_for_collapse}) {
1315       $did_fetch_all = 1;
1316
1317       # instead of looping over ->next, use ->all in stealth mode
1318       # *without* calling a ->reset afterwards
1319       # FIXME ENCAPSULATION - encapsulation breach, cursor method additions pending
1320       if (! $cursor->{_done}) {
1321         $rows = [ ($rows ? @$rows : ()), $cursor->all ];
1322         $cursor->{_done} = 1;
1323       }
1324     }
1325   }
1326
1327   if (! $did_fetch_all and ! @{$rows||[]} ) {
1328     # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1329     $cursor ||= $self->cursor;
1330     if (scalar (my @r = $cursor->next) ) {
1331       $rows = [ \@r ];
1332     }
1333   }
1334
1335   return undef unless @{$rows||[]};
1336
1337   # sanity check - people are too clever for their own good
1338   if ($attrs->{collapse} and my $aliastypes = $attrs->{_last_sqlmaker_alias_map} ) {
1339
1340     my $multiplied_selectors;
1341     for my $sel_alias ( grep { $_ ne $attrs->{alias} } keys %{ $aliastypes->{selecting} } ) {
1342       if (
1343         $aliastypes->{multiplying}{$sel_alias}
1344           or
1345         $aliastypes->{premultiplied}{$sel_alias}
1346       ) {
1347         $multiplied_selectors->{$_} = 1 for values %{$aliastypes->{selecting}{$sel_alias}{-seen_columns}}
1348       }
1349     }
1350
1351     for my $i (0 .. $#{$attrs->{as}} ) {
1352       my $sel = $attrs->{select}[$i];
1353
1354       if (ref $sel eq 'SCALAR') {
1355         $sel = $$sel;
1356       }
1357       elsif( ref $sel eq 'REF' and ref $$sel eq 'ARRAY' ) {
1358         $sel = $$sel->[0];
1359       }
1360
1361       $self->throw_exception(
1362         'Result collapse not possible - selection from a has_many source redirected to the main object'
1363       ) if ($multiplied_selectors->{$sel} and $attrs->{as}[$i] !~ /\./);
1364     }
1365   }
1366
1367   # hotspot - skip the setter
1368   my $res_class = $self->_result_class;
1369
1370   my $inflator_cref = $self->{_result_inflator}{cref} ||= do {
1371     $res_class->can ('inflate_result')
1372       or $self->throw_exception("Inflator $res_class does not provide an inflate_result() method");
1373   };
1374
1375   my $infmap = $attrs->{as};
1376
1377   $self->{_result_inflator}{is_core_row} = ( (
1378     $inflator_cref
1379       ==
1380     ( \&DBIx::Class::Row::inflate_result || die "No ::Row::inflate_result() - can't happen" )
1381   ) ? 1 : 0 ) unless defined $self->{_result_inflator}{is_core_row};
1382
1383   $self->{_result_inflator}{is_hri} = ( (
1384     ! $self->{_result_inflator}{is_core_row}
1385       and
1386     $inflator_cref == \&DBIx::Class::ResultClass::HashRefInflator::inflate_result
1387   ) ? 1 : 0 ) unless defined $self->{_result_inflator}{is_hri};
1388
1389
1390   if ($attrs->{_simple_passthrough_construction}) {
1391     # construct a much simpler array->hash folder for the one-table HRI cases right here
1392     if ($self->{_result_inflator}{is_hri}) {
1393       for my $r (@$rows) {
1394         $r = { map { $infmap->[$_] => $r->[$_] } 0..$#$infmap };
1395       }
1396     }
1397     # FIXME SUBOPTIMAL this is a very very very hot spot
1398     # while rather optimal we can *still* do much better, by
1399     # building a smarter Row::inflate_result(), and
1400     # switch to feeding it data via a much leaner interface
1401     #
1402     # crude unscientific benchmarking indicated the shortcut eval is not worth it for
1403     # this particular resultset size
1404     elsif ( $self->{_result_inflator}{is_core_row} and @$rows < 60 ) {
1405       for my $r (@$rows) {
1406         $r = $inflator_cref->($res_class, $rsrc, { map { $infmap->[$_] => $r->[$_] } (0..$#$infmap) } );
1407       }
1408     }
1409     else {
1410       eval sprintf (
1411         ( $self->{_result_inflator}{is_core_row}
1412           ? '$_ = $inflator_cref->($res_class, $rsrc, { %s }) for @$rows'
1413           # a custom inflator may be a multiplier/reductor - put it in direct list ctx
1414           : '@$rows = map { $inflator_cref->($res_class, $rsrc, { %s } ) } @$rows'
1415         ),
1416         ( join (', ', map { "\$infmap->[$_] => \$_->[$_]" } 0..$#$infmap ) )
1417       );
1418     }
1419   }
1420   else {
1421     my $parser_type =
1422         $self->{_result_inflator}{is_hri}       ? 'hri'
1423       : $self->{_result_inflator}{is_core_row}  ? 'classic_pruning'
1424       :                                           'classic_nonpruning'
1425     ;
1426
1427     # $args and $attrs to _mk_row_parser are separated to delineate what is
1428     # core collapser stuff and what is dbic $rs specific
1429     @{$self->{_row_parser}{$parser_type}}{qw(cref nullcheck)} = $rsrc->_mk_row_parser({
1430       eval => 1,
1431       inflate_map => $infmap,
1432       collapse => $attrs->{collapse},
1433       premultiplied => $attrs->{_main_source_premultiplied},
1434       hri_style => $self->{_result_inflator}{is_hri},
1435       prune_null_branches => $self->{_result_inflator}{is_hri} || $self->{_result_inflator}{is_core_row},
1436     }, $attrs) unless $self->{_row_parser}{$parser_type}{cref};
1437
1438     # column_info metadata historically hasn't been too reliable.
1439     # We need to start fixing this somehow (the collapse resolver
1440     # can't work without it). Add an explicit check for the *main*
1441     # result, hopefully this will gradually weed out such errors
1442     #
1443     # FIXME - this is a temporary kludge that reduces performance
1444     # It is however necessary for the time being
1445     my ($unrolled_non_null_cols_to_check, $err);
1446
1447     if (my $check_non_null_cols = $self->{_row_parser}{$parser_type}{nullcheck} ) {
1448
1449       $err =
1450         'Collapse aborted due to invalid ResultSource metadata - the following '
1451       . 'selections are declared non-nullable but NULLs were retrieved: '
1452       ;
1453
1454       my @violating_idx;
1455       COL: for my $i (@$check_non_null_cols) {
1456         ! defined $_->[$i] and push @violating_idx, $i and next COL for @$rows;
1457       }
1458
1459       $self->throw_exception( $err . join (', ', map { "'$infmap->[$_]'" } @violating_idx ) )
1460         if @violating_idx;
1461
1462       $unrolled_non_null_cols_to_check = join (',', @$check_non_null_cols);
1463     }
1464
1465     my $next_cref =
1466       ($did_fetch_all or ! $attrs->{collapse})  ? undef
1467     : defined $unrolled_non_null_cols_to_check  ? eval sprintf <<'EOS', $unrolled_non_null_cols_to_check
1468 sub {
1469   # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1470   my @r = $cursor->next or return;
1471   if (my @violating_idx = grep { ! defined $r[$_] } (%s) ) {
1472     $self->throw_exception( $err . join (', ', map { "'$infmap->[$_]'" } @violating_idx ) )
1473   }
1474   \@r
1475 }
1476 EOS
1477     : sub {
1478         # FIXME SUBOPTIMAL - we can do better, cursor->next/all (well diff. methods) should return a ref
1479         my @r = $cursor->next or return;
1480         \@r
1481       }
1482     ;
1483
1484     $self->{_row_parser}{$parser_type}{cref}->(
1485       $rows,
1486       $next_cref ? ( $next_cref, $self->{_stashed_rows} = [] ) : (),
1487     );
1488
1489     # simple in-place substitution, does not regrow $rows
1490     if ($self->{_result_inflator}{is_core_row}) {
1491       $_ = $inflator_cref->($res_class, $rsrc, @$_) for @$rows
1492     }
1493     # Special-case multi-object HRI - there is no $inflator_cref pass at all
1494     elsif ( ! $self->{_result_inflator}{is_hri} ) {
1495       # the inflator may be a multiplier/reductor - put it in list ctx
1496       @$rows = map { $inflator_cref->($res_class, $rsrc, @$_) } @$rows;
1497     }
1498   }
1499
1500   # The @$rows check seems odd at first - why wouldn't we want to warn
1501   # regardless? The issue is things like find() etc, where the user
1502   # *knows* only one result will come back. In these cases the ->all
1503   # is not a pessimization, but rather something we actually want
1504   carp_unique(
1505     'Unable to properly collapse has_many results in iterator mode due '
1506   . 'to order criteria - performed an eager cursor slurp underneath. '
1507   . 'Consider using ->all() instead'
1508   ) if ( ! $fetch_all and @$rows > 1 );
1509
1510   return $rows;
1511 }
1512
1513 =head2 result_source
1514
1515 =over 4
1516
1517 =item Arguments: L<$result_source?|DBIx::Class::ResultSource>
1518
1519 =item Return Value: L<$result_source|DBIx::Class::ResultSource>
1520
1521 =back
1522
1523 An accessor for the primary ResultSource object from which this ResultSet
1524 is derived.
1525
1526 =head2 result_class
1527
1528 =over 4
1529
1530 =item Arguments: $result_class?
1531
1532 =item Return Value: $result_class
1533
1534 =back
1535
1536 An accessor for the class to use when creating result objects. Defaults to
1537 C<< result_source->result_class >> - which in most cases is the name of the
1538 L<"table"|DBIx::Class::Manual::Glossary/"ResultSource"> class.
1539
1540 Note that changing the result_class will also remove any components
1541 that were originally loaded in the source class via
1542 L<load_components|Class::C3::Componentised/load_components( @comps )>.
1543 Any overloaded methods in the original source class will not run.
1544
1545 =cut
1546
1547 sub result_class {
1548   my ($self, $result_class) = @_;
1549   if ($result_class) {
1550
1551     # don't fire this for an object
1552     $self->ensure_class_loaded($result_class)
1553       unless ref($result_class);
1554
1555     if ($self->get_cache) {
1556       carp_unique('Changing the result_class of a ResultSet instance with cached results is a noop - the cache contents will not be altered');
1557     }
1558     # FIXME ENCAPSULATION - encapsulation breach, cursor method additions pending
1559     elsif ($self->{cursor} && $self->{cursor}{_pos}) {
1560       $self->throw_exception('Changing the result_class of a ResultSet instance with an active cursor is not supported');
1561     }
1562
1563     $self->_result_class($result_class);
1564
1565     delete $self->{_result_inflator};
1566   }
1567   $self->_result_class;
1568 }
1569
1570 =head2 count
1571
1572 =over 4
1573
1574 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1575
1576 =item Return Value: $count
1577
1578 =back
1579
1580 Performs an SQL C<COUNT> with the same query as the resultset was built
1581 with to find the number of elements. Passing arguments is equivalent to
1582 C<< $rs->search ($cond, \%attrs)->count >>
1583
1584 =cut
1585
1586 sub count {
1587   my $self = shift;
1588   return $self->search(@_)->count if @_ and defined $_[0];
1589   return scalar @{ $self->get_cache } if $self->get_cache;
1590
1591   my $attrs = { %{ $self->_resolved_attrs } };
1592
1593   # this is a little optimization - it is faster to do the limit
1594   # adjustments in software, instead of a subquery
1595   my ($rows, $offset) = delete @{$attrs}{qw/rows offset/};
1596
1597   my $crs;
1598   if ($self->_has_resolved_attr (qw/collapse group_by/)) {
1599     $crs = $self->_count_subq_rs ($attrs);
1600   }
1601   else {
1602     $crs = $self->_count_rs ($attrs);
1603   }
1604   my $count = $crs->next;
1605
1606   $count -= $offset if $offset;
1607   $count = $rows if $rows and $rows < $count;
1608   $count = 0 if ($count < 0);
1609
1610   return $count;
1611 }
1612
1613 =head2 count_rs
1614
1615 =over 4
1616
1617 =item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES>
1618
1619 =item Return Value: L<$count_rs|DBIx::Class::ResultSetColumn>
1620
1621 =back
1622
1623 Same as L</count> but returns a L<DBIx::Class::ResultSetColumn> object.
1624 This can be very handy for subqueries:
1625
1626   ->search( { amount => $some_rs->count_rs->as_query } )
1627
1628 As with regular resultsets the SQL query will be executed only after
1629 the resultset is accessed via L</next> or L</all>. That would return
1630 the same single value obtainable via L</count>.
1631
1632 =cut
1633
1634 sub count_rs {
1635   my $self = shift;
1636   return $self->search(@_)->count_rs if @_;
1637
1638   # this may look like a lack of abstraction (count() does about the same)
1639   # but in fact an _rs *must* use a subquery for the limits, as the
1640   # software based limiting can not be ported if this $rs is to be used
1641   # in a subquery itself (i.e. ->as_query)
1642   if ($self->_has_resolved_attr (qw/collapse group_by offset rows/)) {
1643     return $self->_count_subq_rs($self->{_attrs});
1644   }
1645   else {
1646     return $self->_count_rs($self->{_attrs});
1647   }
1648 }
1649
1650 #
1651 # returns a ResultSetColumn object tied to the count query
1652 #
1653 sub _count_rs {
1654   my ($self, $attrs) = @_;
1655
1656   my $rsrc = $self->result_source;
1657
1658   my $tmp_attrs = { %$attrs };
1659   # take off any limits, record_filter is cdbi, and no point of ordering nor locking a count
1660   delete @{$tmp_attrs}{qw/rows offset order_by record_filter for/};
1661
1662   # overwrite the selector (supplied by the storage)
1663   $rsrc->resultset_class->new($rsrc, {
1664     %$tmp_attrs,
1665     select => $rsrc->storage->_count_select ($rsrc, $attrs),
1666     as => 'count',
1667   })->get_column ('count');
1668 }
1669
1670 #
1671 # same as above but uses a subquery
1672 #
1673 sub _count_subq_rs {
1674   my ($self, $attrs) = @_;
1675
1676   my $rsrc = $self->result_source;
1677
1678   my $sub_attrs = { %$attrs };
1679   # extra selectors do not go in the subquery and there is no point of ordering it, nor locking it
1680   delete @{$sub_attrs}{qw/collapse columns as select order_by for/};
1681
1682   # if we multi-prefetch we group_by something unique, as this is what we would
1683   # get out of the rs via ->next/->all. We *DO WANT* to clobber old group_by regardless
1684   if ( $attrs->{collapse}  ) {
1685     $sub_attrs->{group_by} = [ map { "$attrs->{alias}.$_" } @{
1686       $rsrc->_identifying_column_set || $self->throw_exception(
1687         'Unable to construct a unique group_by criteria properly collapsing the '
1688       . 'has_many prefetch before count()'
1689       );
1690     } ]
1691   }
1692
1693   # Calculate subquery selector
1694   if (my $g = $sub_attrs->{group_by}) {
1695
1696     my $sql_maker = $rsrc->storage->sql_maker;
1697
1698     # necessary as the group_by may refer to aliased functions
1699     my $sel_index;
1700     for my $sel (@{$attrs->{select}}) {
1701       $sel_index->{$sel->{-as}} = $sel
1702         if (ref $sel eq 'HASH' and $sel->{-as});
1703     }
1704
1705     # anything from the original select mentioned on the group-by needs to make it to the inner selector
1706     # also look for named aggregates referred in the having clause
1707     # having often contains scalarrefs - thus parse it out entirely
1708     my @parts = @$g;
1709     if ($attrs->{having}) {
1710       local $sql_maker->{having_bind};
1711       local $sql_maker->{quote_char} = $sql_maker->{quote_char};
1712       local $sql_maker->{name_sep} = $sql_maker->{name_sep};
1713       unless (defined $sql_maker->{quote_char} and length $sql_maker->{quote_char}) {
1714         $sql_maker->{quote_char} = [ "\x00", "\xFF" ];
1715         # if we don't unset it we screw up retarded but unfortunately working
1716         # 'MAX(foo.bar)' => { '>', 3 }
1717         $sql_maker->{name_sep} = '';
1718       }
1719
1720       my ($lquote, $rquote, $sep) = map { quotemeta $_ } ($sql_maker->_quote_chars, $sql_maker->name_sep);
1721
1722       my $having_sql = $sql_maker->_parse_rs_attrs ({ having => $attrs->{having} });
1723       my %seen_having;
1724
1725       # search for both a proper quoted qualified string, for a naive unquoted scalarref
1726       # and if all fails for an utterly naive quoted scalar-with-function
1727       while ($having_sql =~ /
1728         $rquote $sep $lquote (.+?) $rquote
1729           |
1730         [\s,] \w+ \. (\w+) [\s,]
1731           |
1732         [\s,] $lquote (.+?) $rquote [\s,]
1733       /gx) {
1734         my $part = $1 || $2 || $3;  # one of them matched if we got here
1735         unless ($seen_having{$part}++) {
1736           push @parts, $part;
1737         }
1738       }
1739     }
1740
1741     for (@parts) {
1742       my $colpiece = $sel_index->{$_} || $_;
1743
1744       # unqualify join-based group_by's. Arcane but possible query
1745       # also horrible horrible hack to alias a column (not a func.)
1746       # (probably need to introduce SQLA syntax)
1747       if ($colpiece =~ /\./ && $colpiece !~ /^$attrs->{alias}\./) {
1748         my $as = $colpiece;
1749         $as =~ s/\./__/;
1750         $colpiece = \ sprintf ('%s AS %s', map { $sql_maker->_quote ($_) } ($colpiece, $as) );
1751       }
1752       push @{$sub_attrs->{select}}, $colpiece;
1753     }
1754   }
1755   else {
1756     my @pcols = map { "$attrs->{alias}.$_" } ($rsrc->primary_columns);
1757     $sub_attrs->{select} = @pcols ? \@pcols : [ 1 ];
1758   }
1759
1760   return $rsrc->resultset_class
1761                ->new ($rsrc, $sub_attrs)
1762                 ->as_subselect_rs
1763                  ->search ({}, { columns => { count => $rsrc->storage->_count_select ($rsrc, $attrs) } })
1764                   ->get_column ('count');
1765 }
1766
1767
1768 =head2 count_literal
1769
1770 B<CAVEAT>: C<count_literal> is provided for Class::DBI compatibility and
1771 should only be used in that context. See L</search_literal> for further info.
1772
1773 =over 4
1774
1775 =item Arguments: $sql_fragment, @standalone_bind_values
1776
1777 =item Return Value: $count
1778
1779 =back
1780
1781 Counts the results in a literal query. Equivalent to calling L</search_literal>
1782 with the passed arguments, then L</count>.
1783
1784 =cut
1785
1786 sub count_literal { shift->search_literal(@_)->count; }
1787
1788 =head2 all
1789
1790 =over 4
1791
1792 =item Arguments: none
1793
1794 =item Return Value: L<@result_objs|DBIx::Class::Manual::ResultClass>
1795
1796 =back
1797
1798 Returns all elements in the resultset.
1799
1800 =cut
1801
1802 sub all {
1803   my $self = shift;
1804   if(@_) {
1805     $self->throw_exception("all() doesn't take any arguments, you probably wanted ->search(...)->all()");
1806   }
1807
1808   delete @{$self}{qw/_stashed_rows _stashed_results/};
1809
1810   if (my $c = $self->get_cache) {
1811     return @$c;
1812   }
1813
1814   $self->cursor->reset;
1815
1816   my $objs = $self->_construct_results('fetch_all') || [];
1817
1818   $self->set_cache($objs) if $self->{attrs}{cache};
1819
1820   return @$objs;
1821 }
1822
1823 =head2 reset
1824
1825 =over 4
1826
1827 =item Arguments: none
1828
1829 =item Return Value: $self
1830
1831 =back
1832
1833 Resets the resultset's cursor, so you can iterate through the elements again.
1834 Implicitly resets the storage cursor, so a subsequent L</next> will trigger
1835 another query.
1836
1837 =cut
1838
1839 sub reset {
1840   my ($self) = @_;
1841
1842   delete @{$self}{qw/_stashed_rows _stashed_results/};
1843   $self->{all_cache_position} = 0;
1844   $self->cursor->reset;
1845   return $self;
1846 }
1847
1848 =head2 first
1849
1850 =over 4
1851
1852 =item Arguments: none
1853
1854 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
1855
1856 =back
1857
1858 L<Resets|/reset> the resultset (causing a fresh query to storage) and returns
1859 an object for the first result (or C<undef> if the resultset is empty).
1860
1861 =cut
1862
1863 sub first {
1864   return $_[0]->reset->next;
1865 }
1866
1867
1868 # _rs_update_delete
1869 #
1870 # Determines whether and what type of subquery is required for the $rs operation.
1871 # If grouping is necessary either supplies its own, or verifies the current one
1872 # After all is done delegates to the proper storage method.
1873
1874 sub _rs_update_delete {
1875   my ($self, $op, $values) = @_;
1876
1877   my $rsrc = $self->result_source;
1878   my $storage = $rsrc->schema->storage;
1879
1880   my $attrs = { %{$self->_resolved_attrs} };
1881
1882   my $join_classifications;
1883   my ($existing_group_by) = delete @{$attrs}{qw(group_by _grouped_by_distinct)};
1884
1885   # do we need a subquery for any reason?
1886   my $needs_subq = (
1887     defined $existing_group_by
1888       or
1889     # if {from} is unparseable wrap a subq
1890     ref($attrs->{from}) ne 'ARRAY'
1891       or
1892     # limits call for a subq
1893     $self->_has_resolved_attr(qw/rows offset/)
1894   );
1895
1896   # simplify the joinmap, so we can further decide if a subq is necessary
1897   if (!$needs_subq and @{$attrs->{from}} > 1) {
1898
1899     ($attrs->{from}, $join_classifications) =
1900       $storage->_prune_unused_joins ($attrs);
1901
1902     # any non-pruneable non-local restricting joins imply subq
1903     $needs_subq = defined List::Util::first { $_ ne $attrs->{alias} } keys %{ $join_classifications->{restricting} || {} };
1904   }
1905
1906   # check if the head is composite (by now all joins are thrown out unless $needs_subq)
1907   $needs_subq ||= (
1908     (ref $attrs->{from}[0]) ne 'HASH'
1909       or
1910     ref $attrs->{from}[0]{ $attrs->{from}[0]{-alias} }
1911   );
1912
1913   my ($cond, $guard);
1914   # do we need anything like a subquery?
1915   if (! $needs_subq) {
1916     # Most databases do not allow aliasing of tables in UPDATE/DELETE. Thus
1917     # a condition containing 'me' or other table prefixes will not work
1918     # at all. Tell SQLMaker to dequalify idents via a gross hack.
1919     $cond = do {
1920       my $sqla = $rsrc->storage->sql_maker;
1921       local $sqla->{_dequalify_idents} = 1;
1922       \[ $sqla->_recurse_where($self->{cond}) ];
1923     };
1924   }
1925   else {
1926     # we got this far - means it is time to wrap a subquery
1927     my $idcols = $rsrc->_identifying_column_set || $self->throw_exception(
1928       sprintf(
1929         "Unable to perform complex resultset %s() without an identifying set of columns on source '%s'",
1930         $op,
1931         $rsrc->source_name,
1932       )
1933     );
1934
1935     # make a new $rs selecting only the PKs (that's all we really need for the subq)
1936     delete $attrs->{$_} for qw/select as collapse/;
1937     $attrs->{columns} = [ map { "$attrs->{alias}.$_" } @$idcols ];
1938
1939     # this will be consumed by the pruner waaaaay down the stack
1940     $attrs->{_force_prune_multiplying_joins} = 1;
1941
1942     my $subrs = (ref $self)->new($rsrc, $attrs);
1943
1944     if (@$idcols == 1) {
1945       $cond = { $idcols->[0] => { -in => $subrs->as_query } };
1946     }
1947     elsif ($storage->_use_multicolumn_in) {
1948       # no syntax for calling this properly yet
1949       # !!! EXPERIMENTAL API !!! WILL CHANGE !!!
1950       $cond = $storage->sql_maker->_where_op_multicolumn_in (
1951         $idcols, # how do I convey a list of idents...? can binds reside on lhs?
1952         $subrs->as_query
1953       ),
1954     }
1955     else {
1956       # if all else fails - get all primary keys and operate over a ORed set
1957       # wrap in a transaction for consistency
1958       # this is where the group_by/multiplication starts to matter
1959       if (
1960         $existing_group_by
1961           or
1962         # we do not need to check pre-multipliers, since if the premulti is there, its
1963         # parent (who is multi) will be there too
1964         keys %{ $join_classifications->{multiplying} || {} }
1965       ) {
1966         # make sure if there is a supplied group_by it matches the columns compiled above
1967         # perfectly. Anything else can not be sanely executed on most databases so croak
1968         # right then and there
1969         if ($existing_group_by) {
1970           my @current_group_by = map
1971             { $_ =~ /\./ ? $_ : "$attrs->{alias}.$_" }
1972             @$existing_group_by
1973           ;
1974
1975           if (
1976             join ("\x00", sort @current_group_by)
1977               ne
1978             join ("\x00", sort @{$attrs->{columns}} )
1979           ) {
1980             $self->throw_exception (
1981               "You have just attempted a $op operation on a resultset which does group_by"
1982               . ' on columns other than the primary keys, while DBIC internally needs to retrieve'
1983               . ' the primary keys in a subselect. All sane RDBMS engines do not support this'
1984               . ' kind of queries. Please retry the operation with a modified group_by or'
1985               . ' without using one at all.'
1986             );
1987           }
1988         }
1989
1990         $subrs = $subrs->search({}, { group_by => $attrs->{columns} });
1991       }
1992
1993       $guard = $storage->txn_scope_guard;
1994
1995       for my $row ($subrs->cursor->all) {
1996         push @$cond, { map
1997           { $idcols->[$_] => $row->[$_] }
1998           (0 .. $#$idcols)
1999         };
2000       }
2001     }
2002   }
2003
2004   my $res = $cond ? $storage->$op (
2005     $rsrc,
2006     $op eq 'update' ? $values : (),
2007     $cond,
2008   ) : '0E0';
2009
2010   $guard->commit if $guard;
2011
2012   return $res;
2013 }
2014
2015 =head2 update
2016
2017 =over 4
2018
2019 =item Arguments: \%values
2020
2021 =item Return Value: $underlying_storage_rv
2022
2023 =back
2024
2025 Sets the specified columns in the resultset to the supplied values in a
2026 single query. Note that this will not run any accessor/set_column/update
2027 triggers, nor will it update any result object instances derived from this
2028 resultset (this includes the contents of the L<resultset cache|/set_cache>
2029 if any). See L</update_all> if you need to execute any on-update
2030 triggers or cascades defined either by you or a
2031 L<result component|DBIx::Class::Manual::Component/WHAT IS A COMPONENT>.
2032
2033 The return value is a pass through of what the underlying
2034 storage backend returned, and may vary. See L<DBI/execute> for the most
2035 common case.
2036
2037 =head3 CAVEAT
2038
2039 Note that L</update> does not process/deflate any of the values passed in.
2040 This is unlike the corresponding L<DBIx::Class::Row/update>. The user must
2041 ensure manually that any value passed to this method will stringify to
2042 something the RDBMS knows how to deal with. A notable example is the
2043 handling of L<DateTime> objects, for more info see:
2044 L<DBIx::Class::Manual::Cookbook/Formatting DateTime objects in queries>.
2045
2046 =cut
2047
2048 sub update {
2049   my ($self, $values) = @_;
2050   $self->throw_exception('Values for update must be a hash')
2051     unless ref $values eq 'HASH';
2052
2053   return $self->_rs_update_delete ('update', $values);
2054 }
2055
2056 =head2 update_all
2057
2058 =over 4
2059
2060 =item Arguments: \%values
2061
2062 =item Return Value: 1
2063
2064 =back
2065
2066 Fetches all objects and updates them one at a time via
2067 L<DBIx::Class::Row/update>. Note that C<update_all> will run DBIC defined
2068 triggers, while L</update> will not.
2069
2070 =cut
2071
2072 sub update_all {
2073   my ($self, $values) = @_;
2074   $self->throw_exception('Values for update_all must be a hash')
2075     unless ref $values eq 'HASH';
2076
2077   my $guard = $self->result_source->schema->txn_scope_guard;
2078   $_->update({%$values}) for $self->all;  # shallow copy - update will mangle it
2079   $guard->commit;
2080   return 1;
2081 }
2082
2083 =head2 delete
2084
2085 =over 4
2086
2087 =item Arguments: none
2088
2089 =item Return Value: $underlying_storage_rv
2090
2091 =back
2092
2093 Deletes the rows matching this resultset in a single query. Note that this
2094 will not run any delete triggers, nor will it alter the
2095 L<in_storage|DBIx::Class::Row/in_storage> status of any result object instances
2096 derived from this resultset (this includes the contents of the
2097 L<resultset cache|/set_cache> if any). See L</delete_all> if you need to
2098 execute any on-delete triggers or cascades defined either by you or a
2099 L<result component|DBIx::Class::Manual::Component/WHAT IS A COMPONENT>.
2100
2101 The return value is a pass through of what the underlying storage backend
2102 returned, and may vary. See L<DBI/execute> for the most common case.
2103
2104 =cut
2105
2106 sub delete {
2107   my $self = shift;
2108   $self->throw_exception('delete does not accept any arguments')
2109     if @_;
2110
2111   return $self->_rs_update_delete ('delete');
2112 }
2113
2114 =head2 delete_all
2115
2116 =over 4
2117
2118 =item Arguments: none
2119
2120 =item Return Value: 1
2121
2122 =back
2123
2124 Fetches all objects and deletes them one at a time via
2125 L<DBIx::Class::Row/delete>. Note that C<delete_all> will run DBIC defined
2126 triggers, while L</delete> will not.
2127
2128 =cut
2129
2130 sub delete_all {
2131   my $self = shift;
2132   $self->throw_exception('delete_all does not accept any arguments')
2133     if @_;
2134
2135   my $guard = $self->result_source->schema->txn_scope_guard;
2136   $_->delete for $self->all;
2137   $guard->commit;
2138   return 1;
2139 }
2140
2141 =head2 populate
2142
2143 =over 4
2144
2145 =item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ]
2146
2147 =item Return Value: L<\@result_objects|DBIx::Class::Manual::ResultClass> (scalar context) | L<@result_objects|DBIx::Class::Manual::ResultClass> (list context)
2148
2149 =back
2150
2151 Accepts either an arrayref of hashrefs or alternatively an arrayref of
2152 arrayrefs.
2153
2154 =over
2155
2156 =item NOTE
2157
2158 The context of this method call has an important effect on what is
2159 submitted to storage. In void context data is fed directly to fastpath
2160 insertion routines provided by the underlying storage (most often
2161 L<DBI/execute_for_fetch>), bypassing the L<new|DBIx::Class::Row/new> and
2162 L<insert|DBIx::Class::Row/insert> calls on the
2163 L<Result|DBIx::Class::Manual::ResultClass> class, including any
2164 augmentation of these methods provided by components. For example if you
2165 are using something like L<DBIx::Class::UUIDColumns> to create primary
2166 keys for you, you will find that your PKs are empty.  In this case you
2167 will have to explicitly force scalar or list context in order to create
2168 those values.
2169
2170 =back
2171
2172 In non-void (scalar or list) context, this method is simply a wrapper
2173 for L</create>. Depending on list or scalar context either a list of
2174 L<Result|DBIx::Class::Manual::ResultClass> objects or an arrayref
2175 containing these objects is returned.
2176
2177 When supplying data in "arrayref of arrayrefs" invocation style, the
2178 first element should be a list of column names and each subsequent
2179 element should be a data value in the earlier specified column order.
2180 For example:
2181
2182   $schema->resultset("Artist")->populate([
2183     [ qw( artistid name ) ],
2184     [ 100, 'A Formally Unknown Singer' ],
2185     [ 101, 'A singer that jumped the shark two albums ago' ],
2186     [ 102, 'An actually cool singer' ],
2187   ]);
2188
2189 For the arrayref of hashrefs style each hashref should be a structure
2190 suitable for passing to L</create>. Multi-create is also permitted with
2191 this syntax.
2192
2193   $schema->resultset("Artist")->populate([
2194      { artistid => 4, name => 'Manufactured Crap', cds => [
2195         { title => 'My First CD', year => 2006 },
2196         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
2197       ],
2198      },
2199      { artistid => 5, name => 'Angsty-Whiny Girl', cds => [
2200         { title => 'My parents sold me to a record company', year => 2005 },
2201         { title => 'Why Am I So Ugly?', year => 2006 },
2202         { title => 'I Got Surgery and am now Popular', year => 2007 }
2203       ],
2204      },
2205   ]);
2206
2207 If you attempt a void-context multi-create as in the example above (each
2208 Artist also has the related list of CDs), and B<do not> supply the
2209 necessary autoinc foreign key information, this method will proxy to the
2210 less efficient L</create>, and then throw the Result objects away. In this
2211 case there are obviously no benefits to using this method over L</create>.
2212
2213 =cut
2214
2215 sub populate {
2216   my $self = shift;
2217
2218   # this is naive and just a quick check
2219   # the types will need to be checked more thoroughly when the
2220   # multi-source populate gets added
2221   my $data = (
2222     ref $_[0] eq 'ARRAY'
2223       and
2224     ( @{$_[0]} or return )
2225       and
2226     ( ref $_[0][0] eq 'HASH' or ref $_[0][0] eq 'ARRAY' )
2227       and
2228     $_[0]
2229   ) or $self->throw_exception('Populate expects an arrayref of hashrefs or arrayref of arrayrefs');
2230
2231   # FIXME - no cref handling
2232   # At this point assume either hashes or arrays
2233
2234   if(defined wantarray) {
2235     my (@results, $guard);
2236
2237     if (ref $data->[0] eq 'ARRAY') {
2238       # column names only, nothing to do
2239       return if @$data == 1;
2240
2241       $guard = $self->result_source->schema->storage->txn_scope_guard
2242         if @$data > 2;
2243
2244       @results = map
2245         { my $vals = $_; $self->new_result({ map { $data->[0][$_] => $vals->[$_] } 0..$#{$data->[0]} })->insert }
2246         @{$data}[1 .. $#$data]
2247       ;
2248     }
2249     else {
2250
2251       $guard = $self->result_source->schema->storage->txn_scope_guard
2252         if @$data > 1;
2253
2254       @results = map { $self->new_result($_)->insert } @$data;
2255     }
2256
2257     $guard->commit if $guard;
2258     return wantarray ? @results : \@results;
2259   }
2260
2261   # we have to deal with *possibly incomplete* related data
2262   # this means we have to walk the data structure twice
2263   # whether we want this or not
2264   # jnap, I hate you ;)
2265   my $rsrc = $self->result_source;
2266   my $rel_info = { map { $_ => $rsrc->relationship_info($_) } $rsrc->relationships };
2267
2268   my ($colinfo, $colnames, $slices_with_rels);
2269   my $data_start = 0;
2270
2271   DATA_SLICE:
2272   for my $i (0 .. $#$data) {
2273
2274     my $current_slice_seen_rel_infos;
2275
2276 ### Determine/Supplement collists
2277 ### BEWARE - This is a hot piece of code, a lot of weird idioms were used
2278     if( ref $data->[$i] eq 'ARRAY' ) {
2279
2280       # positional(!) explicit column list
2281       if ($i == 0) {
2282         # column names only, nothing to do
2283         return if @$data == 1;
2284
2285         $colinfo->{$data->[0][$_]} = { pos => $_, name => $data->[0][$_] } and push @$colnames, $data->[0][$_]
2286           for 0 .. $#{$data->[0]};
2287
2288         $data_start = 1;
2289
2290         next DATA_SLICE;
2291       }
2292       else {
2293         for (values %$colinfo) {
2294           if ($_->{is_rel} ||= (
2295             $rel_info->{$_->{name}}
2296               and
2297             (
2298               ref $data->[$i][$_->{pos}] eq 'ARRAY'
2299                 or
2300               ref $data->[$i][$_->{pos}] eq 'HASH'
2301                 or
2302               ( defined blessed $data->[$i][$_->{pos}] and $data->[$i][$_->{pos}]->isa('DBIx::Class::Row') )
2303             )
2304               and
2305             1
2306           )) {
2307
2308             # moar sanity check... sigh
2309             for ( ref $data->[$i][$_->{pos}] eq 'ARRAY' ? @{$data->[$i][$_->{pos}]} : $data->[$i][$_->{pos}] ) {
2310               if ( defined blessed $_ and $_->isa('DBIx::Class::Row' ) ) {
2311                 carp_unique("Fast-path populate() with supplied related objects is not possible - falling back to regular create()");
2312                 return my $throwaway = $self->populate(@_);
2313               }
2314             }
2315
2316             push @$current_slice_seen_rel_infos, $rel_info->{$_->{name}};
2317           }
2318         }
2319       }
2320
2321      if ($current_slice_seen_rel_infos) {
2322         push @$slices_with_rels, { map { $colnames->[$_] => $data->[$i][$_] } 0 .. $#$colnames };
2323
2324         # this is needed further down to decide whether or not to fallback to create()
2325         $colinfo->{$colnames->[$_]}{seen_null} ||= ! defined $data->[$i][$_]
2326           for 0 .. $#$colnames;
2327       }
2328     }
2329     elsif( ref $data->[$i] eq 'HASH' ) {
2330
2331       for ( sort keys %{$data->[$i]} ) {
2332
2333         $colinfo->{$_} ||= do {
2334
2335           $self->throw_exception("Column '$_' must be present in supplied explicit column list")
2336             if $data_start; # it will be 0 on AoH, 1 on AoA
2337
2338           push @$colnames, $_;
2339
2340           # RV
2341           { pos => $#$colnames, name => $_ }
2342         };
2343
2344         if ($colinfo->{$_}{is_rel} ||= (
2345           $rel_info->{$_}
2346             and
2347           (
2348             ref $data->[$i]{$_} eq 'ARRAY'
2349               or
2350             ref $data->[$i]{$_} eq 'HASH'
2351               or
2352             ( defined blessed $data->[$i]{$_} and $data->[$i]{$_}->isa('DBIx::Class::Row') )
2353           )
2354             and
2355           1
2356         )) {
2357
2358           # moar sanity check... sigh
2359           for ( ref $data->[$i]{$_} eq 'ARRAY' ? @{$data->[$i]{$_}} : $data->[$i]{$_} ) {
2360             if ( defined blessed $_ and $_->isa('DBIx::Class::Row' ) ) {
2361               carp_unique("Fast-path populate() with supplied related objects is not possible - falling back to regular create()");
2362               return my $throwaway = $self->populate(@_);
2363             }
2364           }
2365
2366           push @$current_slice_seen_rel_infos, $rel_info->{$_};
2367         }
2368       }
2369
2370       if ($current_slice_seen_rel_infos) {
2371         push @$slices_with_rels, $data->[$i];
2372
2373         # this is needed further down to decide whether or not to fallback to create()
2374         $colinfo->{$_}{seen_null} ||= ! defined $data->[$i]{$_}
2375           for keys %{$data->[$i]};
2376       }
2377     }
2378     else {
2379       $self->throw_exception('Unexpected populate() data structure member type: ' . ref $data->[$i] );
2380     }
2381
2382     if ( grep
2383       { $_->{attrs}{is_depends_on} }
2384       @{ $current_slice_seen_rel_infos || [] }
2385     ) {
2386       carp_unique("Fast-path populate() of belongs_to relationship data is not possible - falling back to regular create()");
2387       return my $throwaway = $self->populate(@_);
2388     }
2389   }
2390
2391   if( $slices_with_rels ) {
2392
2393     # need to exclude the rel "columns"
2394     $colnames = [ grep { ! $colinfo->{$_}{is_rel} } @$colnames ];
2395
2396     # extra sanity check - ensure the main source is in fact identifiable
2397     # the localizing of nullability is insane, but oh well... the use-case is legit
2398     my $ci = $rsrc->columns_info($colnames);
2399
2400     $ci->{$_} = { %{$ci->{$_}}, is_nullable => 0 }
2401       for grep { ! $colinfo->{$_}{seen_null} } keys %$ci;
2402
2403     unless( $rsrc->_identifying_column_set($ci) ) {
2404       carp_unique("Fast-path populate() of non-uniquely identifiable rows with related data is not possible - falling back to regular create()");
2405       return my $throwaway = $self->populate(@_);
2406     }
2407   }
2408
2409 ### inherit the data locked in the conditions of the resultset
2410   my ($rs_data) = $self->_merge_with_rscond({});
2411   delete @{$rs_data}{@$colnames};  # passed-in stuff takes precedence
2412
2413   # if anything left - decompose rs_data
2414   my $rs_data_vals;
2415   if (keys %$rs_data) {
2416      push @$rs_data_vals, $rs_data->{$_}
2417       for sort keys %$rs_data;
2418   }
2419
2420 ### start work
2421   my $guard;
2422   $guard = $rsrc->schema->storage->txn_scope_guard
2423     if $slices_with_rels;
2424
2425 ### main source data
2426   # FIXME - need to switch entirely to a coderef-based thing,
2427   # so that large sets aren't copied several times... I think
2428   $rsrc->storage->_insert_bulk(
2429     $rsrc,
2430     [ @$colnames, sort keys %$rs_data ],
2431     [ map {
2432       ref $data->[$_] eq 'ARRAY'
2433       ? (
2434           $slices_with_rels ? [ @{$data->[$_]}[0..$#$colnames], @{$rs_data_vals||[]} ]  # the collist changed
2435         : $rs_data_vals     ? [ @{$data->[$_]}, @$rs_data_vals ]
2436         :                     $data->[$_]
2437       )
2438       : [ @{$data->[$_]}{@$colnames}, @{$rs_data_vals||[]} ]
2439     } $data_start .. $#$data ],
2440   );
2441
2442 ### do the children relationships
2443   if ( $slices_with_rels ) {
2444     my @rels = grep { $colinfo->{$_}{is_rel} } keys %$colinfo
2445       or die 'wtf... please report a bug with DBIC_TRACE=1 output (stacktrace)';
2446
2447     for my $sl (@$slices_with_rels) {
2448
2449       my ($main_proto, $main_proto_rs);
2450       for my $rel (@rels) {
2451         next unless defined $sl->{$rel};
2452
2453         $main_proto ||= {
2454           %$rs_data,
2455           (map { $_ => $sl->{$_} } @$colnames),
2456         };
2457
2458         unless (defined $colinfo->{$rel}{rs}) {
2459
2460           $colinfo->{$rel}{rs} = $rsrc->related_source($rel)->resultset;
2461
2462           $colinfo->{$rel}{fk_map} = { reverse %{ $rsrc->_resolve_relationship_condition(
2463             rel_name => $rel,
2464             self_alias => "\xFE", # irrelevant
2465             foreign_alias => "\xFF", # irrelevant
2466           )->{identity_map} || {} } };
2467
2468         }
2469
2470         $colinfo->{$rel}{rs}->search({ map # only so that we inherit them values properly, no actual search
2471           {
2472             $_ => { '=' =>
2473               ( $main_proto_rs ||= $rsrc->resultset->search($main_proto) )
2474                 ->get_column( $colinfo->{$rel}{fk_map}{$_} )
2475                  ->as_query
2476             }
2477           }
2478           keys %{$colinfo->{$rel}{fk_map}}
2479         })->populate( ref $sl->{$rel} eq 'ARRAY' ? $sl->{$rel} : [ $sl->{$rel} ] );
2480
2481         1;
2482       }
2483     }
2484   }
2485
2486   $guard->commit if $guard;
2487 }
2488
2489 =head2 pager
2490
2491 =over 4
2492
2493 =item Arguments: none
2494
2495 =item Return Value: L<$pager|Data::Page>
2496
2497 =back
2498
2499 Returns a L<Data::Page> object for the current resultset. Only makes
2500 sense for queries with a C<page> attribute.
2501
2502 To get the full count of entries for a paged resultset, call
2503 C<total_entries> on the L<Data::Page> object.
2504
2505 =cut
2506
2507 sub pager {
2508   my ($self) = @_;
2509
2510   return $self->{pager} if $self->{pager};
2511
2512   my $attrs = $self->{attrs};
2513   if (!defined $attrs->{page}) {
2514     $self->throw_exception("Can't create pager for non-paged rs");
2515   }
2516   elsif ($attrs->{page} <= 0) {
2517     $self->throw_exception('Invalid page number (page-numbers are 1-based)');
2518   }
2519   $attrs->{rows} ||= 10;
2520
2521   # throw away the paging flags and re-run the count (possibly
2522   # with a subselect) to get the real total count
2523   my $count_attrs = { %$attrs };
2524   delete @{$count_attrs}{qw/rows offset page pager/};
2525
2526   my $total_rs = (ref $self)->new($self->result_source, $count_attrs);
2527
2528   require DBIx::Class::ResultSet::Pager;
2529   return $self->{pager} = DBIx::Class::ResultSet::Pager->new(
2530     sub { $total_rs->count },  #lazy-get the total
2531     $attrs->{rows},
2532     $self->{attrs}{page},
2533   );
2534 }
2535
2536 =head2 page
2537
2538 =over 4
2539
2540 =item Arguments: $page_number
2541
2542 =item Return Value: L<$resultset|/search>
2543
2544 =back
2545
2546 Returns a resultset for the $page_number page of the resultset on which page
2547 is called, where each page contains a number of rows equal to the 'rows'
2548 attribute set on the resultset (10 by default).
2549
2550 =cut
2551
2552 sub page {
2553   my ($self, $page) = @_;
2554   return (ref $self)->new($self->result_source, { %{$self->{attrs}}, page => $page });
2555 }
2556
2557 =head2 new_result
2558
2559 =over 4
2560
2561 =item Arguments: \%col_data
2562
2563 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2564
2565 =back
2566
2567 Creates a new result object in the resultset's result class and returns
2568 it. The row is not inserted into the database at this point, call
2569 L<DBIx::Class::Row/insert> to do that. Calling L<DBIx::Class::Row/in_storage>
2570 will tell you whether the result object has been inserted or not.
2571
2572 Passes the hashref of input on to L<DBIx::Class::Row/new>.
2573
2574 =cut
2575
2576 sub new_result {
2577   my ($self, $values) = @_;
2578
2579   $self->throw_exception( "new_result takes only one argument - a hashref of values" )
2580     if @_ > 2;
2581
2582   $self->throw_exception( "Result object instantiation requires a hashref as argument" )
2583     unless (ref $values eq 'HASH');
2584
2585   my ($merged_cond, $cols_from_relations) = $self->_merge_with_rscond($values);
2586
2587   my $new = $self->result_class->new({
2588     %$merged_cond,
2589     ( @$cols_from_relations
2590       ? (-cols_from_relations => $cols_from_relations)
2591       : ()
2592     ),
2593     -result_source => $self->result_source, # DO NOT REMOVE THIS, REQUIRED
2594   });
2595
2596   if (
2597     reftype($new) eq 'HASH'
2598       and
2599     ! keys %$new
2600       and
2601     blessed($new)
2602   ) {
2603     carp_unique (sprintf (
2604       "%s->new returned a blessed empty hashref - a strong indicator something is wrong with its inheritance chain",
2605       $self->result_class,
2606     ));
2607   }
2608
2609   $new;
2610 }
2611
2612 # _merge_with_rscond
2613 #
2614 # Takes a simple hash of K/V data and returns its copy merged with the
2615 # condition already present on the resultset. Additionally returns an
2616 # arrayref of value/condition names, which were inferred from related
2617 # objects (this is needed for in-memory related objects)
2618 sub _merge_with_rscond {
2619   my ($self, $data) = @_;
2620
2621   my ($implied_data, @cols_from_relations);
2622
2623   my $alias = $self->{attrs}{alias};
2624
2625   if (! defined $self->{cond}) {
2626     # just massage $data below
2627   }
2628   elsif ($self->{cond} eq UNRESOLVABLE_CONDITION) {
2629     $implied_data = $self->{attrs}{related_objects};  # nothing might have been inserted yet
2630     @cols_from_relations = keys %{ $implied_data || {} };
2631   }
2632   else {
2633     my $eqs = $self->result_source->schema->storage->_extract_fixed_condition_columns($self->{cond}, 'consider_nulls');
2634     $implied_data = { map {
2635       ( ($eqs->{$_}||'') eq UNRESOLVABLE_CONDITION ) ? () : ( $_ => $eqs->{$_} )
2636     } keys %$eqs };
2637   }
2638
2639   return (
2640     { map
2641       { %{ $self->_remove_alias($_, $alias) } }
2642       # precedence must be given to passed values over values inherited from
2643       # the cond, so the order here is important.
2644       ( $implied_data||(), $data)
2645     },
2646     \@cols_from_relations
2647   );
2648 }
2649
2650 # _has_resolved_attr
2651 #
2652 # determines if the resultset defines at least one
2653 # of the attributes supplied
2654 #
2655 # used to determine if a subquery is necessary
2656 #
2657 # supports some virtual attributes:
2658 #   -join
2659 #     This will scan for any joins being present on the resultset.
2660 #     It is not a mere key-search but a deep inspection of {from}
2661 #
2662
2663 sub _has_resolved_attr {
2664   my ($self, @attr_names) = @_;
2665
2666   my $attrs = $self->_resolved_attrs;
2667
2668   my %extra_checks;
2669
2670   for my $n (@attr_names) {
2671     if (grep { $n eq $_ } (qw/-join/) ) {
2672       $extra_checks{$n}++;
2673       next;
2674     }
2675
2676     my $attr =  $attrs->{$n};
2677
2678     next if not defined $attr;
2679
2680     if (ref $attr eq 'HASH') {
2681       return 1 if keys %$attr;
2682     }
2683     elsif (ref $attr eq 'ARRAY') {
2684       return 1 if @$attr;
2685     }
2686     else {
2687       return 1 if $attr;
2688     }
2689   }
2690
2691   # a resolved join is expressed as a multi-level from
2692   return 1 if (
2693     $extra_checks{-join}
2694       and
2695     ref $attrs->{from} eq 'ARRAY'
2696       and
2697     @{$attrs->{from}} > 1
2698   );
2699
2700   return 0;
2701 }
2702
2703 # _remove_alias
2704 #
2705 # Remove the specified alias from the specified query hash. A copy is made so
2706 # the original query is not modified.
2707
2708 sub _remove_alias {
2709   my ($self, $query, $alias) = @_;
2710
2711   my %orig = %{ $query || {} };
2712   my %unaliased;
2713
2714   foreach my $key (keys %orig) {
2715     if ($key !~ /\./) {
2716       $unaliased{$key} = $orig{$key};
2717       next;
2718     }
2719     $unaliased{$1} = $orig{$key}
2720       if $key =~ m/^(?:\Q$alias\E\.)?([^.]+)$/;
2721   }
2722
2723   return \%unaliased;
2724 }
2725
2726 =head2 as_query
2727
2728 =over 4
2729
2730 =item Arguments: none
2731
2732 =item Return Value: \[ $sql, L<@bind_values|/DBIC BIND VALUES> ]
2733
2734 =back
2735
2736 Returns the SQL query and bind vars associated with the invocant.
2737
2738 This is generally used as the RHS for a subquery.
2739
2740 =cut
2741
2742 sub as_query {
2743   my $self = shift;
2744
2745   my $attrs = { %{ $self->_resolved_attrs } };
2746
2747   my $aq = $self->result_source->storage->_select_args_to_query (
2748     $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs
2749   );
2750
2751   $aq;
2752 }
2753
2754 =head2 find_or_new
2755
2756 =over 4
2757
2758 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2759
2760 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2761
2762 =back
2763
2764   my $artist = $schema->resultset('Artist')->find_or_new(
2765     { artist => 'fred' }, { key => 'artists' });
2766
2767   $cd->cd_to_producer->find_or_new({ producer => $producer },
2768                                    { key => 'primary' });
2769
2770 Find an existing record from this resultset using L</find>. if none exists,
2771 instantiate a new result object and return it. The object will not be saved
2772 into your storage until you call L<DBIx::Class::Row/insert> on it.
2773
2774 You most likely want this method when looking for existing rows using a unique
2775 constraint that is not the primary key, or looking for related rows.
2776
2777 If you want objects to be saved immediately, use L</find_or_create> instead.
2778
2779 B<Note>: Make sure to read the documentation of L</find> and understand the
2780 significance of the C<key> attribute, as its lack may skew your search, and
2781 subsequently result in spurious new objects.
2782
2783 B<Note>: Take care when using C<find_or_new> with a table having
2784 columns with default values that you intend to be automatically
2785 supplied by the database (e.g. an auto_increment primary key column).
2786 In normal usage, the value of such columns should NOT be included at
2787 all in the call to C<find_or_new>, even when set to C<undef>.
2788
2789 =cut
2790
2791 sub find_or_new {
2792   my $self     = shift;
2793   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2794   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2795   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2796     return $row;
2797   }
2798   return $self->new_result($hash);
2799 }
2800
2801 =head2 create
2802
2803 =over 4
2804
2805 =item Arguments: \%col_data
2806
2807 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2808
2809 =back
2810
2811 Attempt to create a single new row or a row with multiple related rows
2812 in the table represented by the resultset (and related tables). This
2813 will not check for duplicate rows before inserting, use
2814 L</find_or_create> to do that.
2815
2816 To create one row for this resultset, pass a hashref of key/value
2817 pairs representing the columns of the table and the values you wish to
2818 store. If the appropriate relationships are set up, foreign key fields
2819 can also be passed an object representing the foreign row, and the
2820 value will be set to its primary key.
2821
2822 To create related objects, pass a hashref of related-object column values
2823 B<keyed on the relationship name>. If the relationship is of type C<multi>
2824 (L<DBIx::Class::Relationship/has_many>) - pass an arrayref of hashrefs.
2825 The process will correctly identify columns holding foreign keys, and will
2826 transparently populate them from the keys of the corresponding relation.
2827 This can be applied recursively, and will work correctly for a structure
2828 with an arbitrary depth and width, as long as the relationships actually
2829 exists and the correct column data has been supplied.
2830
2831 Instead of hashrefs of plain related data (key/value pairs), you may
2832 also pass new or inserted objects. New objects (not inserted yet, see
2833 L</new_result>), will be inserted into their appropriate tables.
2834
2835 Effectively a shortcut for C<< ->new_result(\%col_data)->insert >>.
2836
2837 Example of creating a new row.
2838
2839   $person_rs->create({
2840     name=>"Some Person",
2841     email=>"somebody@someplace.com"
2842   });
2843
2844 Example of creating a new row and also creating rows in a related C<has_many>
2845 or C<has_one> resultset.  Note Arrayref.
2846
2847   $artist_rs->create(
2848      { artistid => 4, name => 'Manufactured Crap', cds => [
2849         { title => 'My First CD', year => 2006 },
2850         { title => 'Yet More Tweeny-Pop crap', year => 2007 },
2851       ],
2852      },
2853   );
2854
2855 Example of creating a new row and also creating a row in a related
2856 C<belongs_to> resultset. Note Hashref.
2857
2858   $cd_rs->create({
2859     title=>"Music for Silly Walks",
2860     year=>2000,
2861     artist => {
2862       name=>"Silly Musician",
2863     }
2864   });
2865
2866 =over
2867
2868 =item WARNING
2869
2870 When subclassing ResultSet never attempt to override this method. Since
2871 it is a simple shortcut for C<< $self->new_result($attrs)->insert >>, a
2872 lot of the internals simply never call it, so your override will be
2873 bypassed more often than not. Override either L<DBIx::Class::Row/new>
2874 or L<DBIx::Class::Row/insert> depending on how early in the
2875 L</create> process you need to intervene. See also warning pertaining to
2876 L</new>.
2877
2878 =back
2879
2880 =cut
2881
2882 sub create {
2883   #my ($self, $col_data) = @_;
2884   DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
2885   return shift->new_result(shift)->insert;
2886 }
2887
2888 =head2 find_or_create
2889
2890 =over 4
2891
2892 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2893
2894 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2895
2896 =back
2897
2898   $cd->cd_to_producer->find_or_create({ producer => $producer },
2899                                       { key => 'primary' });
2900
2901 Tries to find a record based on its primary key or unique constraints; if none
2902 is found, creates one and returns that instead.
2903
2904   my $cd = $schema->resultset('CD')->find_or_create({
2905     cdid   => 5,
2906     artist => 'Massive Attack',
2907     title  => 'Mezzanine',
2908     year   => 2005,
2909   });
2910
2911 Also takes an optional C<key> attribute, to search by a specific key or unique
2912 constraint. For example:
2913
2914   my $cd = $schema->resultset('CD')->find_or_create(
2915     {
2916       artist => 'Massive Attack',
2917       title  => 'Mezzanine',
2918     },
2919     { key => 'cd_artist_title' }
2920   );
2921
2922 B<Note>: Make sure to read the documentation of L</find> and understand the
2923 significance of the C<key> attribute, as its lack may skew your search, and
2924 subsequently result in spurious row creation.
2925
2926 B<Note>: Because find_or_create() reads from the database and then
2927 possibly inserts based on the result, this method is subject to a race
2928 condition. Another process could create a record in the table after
2929 the find has completed and before the create has started. To avoid
2930 this problem, use find_or_create() inside a transaction.
2931
2932 B<Note>: Take care when using C<find_or_create> with a table having
2933 columns with default values that you intend to be automatically
2934 supplied by the database (e.g. an auto_increment primary key column).
2935 In normal usage, the value of such columns should NOT be included at
2936 all in the call to C<find_or_create>, even when set to C<undef>.
2937
2938 See also L</find> and L</update_or_create>. For information on how to declare
2939 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
2940
2941 If you need to know if an existing row was found or a new one created use
2942 L</find_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
2943 to call L<DBIx::Class::Row/insert> to save the newly created row to the
2944 database!
2945
2946   my $cd = $schema->resultset('CD')->find_or_new({
2947     cdid   => 5,
2948     artist => 'Massive Attack',
2949     title  => 'Mezzanine',
2950     year   => 2005,
2951   });
2952
2953   if( !$cd->in_storage ) {
2954       # do some stuff
2955       $cd->insert;
2956   }
2957
2958 =cut
2959
2960 sub find_or_create {
2961   my $self     = shift;
2962   my $attrs    = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
2963   my $hash     = ref $_[0] eq 'HASH' ? shift : {@_};
2964   if (keys %$hash and my $row = $self->find($hash, $attrs) ) {
2965     return $row;
2966   }
2967   return $self->new_result($hash)->insert;
2968 }
2969
2970 =head2 update_or_create
2971
2972 =over 4
2973
2974 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
2975
2976 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
2977
2978 =back
2979
2980   $resultset->update_or_create({ col => $val, ... });
2981
2982 Like L</find_or_create>, but if a row is found it is immediately updated via
2983 C<< $found_row->update (\%col_data) >>.
2984
2985
2986 Takes an optional C<key> attribute to search on a specific unique constraint.
2987 For example:
2988
2989   # In your application
2990   my $cd = $schema->resultset('CD')->update_or_create(
2991     {
2992       artist => 'Massive Attack',
2993       title  => 'Mezzanine',
2994       year   => 1998,
2995     },
2996     { key => 'cd_artist_title' }
2997   );
2998
2999   $cd->cd_to_producer->update_or_create({
3000     producer => $producer,
3001     name => 'harry',
3002   }, {
3003     key => 'primary',
3004   });
3005
3006 B<Note>: Make sure to read the documentation of L</find> and understand the
3007 significance of the C<key> attribute, as its lack may skew your search, and
3008 subsequently result in spurious row creation.
3009
3010 B<Note>: Take care when using C<update_or_create> with a table having
3011 columns with default values that you intend to be automatically
3012 supplied by the database (e.g. an auto_increment primary key column).
3013 In normal usage, the value of such columns should NOT be included at
3014 all in the call to C<update_or_create>, even when set to C<undef>.
3015
3016 See also L</find> and L</find_or_create>. For information on how to declare
3017 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
3018
3019 If you need to know if an existing row was updated or a new one created use
3020 L</update_or_new> and L<DBIx::Class::Row/in_storage> instead. Don't forget
3021 to call L<DBIx::Class::Row/insert> to save the newly created row to the
3022 database!
3023
3024 =cut
3025
3026 sub update_or_create {
3027   my $self = shift;
3028   my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
3029   my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
3030
3031   my $row = $self->find($cond, $attrs);
3032   if (defined $row) {
3033     $row->update($cond);
3034     return $row;
3035   }
3036
3037   return $self->new_result($cond)->insert;
3038 }
3039
3040 =head2 update_or_new
3041
3042 =over 4
3043
3044 =item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }?
3045
3046 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
3047
3048 =back
3049
3050   $resultset->update_or_new({ col => $val, ... });
3051
3052 Like L</find_or_new> but if a row is found it is immediately updated via
3053 C<< $found_row->update (\%col_data) >>.
3054
3055 For example:
3056
3057   # In your application
3058   my $cd = $schema->resultset('CD')->update_or_new(
3059     {
3060       artist => 'Massive Attack',
3061       title  => 'Mezzanine',
3062       year   => 1998,
3063     },
3064     { key => 'cd_artist_title' }
3065   );
3066
3067   if ($cd->in_storage) {
3068       # the cd was updated
3069   }
3070   else {
3071       # the cd is not yet in the database, let's insert it
3072       $cd->insert;
3073   }
3074
3075 B<Note>: Make sure to read the documentation of L</find> and understand the
3076 significance of the C<key> attribute, as its lack may skew your search, and
3077 subsequently result in spurious new objects.
3078
3079 B<Note>: Take care when using C<update_or_new> with a table having
3080 columns with default values that you intend to be automatically
3081 supplied by the database (e.g. an auto_increment primary key column).
3082 In normal usage, the value of such columns should NOT be included at
3083 all in the call to C<update_or_new>, even when set to C<undef>.
3084
3085 See also L</find>, L</find_or_create> and L</find_or_new>.
3086
3087 =cut
3088
3089 sub update_or_new {
3090     my $self  = shift;
3091     my $attrs = ( @_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {} );
3092     my $cond  = ref $_[0] eq 'HASH' ? shift : {@_};
3093
3094     my $row = $self->find( $cond, $attrs );
3095     if ( defined $row ) {
3096         $row->update($cond);
3097         return $row;
3098     }
3099
3100     return $self->new_result($cond);
3101 }
3102
3103 =head2 get_cache
3104
3105 =over 4
3106
3107 =item Arguments: none
3108
3109 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass> | undef
3110
3111 =back
3112
3113 Gets the contents of the cache for the resultset, if the cache is set.
3114
3115 The cache is populated either by using the L</prefetch> attribute to
3116 L</search> or by calling L</set_cache>.
3117
3118 =cut
3119
3120 sub get_cache {
3121   shift->{all_cache};
3122 }
3123
3124 =head2 set_cache
3125
3126 =over 4
3127
3128 =item Arguments: L<\@result_objs|DBIx::Class::Manual::ResultClass>
3129
3130 =item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass>
3131
3132 =back
3133
3134 Sets the contents of the cache for the resultset. Expects an arrayref
3135 of objects of the same class as those produced by the resultset. Note that
3136 if the cache is set, the resultset will return the cached objects rather
3137 than re-querying the database even if the cache attr is not set.
3138
3139 The contents of the cache can also be populated by using the
3140 L</prefetch> attribute to L</search>.
3141
3142 =cut
3143
3144 sub set_cache {
3145   my ( $self, $data ) = @_;
3146   $self->throw_exception("set_cache requires an arrayref")
3147       if defined($data) && (ref $data ne 'ARRAY');
3148   $self->{all_cache} = $data;
3149 }
3150
3151 =head2 clear_cache
3152
3153 =over 4
3154
3155 =item Arguments: none
3156
3157 =item Return Value: undef
3158
3159 =back
3160
3161 Clears the cache for the resultset.
3162
3163 =cut
3164
3165 sub clear_cache {
3166   shift->set_cache(undef);
3167 }
3168
3169 =head2 is_paged
3170
3171 =over 4
3172
3173 =item Arguments: none
3174
3175 =item Return Value: true, if the resultset has been paginated
3176
3177 =back
3178
3179 =cut
3180
3181 sub is_paged {
3182   my ($self) = @_;
3183   return !!$self->{attrs}{page};
3184 }
3185
3186 =head2 is_ordered
3187
3188 =over 4
3189
3190 =item Arguments: none
3191
3192 =item Return Value: true, if the resultset has been ordered with C<order_by>.
3193
3194 =back
3195
3196 =cut
3197
3198 sub is_ordered {
3199   my ($self) = @_;
3200   return scalar $self->result_source->storage->_extract_order_criteria($self->{attrs}{order_by});
3201 }
3202
3203 =head2 related_resultset
3204
3205 =over 4
3206
3207 =item Arguments: $rel_name
3208
3209 =item Return Value: L<$resultset|/search>
3210
3211 =back
3212
3213 Returns a related resultset for the supplied relationship name.
3214
3215   $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
3216
3217 =cut
3218
3219 sub related_resultset {
3220   my ($self, $rel) = @_;
3221
3222   return $self->{related_resultsets}{$rel}
3223     if defined $self->{related_resultsets}{$rel};
3224
3225   return $self->{related_resultsets}{$rel} = do {
3226     my $rsrc = $self->result_source;
3227     my $rel_info = $rsrc->relationship_info($rel);
3228
3229     $self->throw_exception(
3230       "search_related: result source '" . $rsrc->source_name .
3231         "' has no such relationship $rel")
3232       unless $rel_info;
3233
3234     my $attrs = $self->_chain_relationship($rel);
3235
3236     my $join_count = $attrs->{seen_join}{$rel};
3237
3238     my $alias = $self->result_source->storage
3239         ->relname_to_table_alias($rel, $join_count);
3240
3241     # since this is search_related, and we already slid the select window inwards
3242     # (the select/as attrs were deleted in the beginning), we need to flip all
3243     # left joins to inner, so we get the expected results
3244     # read the comment on top of the actual function to see what this does
3245     $attrs->{from} = $rsrc->schema->storage->_inner_join_to_node ($attrs->{from}, $alias);
3246
3247
3248     #XXX - temp fix for result_class bug. There likely is a more elegant fix -groditi
3249     delete @{$attrs}{qw(result_class alias)};
3250
3251     my $rel_source = $rsrc->related_source($rel);
3252
3253     my $new = do {
3254
3255       # The reason we do this now instead of passing the alias to the
3256       # search_rs below is that if you wrap/overload resultset on the
3257       # source you need to know what alias it's -going- to have for things
3258       # to work sanely (e.g. RestrictWithObject wants to be able to add
3259       # extra query restrictions, and these may need to be $alias.)
3260
3261       my $rel_attrs = $rel_source->resultset_attributes;
3262       local $rel_attrs->{alias} = $alias;
3263
3264       $rel_source->resultset
3265                  ->search_rs(
3266                      undef, {
3267                        %$attrs,
3268                        where => $attrs->{where},
3269                    });
3270     };
3271
3272     if (my $cache = $self->get_cache) {
3273       my @related_cache = map
3274         { $_->related_resultset($rel)->get_cache || () }
3275         @$cache
3276       ;
3277
3278       $new->set_cache([ map @$_, @related_cache ]) if @related_cache == @$cache;
3279     }
3280
3281     $new;
3282   };
3283 }
3284
3285 =head2 current_source_alias
3286
3287 =over 4
3288
3289 =item Arguments: none
3290
3291 =item Return Value: $source_alias
3292
3293 =back
3294
3295 Returns the current table alias for the result source this resultset is built
3296 on, that will be used in the SQL query. Usually it is C<me>.
3297
3298 Currently the source alias that refers to the result set returned by a
3299 L</search>/L</find> family method depends on how you got to the resultset: it's
3300 C<me> by default, but eg. L</search_related> aliases it to the related result
3301 source name (and keeps C<me> referring to the original result set). The long
3302 term goal is to make L<DBIx::Class> always alias the current resultset as C<me>
3303 (and make this method unnecessary).
3304
3305 Thus it's currently necessary to use this method in predefined queries (see
3306 L<DBIx::Class::Manual::Cookbook/Predefined searches>) when referring to the
3307 source alias of the current result set:
3308
3309   # in a result set class
3310   sub modified_by {
3311     my ($self, $user) = @_;
3312
3313     my $me = $self->current_source_alias;
3314
3315     return $self->search({
3316       "$me.modified" => $user->id,
3317     });
3318   }
3319
3320 =cut
3321
3322 sub current_source_alias {
3323   return (shift->{attrs} || {})->{alias} || 'me';
3324 }
3325
3326 =head2 as_subselect_rs
3327
3328 =over 4
3329
3330 =item Arguments: none
3331
3332 =item Return Value: L<$resultset|/search>
3333
3334 =back
3335
3336 Act as a barrier to SQL symbols.  The resultset provided will be made into a
3337 "virtual view" by including it as a subquery within the from clause.  From this
3338 point on, any joined tables are inaccessible to ->search on the resultset (as if
3339 it were simply where-filtered without joins).  For example:
3340
3341  my $rs = $schema->resultset('Bar')->search({'x.name' => 'abc'},{ join => 'x' });
3342
3343  # 'x' now pollutes the query namespace
3344
3345  # So the following works as expected
3346  my $ok_rs = $rs->search({'x.other' => 1});
3347
3348  # But this doesn't: instead of finding a 'Bar' related to two x rows (abc and
3349  # def) we look for one row with contradictory terms and join in another table
3350  # (aliased 'x_2') which we never use
3351  my $broken_rs = $rs->search({'x.name' => 'def'});
3352
3353  my $rs2 = $rs->as_subselect_rs;
3354
3355  # doesn't work - 'x' is no longer accessible in $rs2, having been sealed away
3356  my $not_joined_rs = $rs2->search({'x.other' => 1});
3357
3358  # works as expected: finds a 'table' row related to two x rows (abc and def)
3359  my $correctly_joined_rs = $rs2->search({'x.name' => 'def'});
3360
3361 Another example of when one might use this would be to select a subset of
3362 columns in a group by clause:
3363
3364  my $rs = $schema->resultset('Bar')->search(undef, {
3365    group_by => [qw{ id foo_id baz_id }],
3366  })->as_subselect_rs->search(undef, {
3367    columns => [qw{ id foo_id }]
3368  });
3369
3370 In the above example normally columns would have to be equal to the group by,
3371 but because we isolated the group by into a subselect the above works.
3372
3373 =cut
3374
3375 sub as_subselect_rs {
3376   my $self = shift;
3377
3378   my $attrs = $self->_resolved_attrs;
3379
3380   my $fresh_rs = (ref $self)->new (
3381     $self->result_source
3382   );
3383
3384   # these pieces will be locked in the subquery
3385   delete $fresh_rs->{cond};
3386   delete @{$fresh_rs->{attrs}}{qw/where bind/};
3387
3388   return $fresh_rs->search( {}, {
3389     from => [{
3390       $attrs->{alias} => $self->as_query,
3391       -alias  => $attrs->{alias},
3392       -rsrc   => $self->result_source,
3393     }],
3394     alias => $attrs->{alias},
3395   });
3396 }
3397
3398 # This code is called by search_related, and makes sure there
3399 # is clear separation between the joins before, during, and
3400 # after the relationship. This information is needed later
3401 # in order to properly resolve prefetch aliases (any alias
3402 # with a relation_chain_depth less than the depth of the
3403 # current prefetch is not considered)
3404 #
3405 # The increments happen twice per join. An even number means a
3406 # relationship specified via a search_related, whereas an odd
3407 # number indicates a join/prefetch added via attributes
3408 #
3409 # Also this code will wrap the current resultset (the one we
3410 # chain to) in a subselect IFF it contains limiting attributes
3411 sub _chain_relationship {
3412   my ($self, $rel) = @_;
3413   my $source = $self->result_source;
3414   my $attrs = { %{$self->{attrs}||{}} };
3415
3416   # we need to take the prefetch the attrs into account before we
3417   # ->_resolve_join as otherwise they get lost - captainL
3418   my $join = $self->_merge_joinpref_attr( $attrs->{join}, $attrs->{prefetch} );
3419
3420   delete @{$attrs}{qw/join prefetch collapse group_by distinct _grouped_by_distinct select as columns +select +as +columns/};
3421
3422   my $seen = { %{ (delete $attrs->{seen_join}) || {} } };
3423
3424   my $from;
3425   my @force_subq_attrs = qw/offset rows group_by having/;
3426
3427   if (
3428     ($attrs->{from} && ref $attrs->{from} ne 'ARRAY')
3429       ||
3430     $self->_has_resolved_attr (@force_subq_attrs)
3431   ) {
3432     # Nuke the prefetch (if any) before the new $rs attrs
3433     # are resolved (prefetch is useless - we are wrapping
3434     # a subquery anyway).
3435     my $rs_copy = $self->search;
3436     $rs_copy->{attrs}{join} = $self->_merge_joinpref_attr (
3437       $rs_copy->{attrs}{join},
3438       delete $rs_copy->{attrs}{prefetch},
3439     );
3440
3441     $from = [{
3442       -rsrc   => $source,
3443       -alias  => $attrs->{alias},
3444       $attrs->{alias} => $rs_copy->as_query,
3445     }];
3446     delete @{$attrs}{@force_subq_attrs, qw/where bind/};
3447     $seen->{-relation_chain_depth} = 0;
3448   }
3449   elsif ($attrs->{from}) {  #shallow copy suffices
3450     $from = [ @{$attrs->{from}} ];
3451   }
3452   else {
3453     $from = [{
3454       -rsrc  => $source,
3455       -alias => $attrs->{alias},
3456       $attrs->{alias} => $source->from,
3457     }];
3458   }
3459
3460   my $jpath = ($seen->{-relation_chain_depth})
3461     ? $from->[-1][0]{-join_path}
3462     : [];
3463
3464   my @requested_joins = $source->_resolve_join(
3465     $join,
3466     $attrs->{alias},
3467     $seen,
3468     $jpath,
3469   );
3470
3471   push @$from, @requested_joins;
3472
3473   $seen->{-relation_chain_depth}++;
3474
3475   # if $self already had a join/prefetch specified on it, the requested
3476   # $rel might very well be already included. What we do in this case
3477   # is effectively a no-op (except that we bump up the chain_depth on
3478   # the join in question so we could tell it *is* the search_related)
3479   my $already_joined;
3480
3481   # we consider the last one thus reverse
3482   for my $j (reverse @requested_joins) {
3483     my ($last_j) = keys %{$j->[0]{-join_path}[-1]};
3484     if ($rel eq $last_j) {
3485       $j->[0]{-relation_chain_depth}++;
3486       $already_joined++;
3487       last;
3488     }
3489   }
3490
3491   unless ($already_joined) {
3492     push @$from, $source->_resolve_join(
3493       $rel,
3494       $attrs->{alias},
3495       $seen,
3496       $jpath,
3497     );
3498   }
3499
3500   $seen->{-relation_chain_depth}++;
3501
3502   return {%$attrs, from => $from, seen_join => $seen};
3503 }
3504
3505 sub _resolved_attrs {
3506   my $self = shift;
3507   return $self->{_attrs} if $self->{_attrs};
3508
3509   my $attrs  = { %{ $self->{attrs} || {} } };
3510   my $source = $attrs->{result_source} = $self->result_source;
3511   my $alias  = $attrs->{alias};
3512
3513   $self->throw_exception("Specifying distinct => 1 in conjunction with collapse => 1 is unsupported")
3514     if $attrs->{collapse} and $attrs->{distinct};
3515
3516   # default selection list
3517   $attrs->{columns} = [ $source->columns ]
3518     unless List::Util::first { exists $attrs->{$_} } qw/columns cols select as/;
3519
3520   # merge selectors together
3521   for (qw/columns select as/) {
3522     $attrs->{$_} = $self->_merge_attr($attrs->{$_}, delete $attrs->{"+$_"})
3523       if $attrs->{$_} or $attrs->{"+$_"};
3524   }
3525
3526   # disassemble columns
3527   my (@sel, @as);
3528   if (my $cols = delete $attrs->{columns}) {
3529     for my $c (ref $cols eq 'ARRAY' ? @$cols : $cols) {
3530       if (ref $c eq 'HASH') {
3531         for my $as (sort keys %$c) {
3532           push @sel, $c->{$as};
3533           push @as, $as;
3534         }
3535       }
3536       else {
3537         push @sel, $c;
3538         push @as, $c;
3539       }
3540     }
3541   }
3542
3543   # when trying to weed off duplicates later do not go past this point -
3544   # everything added from here on is unbalanced "anyone's guess" stuff
3545   my $dedup_stop_idx = $#as;
3546
3547   push @as, @{ ref $attrs->{as} eq 'ARRAY' ? $attrs->{as} : [ $attrs->{as} ] }
3548     if $attrs->{as};
3549   push @sel, @{ ref $attrs->{select} eq 'ARRAY' ? $attrs->{select} : [ $attrs->{select} ] }
3550     if $attrs->{select};
3551
3552   # assume all unqualified selectors to apply to the current alias (legacy stuff)
3553   $_ = (ref $_ or $_ =~ /\./) ? $_ : "$alias.$_" for @sel;
3554
3555   # disqualify all $alias.col as-bits (inflate-map mandated)
3556   $_ = ($_ =~ /^\Q$alias.\E(.+)$/) ? $1 : $_ for @as;
3557
3558   # de-duplicate the result (remove *identical* select/as pairs)
3559   # and also die on duplicate {as} pointing to different {select}s
3560   # not using a c-style for as the condition is prone to shrinkage
3561   my $seen;
3562   my $i = 0;
3563   while ($i <= $dedup_stop_idx) {
3564     if ($seen->{"$sel[$i] \x00\x00 $as[$i]"}++) {
3565       splice @sel, $i, 1;
3566       splice @as, $i, 1;
3567       $dedup_stop_idx--;
3568     }
3569     elsif ($seen->{$as[$i]}++) {
3570       $self->throw_exception(
3571         "inflate_result() alias '$as[$i]' specified twice with different SQL-side {select}-ors"
3572       );
3573     }
3574     else {
3575       $i++;
3576     }
3577   }
3578
3579   $attrs->{select} = \@sel;
3580   $attrs->{as} = \@as;
3581
3582   $attrs->{from} ||= [{
3583     -rsrc   => $source,
3584     -alias  => $self->{attrs}{alias},
3585     $self->{attrs}{alias} => $source->from,
3586   }];
3587
3588   if ( $attrs->{join} || $attrs->{prefetch} ) {
3589
3590     $self->throw_exception ('join/prefetch can not be used with a custom {from}')
3591       if ref $attrs->{from} ne 'ARRAY';
3592
3593     my $join = (delete $attrs->{join}) || {};
3594
3595     if ( defined $attrs->{prefetch} ) {
3596       $join = $self->_merge_joinpref_attr( $join, $attrs->{prefetch} );
3597     }
3598
3599     $attrs->{from} =    # have to copy here to avoid corrupting the original
3600       [
3601         @{ $attrs->{from} },
3602         $source->_resolve_join(
3603           $join,
3604           $alias,
3605           { %{ $attrs->{seen_join} || {} } },
3606           ( $attrs->{seen_join} && keys %{$attrs->{seen_join}})
3607             ? $attrs->{from}[-1][0]{-join_path}
3608             : []
3609           ,
3610         )
3611       ];
3612   }
3613
3614   for my $attr (qw(order_by group_by)) {
3615
3616     if ( defined $attrs->{$attr} ) {
3617       $attrs->{$attr} = (
3618         ref( $attrs->{$attr} ) eq 'ARRAY'
3619         ? [ @{ $attrs->{$attr} } ]
3620         : [ $attrs->{$attr} || () ]
3621       );
3622
3623       delete $attrs->{$attr} unless @{$attrs->{$attr}};
3624     }
3625   }
3626
3627   # generate selections based on the prefetch helper
3628   my ($prefetch, @prefetch_select, @prefetch_as);
3629   $prefetch = $self->_merge_joinpref_attr( {}, delete $attrs->{prefetch} )
3630     if defined $attrs->{prefetch};
3631
3632   if ($prefetch) {
3633
3634     $self->throw_exception("Unable to prefetch, resultset contains an unnamed selector $attrs->{_dark_selector}{string}")
3635       if $attrs->{_dark_selector};
3636
3637     $self->throw_exception("Specifying prefetch in conjunction with an explicit collapse => 0 is unsupported")
3638       if defined $attrs->{collapse} and ! $attrs->{collapse};
3639
3640     $attrs->{collapse} = 1;
3641
3642     # this is a separate structure (we don't look in {from} directly)
3643     # as the resolver needs to shift things off the lists to work
3644     # properly (identical-prefetches on different branches)
3645     my $join_map = {};
3646     if (ref $attrs->{from} eq 'ARRAY') {
3647
3648       my $start_depth = $attrs->{seen_join}{-relation_chain_depth} || 0;
3649
3650       for my $j ( @{$attrs->{from}}[1 .. $#{$attrs->{from}} ] ) {
3651         next unless $j->[0]{-alias};
3652         next unless $j->[0]{-join_path};
3653         next if ($j->[0]{-relation_chain_depth} || 0) < $start_depth;
3654
3655         my @jpath = map { keys %$_ } @{$j->[0]{-join_path}};
3656
3657         my $p = $join_map;
3658         $p = $p->{$_} ||= {} for @jpath[ ($start_depth/2) .. $#jpath]; #only even depths are actual jpath boundaries
3659         push @{$p->{-join_aliases} }, $j->[0]{-alias};
3660       }
3661     }
3662
3663     my @prefetch = $source->_resolve_prefetch( $prefetch, $alias, $join_map );
3664
3665     # save these for after distinct resolution
3666     @prefetch_select = map { $_->[0] } @prefetch;
3667     @prefetch_as = map { $_->[1] } @prefetch;
3668   }
3669
3670   # run through the resulting joinstructure (starting from our current slot)
3671   # and unset collapse if proven unnecessary
3672   #
3673   # also while we are at it find out if the current root source has
3674   # been premultiplied by previous related_source chaining
3675   #
3676   # this allows to predict whether a root object with all other relation
3677   # data set to NULL is in fact unique
3678   if ($attrs->{collapse}) {
3679
3680     if (ref $attrs->{from} eq 'ARRAY') {
3681
3682       if (@{$attrs->{from}} == 1) {
3683         # no joins - no collapse
3684         $attrs->{collapse} = 0;
3685       }
3686       else {
3687         # find where our table-spec starts
3688         my @fromlist = @{$attrs->{from}};
3689         while (@fromlist) {
3690           my $t = shift @fromlist;
3691
3692           my $is_multi;
3693           # me vs join from-spec distinction - a ref means non-root
3694           if (ref $t eq 'ARRAY') {
3695             $t = $t->[0];
3696             $is_multi ||= ! $t->{-is_single};
3697           }
3698           last if ($t->{-alias} && $t->{-alias} eq $alias);
3699           $attrs->{_main_source_premultiplied} ||= $is_multi;
3700         }
3701
3702         # no non-singles remaining, nor any premultiplication - nothing to collapse
3703         if (
3704           ! $attrs->{_main_source_premultiplied}
3705             and
3706           ! List::Util::first { ! $_->[0]{-is_single} } @fromlist
3707         ) {
3708           $attrs->{collapse} = 0;
3709         }
3710       }
3711     }
3712
3713     else {
3714       # if we can not analyze the from - err on the side of safety
3715       $attrs->{_main_source_premultiplied} = 1;
3716     }
3717   }
3718
3719   # generate the distinct induced group_by before injecting the prefetched select/as parts
3720   if (delete $attrs->{distinct}) {
3721     if ($attrs->{group_by}) {
3722       carp_unique ("Useless use of distinct on a grouped resultset ('distinct' is ignored when a 'group_by' is present)");
3723     }
3724     else {
3725       $attrs->{_grouped_by_distinct} = 1;
3726       # distinct affects only the main selection part, not what prefetch may add below
3727       ($attrs->{group_by}, my $new_order) = $source->storage->_group_over_selection($attrs);
3728
3729       # FIXME possibly ignore a rewritten order_by (may turn out to be an issue)
3730       # The thinking is: if we are collapsing the subquerying prefetch engine will
3731       # rip stuff apart for us anyway, and we do not want to have a potentially
3732       # function-converted external order_by
3733       # ( there is an explicit if ( collapse && _grouped_by_distinct ) check in DBIHacks )
3734       $attrs->{order_by} = $new_order unless $attrs->{collapse};
3735     }
3736   }
3737
3738   # inject prefetch-bound selection (if any)
3739   push @{$attrs->{select}}, @prefetch_select;
3740   push @{$attrs->{as}}, @prefetch_as;
3741
3742   $attrs->{_simple_passthrough_construction} = !(
3743     $attrs->{collapse}
3744       or
3745     grep { $_ =~ /\./ } @{$attrs->{as}}
3746   );
3747
3748   # if both page and offset are specified, produce a combined offset
3749   # even though it doesn't make much sense, this is what pre 081xx has
3750   # been doing
3751   if (my $page = delete $attrs->{page}) {
3752     $attrs->{offset} =
3753       ($attrs->{rows} * ($page - 1))
3754             +
3755       ($attrs->{offset} || 0)
3756     ;
3757   }
3758
3759   return $self->{_attrs} = $attrs;
3760 }
3761
3762 sub _rollout_attr {
3763   my ($self, $attr) = @_;
3764
3765   if (ref $attr eq 'HASH') {
3766     return $self->_rollout_hash($attr);
3767   } elsif (ref $attr eq 'ARRAY') {
3768     return $self->_rollout_array($attr);
3769   } else {
3770     return [$attr];
3771   }
3772 }
3773
3774 sub _rollout_array {
3775   my ($self, $attr) = @_;
3776
3777   my @rolled_array;
3778   foreach my $element (@{$attr}) {
3779     if (ref $element eq 'HASH') {
3780       push( @rolled_array, @{ $self->_rollout_hash( $element ) } );
3781     } elsif (ref $element eq 'ARRAY') {
3782       #  XXX - should probably recurse here
3783       push( @rolled_array, @{$self->_rollout_array($element)} );
3784     } else {
3785       push( @rolled_array, $element );
3786     }
3787   }
3788   return \@rolled_array;
3789 }
3790
3791 sub _rollout_hash {
3792   my ($self, $attr) = @_;
3793
3794   my @rolled_array;
3795   foreach my $key (keys %{$attr}) {
3796     push( @rolled_array, { $key => $attr->{$key} } );
3797   }
3798   return \@rolled_array;
3799 }
3800
3801 sub _calculate_score {
3802   my ($self, $a, $b) = @_;
3803
3804   if (defined $a xor defined $b) {
3805     return 0;
3806   }
3807   elsif (not defined $a) {
3808     return 1;
3809   }
3810
3811   if (ref $b eq 'HASH') {
3812     my ($b_key) = keys %{$b};
3813     if (ref $a eq 'HASH') {
3814       my ($a_key) = keys %{$a};
3815       if ($a_key eq $b_key) {
3816         return (1 + $self->_calculate_score( $a->{$a_key}, $b->{$b_key} ));
3817       } else {
3818         return 0;
3819       }
3820     } else {
3821       return ($a eq $b_key) ? 1 : 0;
3822     }
3823   } else {
3824     if (ref $a eq 'HASH') {
3825       my ($a_key) = keys %{$a};
3826       return ($b eq $a_key) ? 1 : 0;
3827     } else {
3828       return ($b eq $a) ? 1 : 0;
3829     }
3830   }
3831 }
3832
3833 sub _merge_joinpref_attr {
3834   my ($self, $orig, $import) = @_;
3835
3836   return $import unless defined($orig);
3837   return $orig unless defined($import);
3838
3839   $orig = $self->_rollout_attr($orig);
3840   $import = $self->_rollout_attr($import);
3841
3842   my $seen_keys;
3843   foreach my $import_element ( @{$import} ) {
3844     # find best candidate from $orig to merge $b_element into
3845     my $best_candidate = { position => undef, score => 0 }; my $position = 0;
3846     foreach my $orig_element ( @{$orig} ) {
3847       my $score = $self->_calculate_score( $orig_element, $import_element );
3848       if ($score > $best_candidate->{score}) {
3849         $best_candidate->{position} = $position;
3850         $best_candidate->{score} = $score;
3851       }
3852       $position++;
3853     }
3854     my ($import_key) = ( ref $import_element eq 'HASH' ) ? keys %{$import_element} : ($import_element);
3855     $import_key = '' if not defined $import_key;
3856
3857     if ($best_candidate->{score} == 0 || exists $seen_keys->{$import_key}) {
3858       push( @{$orig}, $import_element );
3859     } else {
3860       my $orig_best = $orig->[$best_candidate->{position}];
3861       # merge orig_best and b_element together and replace original with merged
3862       if (ref $orig_best ne 'HASH') {
3863         $orig->[$best_candidate->{position}] = $import_element;
3864       } elsif (ref $import_element eq 'HASH') {
3865         my ($key) = keys %{$orig_best};
3866         $orig->[$best_candidate->{position}] = { $key => $self->_merge_joinpref_attr($orig_best->{$key}, $import_element->{$key}) };
3867       }
3868     }
3869     $seen_keys->{$import_key} = 1; # don't merge the same key twice
3870   }
3871
3872   return @$orig ? $orig : ();
3873 }
3874
3875 {
3876   my $hm;
3877
3878   sub _merge_attr {
3879     $hm ||= do {
3880       require Hash::Merge;
3881       my $hm = Hash::Merge->new;
3882
3883       $hm->specify_behavior({
3884         SCALAR => {
3885           SCALAR => sub {
3886             my ($defl, $defr) = map { defined $_ } (@_[0,1]);
3887
3888             if ($defl xor $defr) {
3889               return [ $defl ? $_[0] : $_[1] ];
3890             }
3891             elsif (! $defl) {
3892               return [];
3893             }
3894             elsif (__HM_DEDUP and $_[0] eq $_[1]) {
3895               return [ $_[0] ];
3896             }
3897             else {
3898               return [$_[0], $_[1]];
3899             }
3900           },
3901           ARRAY => sub {
3902             return $_[1] if !defined $_[0];
3903             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3904             return [$_[0], @{$_[1]}]
3905           },
3906           HASH  => sub {
3907             return [] if !defined $_[0] and !keys %{$_[1]};
3908             return [ $_[1] ] if !defined $_[0];
3909             return [ $_[0] ] if !keys %{$_[1]};
3910             return [$_[0], $_[1]]
3911           },
3912         },
3913         ARRAY => {
3914           SCALAR => sub {
3915             return $_[0] if !defined $_[1];
3916             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3917             return [@{$_[0]}, $_[1]]
3918           },
3919           ARRAY => sub {
3920             my @ret = @{$_[0]} or return $_[1];
3921             return [ @ret, @{$_[1]} ] unless __HM_DEDUP;
3922             my %idx = map { $_ => 1 } @ret;
3923             push @ret, grep { ! defined $idx{$_} } (@{$_[1]});
3924             \@ret;
3925           },
3926           HASH => sub {
3927             return [ $_[1] ] if ! @{$_[0]};
3928             return $_[0] if !keys %{$_[1]};
3929             return $_[0] if __HM_DEDUP and List::Util::first { $_ eq $_[1] } @{$_[0]};
3930             return [ @{$_[0]}, $_[1] ];
3931           },
3932         },
3933         HASH => {
3934           SCALAR => sub {
3935             return [] if !keys %{$_[0]} and !defined $_[1];
3936             return [ $_[0] ] if !defined $_[1];
3937             return [ $_[1] ] if !keys %{$_[0]};
3938             return [$_[0], $_[1]]
3939           },
3940           ARRAY => sub {
3941             return [] if !keys %{$_[0]} and !@{$_[1]};
3942             return [ $_[0] ] if !@{$_[1]};
3943             return $_[1] if !keys %{$_[0]};
3944             return $_[1] if __HM_DEDUP and List::Util::first { $_ eq $_[0] } @{$_[1]};
3945             return [ $_[0], @{$_[1]} ];
3946           },
3947           HASH => sub {
3948             return [] if !keys %{$_[0]} and !keys %{$_[1]};
3949             return [ $_[0] ] if !keys %{$_[1]};
3950             return [ $_[1] ] if !keys %{$_[0]};
3951             return [ $_[0] ] if $_[0] eq $_[1];
3952             return [ $_[0], $_[1] ];
3953           },
3954         }
3955       } => 'DBIC_RS_ATTR_MERGER');
3956       $hm;
3957     };
3958
3959     return $hm->merge ($_[1], $_[2]);
3960   }
3961 }
3962
3963 sub STORABLE_freeze {
3964   my ($self, $cloning) = @_;
3965   my $to_serialize = { %$self };
3966
3967   # A cursor in progress can't be serialized (and would make little sense anyway)
3968   # the parser can be regenerated (and can't be serialized)
3969   delete @{$to_serialize}{qw/cursor _row_parser _result_inflator/};
3970
3971   # nor is it sensical to store a not-yet-fired-count pager
3972   if ($to_serialize->{pager} and ref $to_serialize->{pager}{total_entries} eq 'CODE') {
3973     delete $to_serialize->{pager};
3974   }
3975
3976   Storable::nfreeze($to_serialize);
3977 }
3978
3979 # need this hook for symmetry
3980 sub STORABLE_thaw {
3981   my ($self, $cloning, $serialized) = @_;
3982
3983   %$self = %{ Storable::thaw($serialized) };
3984
3985   $self;
3986 }
3987
3988
3989 =head2 throw_exception
3990
3991 See L<DBIx::Class::Schema/throw_exception> for details.
3992
3993 =cut
3994
3995 sub throw_exception {
3996   my $self=shift;
3997
3998   if (ref $self and my $rsrc = $self->result_source) {
3999     $rsrc->throw_exception(@_)
4000   }
4001   else {
4002     DBIx::Class::Exception->throw(@_);
4003   }
4004 }
4005
4006 1;
4007
4008 __END__
4009
4010 # XXX: FIXME: Attributes docs need clearing up
4011
4012 =head1 ATTRIBUTES
4013
4014 Attributes are used to refine a ResultSet in various ways when
4015 searching for data. They can be passed to any method which takes an
4016 C<\%attrs> argument. See L</search>, L</search_rs>, L</find>,
4017 L</count>.
4018
4019 Default attributes can be set on the result class using
4020 L<DBIx::Class::ResultSource/resultset_attributes>.  (Please read
4021 the CAVEATS on that feature before using it!)
4022
4023 These are in no particular order:
4024
4025 =head2 order_by
4026
4027 =over 4
4028
4029 =item Value: ( $order_by | \@order_by | \%order_by )
4030
4031 =back
4032
4033 Which column(s) to order the results by.
4034
4035 [The full list of suitable values is documented in
4036 L<SQL::Abstract/"ORDER BY CLAUSES">; the following is a summary of
4037 common options.]
4038
4039 If a single column name, or an arrayref of names is supplied, the
4040 argument is passed through directly to SQL. The hashref syntax allows
4041 for connection-agnostic specification of ordering direction:
4042
4043  For descending order:
4044
4045   order_by => { -desc => [qw/col1 col2 col3/] }
4046
4047  For explicit ascending order:
4048
4049   order_by => { -asc => 'col' }
4050
4051 The old scalarref syntax (i.e. order_by => \'year DESC') is still
4052 supported, although you are strongly encouraged to use the hashref
4053 syntax as outlined above.
4054
4055 =head2 columns
4056
4057 =over 4
4058
4059 =item Value: \@columns | \%columns | $column
4060
4061 =back
4062
4063 Shortcut to request a particular set of columns to be retrieved. Each
4064 column spec may be a string (a table column name), or a hash (in which
4065 case the key is the C<as> value, and the value is used as the C<select>
4066 expression). Adds the L</current_source_alias> onto the start of any column without a C<.> in
4067 it and sets C<select> from that, then auto-populates C<as> from
4068 C<select> as normal. (You may also use the C<cols> attribute, as in
4069 earlier versions of DBIC, but this is deprecated)
4070
4071 Essentially C<columns> does the same as L</select> and L</as>.
4072
4073     columns => [ 'some_column', { dbic_slot => 'another_column' } ]
4074
4075 is the same as
4076
4077     select => [qw(some_column another_column)],
4078     as     => [qw(some_column dbic_slot)]
4079
4080 If you want to individually retrieve related columns (in essence perform
4081 manual prefetch) you have to make sure to specify the correct inflation slot
4082 chain such that it matches existing relationships:
4083
4084     my $rs = $schema->resultset('Artist')->search({}, {
4085         # required to tell DBIC to collapse has_many relationships
4086         collapse => 1,
4087         join     => { cds => 'tracks'},
4088         '+columns'  => {
4089           'cds.cdid'         => 'cds.cdid',
4090           'cds.tracks.title' => 'tracks.title',
4091         },
4092     });
4093
4094 Like elsewhere, literal SQL or literal values can be included by using a
4095 scalar reference or a literal bind value, and these values will be available
4096 in the result with C<get_column> (see also
4097 L<SQL::Abstract/Literal SQL and value type operators>):
4098
4099     # equivalent SQL: SELECT 1, 'a string', IF(my_column,?,?) ...
4100     # bind values: $true_value, $false_value
4101     columns => [
4102         {
4103             foo => \1,
4104             bar => \q{'a string'},
4105             baz => \[ 'IF(my_column,?,?)', $true_value, $false_value ],
4106         }
4107     ]
4108
4109 =head2 +columns
4110
4111 B<NOTE:> You B<MUST> explicitly quote C<'+columns'> when using this attribute.
4112 Not doing so causes Perl to incorrectly interpret C<+columns> as a bareword
4113 with a unary plus operator before it, which is the same as simply C<columns>.
4114
4115 =over 4
4116
4117 =item Value: \@extra_columns
4118
4119 =back
4120
4121 Indicates additional columns to be selected from storage. Works the same as
4122 L</columns> but adds columns to the current selection. (You may also use the
4123 C<include_columns> attribute, as in earlier versions of DBIC, but this is
4124 deprecated)
4125
4126   $schema->resultset('CD')->search(undef, {
4127     '+columns' => ['artist.name'],
4128     join => ['artist']
4129   });
4130
4131 would return all CDs and include a 'name' column to the information
4132 passed to object inflation. Note that the 'artist' is the name of the
4133 column (or relationship) accessor, and 'name' is the name of the column
4134 accessor in the related table.
4135
4136 =head2 select
4137
4138 =over 4
4139
4140 =item Value: \@select_columns
4141
4142 =back
4143
4144 Indicates which columns should be selected from the storage. You can use
4145 column names, or in the case of RDBMS back ends, function or stored procedure
4146 names:
4147
4148   $rs = $schema->resultset('Employee')->search(undef, {
4149     select => [
4150       'name',
4151       { count => 'employeeid' },
4152       { max => { length => 'name' }, -as => 'longest_name' }
4153     ]
4154   });
4155
4156   # Equivalent SQL
4157   SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee
4158
4159 B<NOTE:> You will almost always need a corresponding L</as> attribute when you
4160 use L</select>, to instruct DBIx::Class how to store the result of the column.
4161
4162 Also note that the L</as> attribute has B<nothing to do> with the SQL-side
4163 C<AS> identifier aliasing. You B<can> alias a function (so you can use it e.g.
4164 in an C<ORDER BY> clause), however this is done via the C<-as> B<select
4165 function attribute> supplied as shown in the example above.
4166
4167 =head2 +select
4168
4169 B<NOTE:> You B<MUST> explicitly quote C<'+select'> when using this attribute.
4170 Not doing so causes Perl to incorrectly interpret C<+select> as a bareword
4171 with a unary plus operator before it, which is the same as simply C<select>.
4172
4173 =over 4
4174
4175 =item Value: \@extra_select_columns
4176
4177 =back
4178
4179 Indicates additional columns to be selected from storage.  Works the same as
4180 L</select> but adds columns to the current selection, instead of specifying
4181 a new explicit list.
4182
4183 =head2 as
4184
4185 =over 4
4186
4187 =item Value: \@inflation_names
4188
4189 =back
4190
4191 Indicates DBIC-side names for object inflation. That is L</as> indicates the
4192 slot name in which the column value will be stored within the
4193 L<Row|DBIx::Class::Row> object. The value will then be accessible via this
4194 identifier by the C<get_column> method (or via the object accessor B<if one
4195 with the same name already exists>) as shown below.
4196
4197 The L</as> attribute has B<nothing to do> with the SQL-side identifier
4198 aliasing C<AS>. See L</select> for details.
4199
4200   $rs = $schema->resultset('Employee')->search(undef, {
4201     select => [
4202       'name',
4203       { count => 'employeeid' },
4204       { max => { length => 'name' }, -as => 'longest_name' }
4205     ],
4206     as => [qw/
4207       name
4208       employee_count
4209       max_name_length
4210     /],
4211   });
4212
4213 If the object against which the search is performed already has an accessor
4214 matching a column name specified in C<as>, the value can be retrieved using
4215 the accessor as normal:
4216
4217   my $name = $employee->name();
4218
4219 If on the other hand an accessor does not exist in the object, you need to
4220 use C<get_column> instead:
4221
4222   my $employee_count = $employee->get_column('employee_count');
4223
4224 You can create your own accessors if required - see
4225 L<DBIx::Class::Manual::Cookbook> for details.
4226
4227 =head2 +as
4228
4229 B<NOTE:> You B<MUST> explicitly quote C<'+as'> when using this attribute.
4230 Not doing so causes Perl to incorrectly interpret C<+as> as a bareword
4231 with a unary plus operator before it, which is the same as simply C<as>.
4232
4233 =over 4
4234
4235 =item Value: \@extra_inflation_names
4236
4237 =back
4238
4239 Indicates additional inflation names for selectors added via L</+select>. See L</as>.
4240
4241 =head2 join
4242
4243 =over 4
4244
4245 =item Value: ($rel_name | \@rel_names | \%rel_names)
4246
4247 =back
4248
4249 Contains a list of relationships that should be joined for this query.  For
4250 example:
4251
4252   # Get CDs by Nine Inch Nails
4253   my $rs = $schema->resultset('CD')->search(
4254     { 'artist.name' => 'Nine Inch Nails' },
4255     { join => 'artist' }
4256   );
4257
4258 Can also contain a hash reference to refer to the other relation's relations.
4259 For example:
4260
4261   package MyApp::Schema::Track;
4262   use base qw/DBIx::Class/;
4263   __PACKAGE__->table('track');
4264   __PACKAGE__->add_columns(qw/trackid cd position title/);
4265   __PACKAGE__->set_primary_key('trackid');
4266   __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
4267   1;
4268
4269   # In your application
4270   my $rs = $schema->resultset('Artist')->search(
4271     { 'track.title' => 'Teardrop' },
4272     {
4273       join     => { cd => 'track' },
4274       order_by => 'artist.name',
4275     }
4276   );
4277
4278 You need to use the relationship (not the table) name in  conditions,
4279 because they are aliased as such. The current table is aliased as "me", so
4280 you need to use me.column_name in order to avoid ambiguity. For example:
4281
4282   # Get CDs from 1984 with a 'Foo' track
4283   my $rs = $schema->resultset('CD')->search(
4284     {
4285       'me.year' => 1984,
4286       'tracks.name' => 'Foo'
4287     },
4288     { join => 'tracks' }
4289   );
4290
4291 If the same join is supplied twice, it will be aliased to <rel>_2 (and
4292 similarly for a third time). For e.g.
4293
4294   my $rs = $schema->resultset('Artist')->search({
4295     'cds.title'   => 'Down to Earth',
4296     'cds_2.title' => 'Popular',
4297   }, {
4298     join => [ qw/cds cds/ ],
4299   });
4300
4301 will return a set of all artists that have both a cd with title 'Down
4302 to Earth' and a cd with title 'Popular'.
4303
4304 If you want to fetch related objects from other tables as well, see L</prefetch>
4305 below.
4306
4307  NOTE: An internal join-chain pruner will discard certain joins while
4308  constructing the actual SQL query, as long as the joins in question do not
4309  affect the retrieved result. This for example includes 1:1 left joins
4310  that are not part of the restriction specification (WHERE/HAVING) nor are
4311  a part of the query selection.
4312
4313 For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
4314
4315 =head2 collapse
4316
4317 =over 4
4318
4319 =item Value: (0 | 1)
4320
4321 =back
4322
4323 When set to a true value, indicates that any rows fetched from joined has_many
4324 relationships are to be aggregated into the corresponding "parent" object. For
4325 example, the resultset:
4326
4327   my $rs = $schema->resultset('CD')->search({}, {
4328     '+columns' => [ qw/ tracks.title tracks.position / ],
4329     join => 'tracks',
4330     collapse => 1,
4331   });
4332
4333 While executing the following query:
4334
4335   SELECT me.*, tracks.title, tracks.position
4336     FROM cd me
4337     LEFT JOIN track tracks
4338       ON tracks.cdid = me.cdid
4339
4340 Will return only as many objects as there are rows in the CD source, even
4341 though the result of the query may span many rows. Each of these CD objects
4342 will in turn have multiple "Track" objects hidden behind the has_many
4343 generated accessor C<tracks>. Without C<< collapse => 1 >>, the return values
4344 of this resultset would be as many CD objects as there are tracks (a "Cartesian
4345 product"), with each CD object containing exactly one of all fetched Track data.
4346
4347 When a collapse is requested on a non-ordered resultset, an order by some
4348 unique part of the main source (the left-most table) is inserted automatically.
4349 This is done so that the resultset is allowed to be "lazy" - calling
4350 L<< $rs->next|/next >> will fetch only as many rows as it needs to build the next
4351 object with all of its related data.
4352
4353 If an L</order_by> is already declared, and orders the resultset in a way that
4354 makes collapsing as described above impossible (e.g. C<< ORDER BY
4355 has_many_rel.column >> or C<ORDER BY RANDOM()>), DBIC will automatically
4356 switch to "eager" mode and slurp the entire resultset before constructing the
4357 first object returned by L</next>.
4358
4359 Setting this attribute on a resultset that does not join any has_many
4360 relations is a no-op.
4361
4362 For a more in-depth discussion, see L</PREFETCHING>.
4363
4364 =head2 prefetch
4365
4366 =over 4
4367
4368 =item Value: ($rel_name | \@rel_names | \%rel_names)
4369
4370 =back
4371
4372 This attribute is a shorthand for specifying a L</join> spec, adding all
4373 columns from the joined related sources as L</+columns> and setting
4374 L</collapse> to a true value. It can be thought of as a rough B<superset>
4375 of the L</join> attribute.
4376
4377 For example, the following two queries are equivalent:
4378
4379   my $rs = $schema->resultset('Artist')->search({}, {
4380     prefetch => { cds => ['genre', 'tracks' ] },
4381   });
4382
4383 and
4384
4385   my $rs = $schema->resultset('Artist')->search({}, {
4386     join => { cds => ['genre', 'tracks' ] },
4387     collapse => 1,
4388     '+columns' => [
4389       (map
4390         { +{ "cds.$_" => "cds.$_" } }
4391         $schema->source('Artist')->related_source('cds')->columns
4392       ),
4393       (map
4394         { +{ "cds.genre.$_" => "genre.$_" } }
4395         $schema->source('Artist')->related_source('cds')->related_source('genre')->columns
4396       ),
4397       (map
4398         { +{ "cds.tracks.$_" => "tracks.$_" } }
4399         $schema->source('Artist')->related_source('cds')->related_source('tracks')->columns
4400       ),
4401     ],
4402   });
4403
4404 Both producing the following SQL:
4405
4406   SELECT  me.artistid, me.name, me.rank, me.charfield,
4407           cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track,
4408           genre.genreid, genre.name,
4409           tracks.trackid, tracks.cd, tracks.position, tracks.title, tracks.last_updated_on, tracks.last_updated_at
4410     FROM artist me
4411     LEFT JOIN cd cds
4412       ON cds.artist = me.artistid
4413     LEFT JOIN genre genre
4414       ON genre.genreid = cds.genreid
4415     LEFT JOIN track tracks
4416       ON tracks.cd = cds.cdid
4417   ORDER BY me.artistid
4418
4419 While L</prefetch> implies a L</join>, it is ok to mix the two together, as
4420 the arguments are properly merged and generally do the right thing. For
4421 example, you may want to do the following:
4422
4423   my $artists_and_cds_without_genre = $schema->resultset('Artist')->search(
4424     { 'genre.genreid' => undef },
4425     {
4426       join => { cds => 'genre' },
4427       prefetch => 'cds',
4428     }
4429   );
4430
4431 Which generates the following SQL:
4432
4433   SELECT  me.artistid, me.name, me.rank, me.charfield,
4434           cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track
4435     FROM artist me
4436     LEFT JOIN cd cds
4437       ON cds.artist = me.artistid
4438     LEFT JOIN genre genre
4439       ON genre.genreid = cds.genreid
4440   WHERE genre.genreid IS NULL
4441   ORDER BY me.artistid
4442
4443 For a more in-depth discussion, see L</PREFETCHING>.
4444
4445 =head2 alias
4446
4447 =over 4
4448
4449 =item Value: $source_alias
4450
4451 =back
4452
4453 Sets the source alias for the query.  Normally, this defaults to C<me>, but
4454 nested search queries (sub-SELECTs) might need specific aliases set to
4455 reference inner queries.  For example:
4456
4457    my $q = $rs
4458       ->related_resultset('CDs')
4459       ->related_resultset('Tracks')
4460       ->search({
4461          'track.id' => { -ident => 'none_search.id' },
4462       })
4463       ->as_query;
4464
4465    my $ids = $self->search({
4466       -not_exists => $q,
4467    }, {
4468       alias    => 'none_search',
4469       group_by => 'none_search.id',
4470    })->get_column('id')->as_query;
4471
4472    $self->search({ id => { -in => $ids } })
4473
4474 This attribute is directly tied to L</current_source_alias>.
4475
4476 =head2 page
4477
4478 =over 4
4479
4480 =item Value: $page
4481
4482 =back
4483
4484 Makes the resultset paged and specifies the page to retrieve. Effectively
4485 identical to creating a non-pages resultset and then calling ->page($page)
4486 on it.
4487
4488 If L</rows> attribute is not specified it defaults to 10 rows per page.
4489
4490 When you have a paged resultset, L</count> will only return the number
4491 of rows in the page. To get the total, use the L</pager> and call
4492 C<total_entries> on it.
4493
4494 =head2 rows
4495
4496 =over 4
4497
4498 =item Value: $rows
4499
4500 =back
4501
4502 Specifies the maximum number of rows for direct retrieval or the number of
4503 rows per page if the page attribute or method is used.
4504
4505 =head2 offset
4506
4507 =over 4
4508
4509 =item Value: $offset
4510
4511 =back
4512
4513 Specifies the (zero-based) row number for the  first row to be returned, or the
4514 of the first row of the first page if paging is used.
4515
4516 =head2 software_limit
4517
4518 =over 4
4519
4520 =item Value: (0 | 1)
4521
4522 =back
4523
4524 When combined with L</rows> and/or L</offset> the generated SQL will not
4525 include any limit dialect stanzas. Instead the entire result will be selected
4526 as if no limits were specified, and DBIC will perform the limit locally, by
4527 artificially advancing and finishing the resulting L</cursor>.
4528
4529 This is the recommended way of performing resultset limiting when no sane RDBMS
4530 implementation is available (e.g.
4531 L<Sybase ASE|DBIx::Class::Storage::DBI::Sybase::ASE> using the
4532 L<Generic Sub Query|DBIx::Class::SQLMaker::LimitDialects/GenericSubQ> hack)
4533
4534 =head2 group_by
4535
4536 =over 4
4537
4538 =item Value: \@columns
4539
4540 =back
4541
4542 A arrayref of columns to group by. Can include columns of joined tables.
4543
4544   group_by => [qw/ column1 column2 ... /]
4545
4546 =head2 having
4547
4548 =over 4
4549
4550 =item Value: $condition
4551
4552 =back
4553
4554 The HAVING operator specifies a B<secondary> condition applied to the set
4555 after the grouping calculations have been done. In other words it is a
4556 constraint just like L</where> (and accepting the same
4557 L<SQL::Abstract syntax|SQL::Abstract/WHERE CLAUSES>) applied to the data
4558 as it exists after GROUP BY has taken place. Specifying L</having> without
4559 L</group_by> is a logical mistake, and a fatal error on most RDBMS engines.
4560
4561 E.g.
4562
4563   having => { 'count_employee' => { '>=', 100 } }
4564
4565 or with an in-place function in which case literal SQL is required:
4566
4567   having => \[ 'count(employee) >= ?', 100 ]
4568
4569 =head2 distinct
4570
4571 =over 4
4572
4573 =item Value: (0 | 1)
4574
4575 =back
4576
4577 Set to 1 to automatically generate a L</group_by> clause based on the selection
4578 (including intelligent handling of L</order_by> contents). Note that the group
4579 criteria calculation takes place over the B<final> selection. This includes
4580 any L</+columns>, L</+select> or L</order_by> additions in subsequent
4581 L</search> calls, and standalone columns selected via
4582 L<DBIx::Class::ResultSetColumn> (L</get_column>). A notable exception are the
4583 extra selections specified via L</prefetch> - such selections are explicitly
4584 excluded from group criteria calculations.
4585
4586 If the final ResultSet also explicitly defines a L</group_by> attribute, this
4587 setting is ignored and an appropriate warning is issued.
4588
4589 =head2 where
4590
4591 =over 4
4592
4593 Adds to the WHERE clause.
4594
4595   # only return rows WHERE deleted IS NULL for all searches
4596   __PACKAGE__->resultset_attributes({ where => { deleted => undef } });
4597
4598 Can be overridden by passing C<< { where => undef } >> as an attribute
4599 to a resultset.
4600
4601 For more complicated where clauses see L<SQL::Abstract/WHERE CLAUSES>.
4602
4603 =back
4604
4605 =head2 cache
4606
4607 Set to 1 to cache search results. This prevents extra SQL queries if you
4608 revisit rows in your ResultSet:
4609
4610   my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
4611
4612   while( my $artist = $resultset->next ) {
4613     ... do stuff ...
4614   }
4615
4616   $rs->first; # without cache, this would issue a query
4617
4618 By default, searches are not cached.
4619
4620 For more examples of using these attributes, see
4621 L<DBIx::Class::Manual::Cookbook>.
4622
4623 =head2 for
4624
4625 =over 4
4626
4627 =item Value: ( 'update' | 'shared' | \$scalar )
4628
4629 =back
4630
4631 Set to 'update' for a SELECT ... FOR UPDATE or 'shared' for a SELECT
4632 ... FOR SHARED. If \$scalar is passed, this is taken directly and embedded in the
4633 query.
4634
4635 =head1 PREFETCHING
4636
4637 DBIx::Class supports arbitrary related data prefetching from multiple related
4638 sources. Any combination of relationship types and column sets are supported.
4639 If L<collapsing|/collapse> is requested, there is an additional requirement of
4640 selecting enough data to make every individual object uniquely identifiable.
4641
4642 Here are some more involved examples, based on the following relationship map:
4643
4644   # Assuming:
4645   My::Schema::CD->belongs_to( artist      => 'My::Schema::Artist'     );
4646   My::Schema::CD->might_have( liner_note  => 'My::Schema::LinerNotes' );
4647   My::Schema::CD->has_many(   tracks      => 'My::Schema::Track'      );
4648
4649   My::Schema::Artist->belongs_to( record_label => 'My::Schema::RecordLabel' );
4650
4651   My::Schema::Track->has_many( guests => 'My::Schema::Guest' );
4652
4653
4654
4655   my $rs = $schema->resultset('Tag')->search(
4656     undef,
4657     {
4658       prefetch => {
4659         cd => 'artist'
4660       }
4661     }
4662   );
4663
4664 The initial search results in SQL like the following:
4665
4666   SELECT tag.*, cd.*, artist.* FROM tag
4667   JOIN cd ON tag.cd = cd.cdid
4668   JOIN artist ON cd.artist = artist.artistid
4669
4670 L<DBIx::Class> has no need to go back to the database when we access the
4671 C<cd> or C<artist> relationships, which saves us two SQL statements in this
4672 case.
4673
4674 Simple prefetches will be joined automatically, so there is no need
4675 for a C<join> attribute in the above search.
4676
4677 The L</prefetch> attribute can be used with any of the relationship types
4678 and multiple prefetches can be specified together. Below is a more complex
4679 example that prefetches a CD's artist, its liner notes (if present),
4680 the cover image, the tracks on that CD, and the guests on those
4681 tracks.
4682
4683   my $rs = $schema->resultset('CD')->search(
4684     undef,
4685     {
4686       prefetch => [
4687         { artist => 'record_label'},  # belongs_to => belongs_to
4688         'liner_note',                 # might_have
4689         'cover_image',                # has_one
4690         { tracks => 'guests' },       # has_many => has_many
4691       ]
4692     }
4693   );
4694
4695 This will produce SQL like the following:
4696
4697   SELECT cd.*, artist.*, record_label.*, liner_note.*, cover_image.*,
4698          tracks.*, guests.*
4699     FROM cd me
4700     JOIN artist artist
4701       ON artist.artistid = me.artistid
4702     JOIN record_label record_label
4703       ON record_label.labelid = artist.labelid
4704     LEFT JOIN track tracks
4705       ON tracks.cdid = me.cdid
4706     LEFT JOIN guest guests
4707       ON guests.trackid = track.trackid
4708     LEFT JOIN liner_notes liner_note
4709       ON liner_note.cdid = me.cdid
4710     JOIN cd_artwork cover_image
4711       ON cover_image.cdid = me.cdid
4712   ORDER BY tracks.cd
4713
4714 Now the C<artist>, C<record_label>, C<liner_note>, C<cover_image>,
4715 C<tracks>, and C<guests> of the CD will all be available through the
4716 relationship accessors without the need for additional queries to the
4717 database.
4718
4719 =head3 CAVEATS
4720
4721 Prefetch does a lot of deep magic. As such, it may not behave exactly
4722 as you might expect.
4723
4724 =over 4
4725
4726 =item *
4727
4728 Prefetch uses the L</cache> to populate the prefetched relationships. This
4729 may or may not be what you want.
4730
4731 =item *
4732
4733 If you specify a condition on a prefetched relationship, ONLY those
4734 rows that match the prefetched condition will be fetched into that relationship.
4735 This means that adding prefetch to a search() B<may alter> what is returned by
4736 traversing a relationship. So, if you have C<< Artist->has_many(CDs) >> and you do
4737
4738   my $artist_rs = $schema->resultset('Artist')->search({
4739       'cds.year' => 2008,
4740   }, {
4741       join => 'cds',
4742   });
4743
4744   my $count = $artist_rs->first->cds->count;
4745
4746   my $artist_rs_prefetch = $artist_rs->search( {}, { prefetch => 'cds' } );
4747
4748   my $prefetch_count = $artist_rs_prefetch->first->cds->count;
4749
4750   cmp_ok( $count, '==', $prefetch_count, "Counts should be the same" );
4751
4752 That cmp_ok() may or may not pass depending on the datasets involved. In other
4753 words the C<WHERE> condition would apply to the entire dataset, just like
4754 it would in regular SQL. If you want to add a condition only to the "right side"
4755 of a C<LEFT JOIN> - consider declaring and using a L<relationship with a custom
4756 condition|DBIx::Class::Relationship::Base/condition>
4757
4758 =back
4759
4760 =head1 DBIC BIND VALUES
4761
4762 Because DBIC may need more information to bind values than just the column name
4763 and value itself, it uses a special format for both passing and receiving bind
4764 values.  Each bind value should be composed of an arrayref of
4765 C<< [ \%args => $val ] >>.  The format of C<< \%args >> is currently:
4766
4767 =over 4
4768
4769 =item dbd_attrs
4770
4771 If present (in any form), this is what is being passed directly to bind_param.
4772 Note that different DBD's expect different bind args.  (e.g. DBD::SQLite takes
4773 a single numerical type, while DBD::Pg takes a hashref if bind options.)
4774
4775 If this is specified, all other bind options described below are ignored.
4776
4777 =item sqlt_datatype
4778
4779 If present, this is used to infer the actual bind attribute by passing to
4780 C<< $resolved_storage->bind_attribute_by_data_type() >>.  Defaults to the
4781 "data_type" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>.
4782
4783 Note that the data type is somewhat freeform (hence the sqlt_ prefix);
4784 currently drivers are expected to "Do the Right Thing" when given a common
4785 datatype name.  (Not ideal, but that's what we got at this point.)
4786
4787 =item sqlt_size
4788
4789 Currently used to correctly allocate buffers for bind_param_inout().
4790 Defaults to "size" from the L<add_columns column info|DBIx::Class::ResultSource/add_columns>,
4791 or to a sensible value based on the "data_type".
4792
4793 =item dbic_colname
4794
4795 Used to fill in missing sqlt_datatype and sqlt_size attributes (if they are
4796 explicitly specified they are never overridden).  Also used by some weird DBDs,
4797 where the column name should be available at bind_param time (e.g. Oracle).
4798
4799 =back
4800
4801 For backwards compatibility and convenience, the following shortcuts are
4802 supported:
4803
4804   [ $name => $val ] === [ { dbic_colname => $name }, $val ]
4805   [ \$dt  => $val ] === [ { sqlt_datatype => $dt }, $val ]
4806   [ undef,   $val ] === [ {}, $val ]
4807   $val              === [ {}, $val ]
4808
4809 =head1 FURTHER QUESTIONS?
4810
4811 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
4812
4813 =head1 COPYRIGHT AND LICENSE
4814
4815 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
4816 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
4817 redistribute it and/or modify it under the same terms as the
4818 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
4819
4820 =cut