1 package DBIx::Class::ResultSet;
9 use Carp::Clan qw/^DBIx::Class/;
13 use Scalar::Util qw/weaken/;
15 use DBIx::Class::ResultSetColumn;
16 use base qw/DBIx::Class/;
17 __PACKAGE__->load_components(qw/AccessorGroup/);
18 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
22 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
26 my $rs = $schema->resultset('User')->search(registered => 1);
27 my @rows = $schema->resultset('CD')->search(year => 2005);
31 The resultset is also known as an iterator. It is responsible for handling
32 queries that may return an arbitrary number of rows, e.g. via L</search>
33 or a C<has_many> relationship.
35 In the examples below, the following table classes are used:
37 package MyApp::Schema::Artist;
38 use base qw/DBIx::Class/;
39 __PACKAGE__->load_components(qw/Core/);
40 __PACKAGE__->table('artist');
41 __PACKAGE__->add_columns(qw/artistid name/);
42 __PACKAGE__->set_primary_key('artistid');
43 __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
46 package MyApp::Schema::CD;
47 use base qw/DBIx::Class/;
48 __PACKAGE__->load_components(qw/Core/);
49 __PACKAGE__->table('cd');
50 __PACKAGE__->add_columns(qw/cdid artist title year/);
51 __PACKAGE__->set_primary_key('cdid');
52 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
61 =item Arguments: $source, \%$attrs
63 =item Return Value: $rs
67 The resultset constructor. Takes a source object (usually a
68 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
69 L</ATTRIBUTES> below). Does not perform any queries -- these are
70 executed as needed by the other methods.
72 Generally you won't need to construct a resultset manually. You'll
73 automatically get one from e.g. a L</search> called in scalar context:
75 my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
77 IMPORTANT: If called on an object, proxies to new_result instead so
79 my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
81 will return a CD object, not a ResultSet.
87 return $class->new_result(@_) if ref $class;
89 my ($source, $attrs) = @_;
93 $attrs->{rows} ||= 10;
94 $attrs->{offset} ||= 0;
95 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
98 $attrs->{alias} ||= 'me';
101 result_source => $source,
102 result_class => $attrs->{result_class} || $source->result_class,
103 cond => $attrs->{where},
104 # from => $attrs->{from},
105 # collapse => $collapse,
107 page => delete $attrs->{page},
117 =item Arguments: $cond, \%attrs?
119 =item Return Value: $resultset (scalar context), @row_objs (list context)
123 my @cds = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
124 my $new_rs = $cd_rs->search({ year => 2005 });
126 my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
127 # year = 2005 OR year = 2004
129 If you need to pass in additional attributes but no additional condition,
130 call it as C<search(undef, \%attrs)>.
132 # "SELECT name, artistid FROM $artist_table"
133 my @all_artists = $schema->resultset('Artist')->search(undef, {
134 columns => [qw/name artistid/],
141 my $rs = $self->search_rs( @_ );
142 return (wantarray ? $rs->all : $rs);
149 =item Arguments: $cond, \%attrs?
151 =item Return Value: $resultset
155 This method does the same exact thing as search() except it will
156 always return a resultset, even in list context.
164 $attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
165 my $our_attrs = ($attrs->{_parent_attrs})
166 ? { %{$attrs->{_parent_attrs}} }
167 : { %{$self->{attrs}} };
168 delete($attrs->{_parent_attrs}) if(exists $attrs->{_parent_attrs});
169 my $having = delete $our_attrs->{having};
171 # XXX should only maintain _live_join_stack and generate _live_join_h from that
172 if ($attrs->{_live_join_stack}) {
173 my $live_join = $attrs->{_live_join_stack};
174 foreach (reverse @{$live_join}) {
175 $attrs->{_live_join_h} = (defined $attrs->{_live_join_h}) ? { $_ => $attrs->{_live_join_h} } : $_;
179 # merge new attrs into inherited
180 foreach my $key (qw/join prefetch/) {
181 next unless (exists $attrs->{$key});
182 if ($attrs->{_live_join_stack} || $our_attrs->{_live_join_stack}) {
183 my $live_join = $attrs->{_live_join_stack} ||
184 $our_attrs->{_live_join_stack};
185 foreach (reverse @{$live_join}) {
186 $attrs->{$key} = { $_ => $attrs->{$key} };
190 if (exists $our_attrs->{$key}) {
191 $our_attrs->{$key} = $self->_merge_attr($our_attrs->{$key}, $attrs->{$key});
193 $our_attrs->{$key} = $attrs->{$key};
195 delete $attrs->{$key};
198 $our_attrs->{join} = $self->_merge_attr(
199 $our_attrs->{join}, $attrs->{_live_join_h}
200 ) if ($attrs->{_live_join_h});
202 if (defined $our_attrs->{prefetch}) {
203 $our_attrs->{join} = $self->_merge_attr(
204 $our_attrs->{join}, $our_attrs->{prefetch}
208 my $new_attrs = { %{$our_attrs}, %{$attrs} };
211 (@_ == 1 || ref $_[0] eq "HASH")
215 ? $self->throw_exception("Odd number of arguments to search")
222 if (defined $where) {
223 $new_attrs->{where} = (
224 defined $new_attrs->{where}
227 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
228 } $where, $new_attrs->{where}
234 if (defined $having) {
235 $new_attrs->{having} = (
236 defined $new_attrs->{having}
239 ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_
240 } $having, $new_attrs->{having}
246 my $rs = (ref $self)->new($self->result_source, $new_attrs);
247 $rs->{_parent_rs} = $self->{_parent_rs} if ($self->{_parent_rs});
249 unless (@_) { # no search, effectively just a clone
250 my $rows = $self->get_cache;
252 $rs->set_cache($rows);
258 =head2 search_literal
262 =item Arguments: $sql_fragment, @bind_values
264 =item Return Value: $resultset (scalar context), @row_objs (list context)
268 my @cds = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
269 my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
271 Pass a literal chunk of SQL to be added to the conditional part of the
277 my ($self, $cond, @vals) = @_;
278 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
279 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
280 return $self->search(\$cond, $attrs);
287 =item Arguments: @values | \%cols, \%attrs?
289 =item Return Value: $row_object
293 Finds a row based on its primary key or unique constraint. For example, to find
294 a row by its primary key:
296 my $cd = $schema->resultset('CD')->find(5);
298 You can also find a row by a specific unique constraint using the C<key>
299 attribute. For example:
301 my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', {
302 key => 'cd_artist_title'
305 Additionally, you can specify the columns explicitly by name:
307 my $cd = $schema->resultset('CD')->find(
309 artist => 'Massive Attack',
310 title => 'Mezzanine',
312 { key => 'cd_artist_title' }
315 If the C<key> is specified as C<primary>, it searches only on the primary key.
317 If no C<key> is specified, it searches on all unique constraints defined on the
318 source, including the primary key.
320 See also L</find_or_create> and L</update_or_create>. For information on how to
321 declare unique constraints, see
322 L<DBIx::Class::ResultSource/add_unique_constraint>.
328 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
330 # Default to the primary key, but allow a specific key
331 my @cols = exists $attrs->{key}
332 ? $self->result_source->unique_constraint_columns($attrs->{key})
333 : $self->result_source->primary_columns;
334 $self->throw_exception(
335 "Can't find unless a primary key or unique constraint is defined"
338 # Parse out a hashref from input
340 if (ref $_[0] eq 'HASH') {
341 $input_query = { %{$_[0]} };
343 elsif (@_ == @cols) {
345 @{$input_query}{@cols} = @_;
348 # Compatibility: Allow e.g. find(id => $value)
349 carp "Find by key => value deprecated; please use a hashref instead";
353 my @unique_queries = $self->_unique_queries($input_query, $attrs);
355 # Handle cases where the ResultSet defines the query, or where the user is
357 my $query = @unique_queries ? \@unique_queries : $input_query;
361 my $rs = $self->search($query, $attrs);
363 return keys %{$rs->{_attrs}->{collapse}} ? $rs->next : $rs->single;
367 return (keys %{$self->{_attrs}->{collapse}})
368 ? $self->search($query)->next
369 : $self->single($query);
375 # Build a list of queries which satisfy unique constraints.
377 sub _unique_queries {
378 my ($self, $query, $attrs) = @_;
380 my @constraint_names = exists $attrs->{key}
382 : $self->result_source->unique_constraint_names;
385 foreach my $name (@constraint_names) {
386 my @unique_cols = $self->result_source->unique_constraint_columns($name);
387 my $unique_query = $self->_build_unique_query($query, \@unique_cols);
389 next unless scalar keys %$unique_query;
391 # Add the ResultSet's alias
392 foreach my $key (grep { ! m/\./ } keys %$unique_query) {
393 my $alias = ($self->{attrs}->{_live_join})
394 ? $self->{attrs}->{_live_join}
395 : $self->{attrs}->{alias};
396 $unique_query->{"$alias.$key"} = delete $unique_query->{$key};
399 push @unique_queries, $unique_query;
402 return @unique_queries;
405 # _build_unique_query
407 # Constrain the specified query hash based on the specified column names.
409 sub _build_unique_query {
410 my ($self, $query, $unique_cols) = @_;
413 map { $_ => $query->{$_} }
414 grep { exists $query->{$_} }
417 return \%unique_query;
420 =head2 search_related
424 =item Arguments: $rel, $cond, \%attrs?
426 =item Return Value: $new_resultset
430 $new_rs = $cd_rs->search_related('artist', {
434 Searches the specified relationship, optionally specifying a condition and
435 attributes for matching records. See L</ATTRIBUTES> for more information.
440 return shift->related_resultset(shift)->search(@_);
447 =item Arguments: none
449 =item Return Value: $cursor
453 Returns a storage-driven cursor to the given resultset. See
454 L<DBIx::Class::Cursor> for more information.
462 my $attrs = { %{$self->{_attrs}} };
463 return $self->{cursor}
464 ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
465 $attrs->{where},$attrs);
472 =item Arguments: $cond?
474 =item Return Value: $row_object?
478 my $cd = $schema->resultset('CD')->single({ year => 2001 });
480 Inflates the first result without creating a cursor if the resultset has
481 any records in it; if not returns nothing. Used by L</find> as an optimisation.
483 Can optionally take an additional condition *only* - this is a fast-code-path
484 method; if you need to add extra joins or similar call ->search and then
485 ->single without a condition on the $rs returned from that.
490 my ($self, $where) = @_;
492 my $attrs = { %{$self->{_attrs}} };
494 if (defined $attrs->{where}) {
497 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
498 $where, delete $attrs->{where} ]
501 $attrs->{where} = $where;
505 unless ($self->_is_unique_query($attrs->{where})) {
506 carp "Query not guaranteed to return a single row"
507 . "; please declare your unique constraints or use search instead";
510 my @data = $self->result_source->storage->select_single(
511 $attrs->{from}, $attrs->{select},
512 $attrs->{where},$attrs
515 return (@data ? $self->_construct_object(@data) : ());
520 # Try to determine if the specified query is guaranteed to be unique, based on
521 # the declared unique constraints.
523 sub _is_unique_query {
524 my ($self, $query) = @_;
526 my $collapsed = $self->_collapse_query($query);
527 my $alias = ($self->{attrs}->{_live_join})
528 ? $self->{attrs}->{_live_join}
529 : $self->{attrs}->{alias};
531 foreach my $name ($self->result_source->unique_constraint_names) {
532 my @unique_cols = map {
534 } $self->result_source->unique_constraint_columns($name);
536 # Count the values for each unique column
537 my %seen = map { $_ => 0 } @unique_cols;
539 foreach my $key (keys %$collapsed) {
541 $aliased = "$alias.$key" unless $key =~ /\./;
543 next unless exists $seen{$aliased}; # Additional constraints are okay
544 $seen{$aliased} = scalar @{ $collapsed->{$key} };
547 # If we get 0 or more than 1 value for a column, it's not necessarily unique
548 return 1 unless grep { $_ != 1 } values %seen;
556 # Recursively collapse the query, accumulating values for each column.
558 sub _collapse_query {
559 my ($self, $query, $collapsed) = @_;
563 if (ref $query eq 'ARRAY') {
564 foreach my $subquery (@$query) {
565 next unless ref $subquery; # -or
566 # warn "ARRAY: " . Dumper $subquery;
567 $collapsed = $self->_collapse_query($subquery, $collapsed);
570 elsif (ref $query eq 'HASH') {
571 if (keys %$query and (keys %$query)[0] eq '-and') {
572 foreach my $subquery (@{$query->{-and}}) {
573 # warn "HASH: " . Dumper $subquery;
574 $collapsed = $self->_collapse_query($subquery, $collapsed);
578 # warn "LEAF: " . Dumper $query;
579 foreach my $key (keys %$query) {
580 push @{$collapsed->{$key}}, $query->{$key};
592 =item Arguments: $cond?
594 =item Return Value: $resultsetcolumn
598 my $max_length = $rs->get_column('length')->max;
600 Returns a ResultSetColumn instance for $column based on $self
605 my ($self, $column) = @_;
606 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
614 =item Arguments: $cond, \%attrs?
616 =item Return Value: $resultset (scalar context), @row_objs (list context)
620 # WHERE title LIKE '%blue%'
621 $cd_rs = $rs->search_like({ title => '%blue%'});
623 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
624 that this is simply a convenience method. You most likely want to use
625 L</search> with specific operators.
627 For more information, see L<DBIx::Class::Manual::Cookbook>.
633 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
634 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
635 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
636 return $class->search($query, { %$attrs });
643 =item Arguments: $first, $last
645 =item Return Value: $resultset (scalar context), @row_objs (list context)
649 Returns a resultset or object list representing a subset of elements from the
650 resultset slice is called on. Indexes are from 0, i.e., to get the first
653 my ($one, $two, $three) = $rs->slice(0, 2);
658 my ($self, $min, $max) = @_;
659 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
660 $attrs->{offset} = $self->{attrs}{offset} || 0;
661 $attrs->{offset} += $min;
662 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
663 return $self->search(undef(), $attrs);
664 #my $slice = (ref $self)->new($self->result_source, $attrs);
665 #return (wantarray ? $slice->all : $slice);
672 =item Arguments: none
674 =item Return Value: $result?
678 Returns the next element in the resultset (C<undef> is there is none).
680 Can be used to efficiently iterate over records in the resultset:
682 my $rs = $schema->resultset('CD')->search;
683 while (my $cd = $rs->next) {
687 Note that you need to store the resultset object, and call C<next> on it.
688 Calling C<< resultset('Table')->next >> repeatedly will always return the
689 first record from the resultset.
695 if (my $cache = $self->get_cache) {
696 $self->{all_cache_position} ||= 0;
697 return $cache->[$self->{all_cache_position}++];
699 if ($self->{attrs}{cache}) {
700 $self->{all_cache_position} = 1;
701 return ($self->all)[0];
704 exists $self->{stashed_row}
705 ? @{delete $self->{stashed_row}}
706 : $self->cursor->next
708 return unless (@row);
709 return $self->_construct_object(@row);
715 return if(exists $self->{_attrs}); #return if _resolve has already been called
717 my $attrs = $self->{attrs};
718 my $source = ($self->{_parent_rs})
719 ? $self->{_parent_rs}
720 : $self->{result_source};
722 # XXX - lose storable dclone
723 my $record_filter = delete $attrs->{record_filter}
724 if (defined $attrs->{record_filter});
725 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
726 $attrs->{record_filter} = $record_filter if ($record_filter);
727 $self->{attrs}->{record_filter} = $record_filter if ($record_filter);
729 my $alias = $attrs->{alias};
731 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
732 delete $attrs->{as} if $attrs->{columns};
733 $attrs->{columns} ||= [ $self->{result_source}->columns ]
734 unless $attrs->{select};
735 my $select_alias = ($self->{_parent_rs})
736 ? $self->{attrs}->{_live_join}
739 map { m/\./ ? $_ : "${select_alias}.$_" } @{delete $attrs->{columns}}
740 ] if $attrs->{columns};
742 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
744 if (my $include = delete $attrs->{include_columns}) {
745 push(@{$attrs->{select}}, @$include);
746 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
749 $attrs->{from} ||= [ { $alias => $source->from } ];
750 $attrs->{seen_join} ||= {};
752 if (my $join = delete $attrs->{join}) {
753 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
754 if (ref $j eq 'HASH') {
755 $seen{$_} = 1 foreach keys %$j;
760 push(@{$attrs->{from}},
761 $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join})
764 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
765 $attrs->{order_by} = [ $attrs->{order_by} ] if
766 $attrs->{order_by} and !ref($attrs->{order_by});
767 $attrs->{order_by} ||= [];
769 if(my $seladds = delete($attrs->{'+select'})) {
770 my @seladds = (ref($seladds) eq 'ARRAY' ? @$seladds : ($seladds));
772 @{ $attrs->{select} },
773 map { (m/\./ || ref($_)) ? $_ : "${alias}.$_" } $seladds
776 if(my $asadds = delete($attrs->{'+as'})) {
777 my @asadds = (ref($asadds) eq 'ARRAY' ? @$asadds : ($asadds));
778 $attrs->{as} = [ @{ $attrs->{as} }, @asadds ];
780 my $collapse = $attrs->{collapse} || {};
781 if (my $prefetch = delete $attrs->{prefetch}) {
783 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
784 if ( ref $p eq 'HASH' ) {
785 foreach my $key (keys %$p) {
786 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
790 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
793 # bring joins back to level of current class
794 $p = $self->_reduce_joins($p, $attrs) if ($attrs->{_live_join_stack});
796 my @prefetch = $self->result_source->resolve_prefetch(
797 $p, $attrs->{alias}, {}, \@pre_order, $collapse
799 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
800 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
803 push(@{$attrs->{order_by}}, @pre_order);
805 $attrs->{collapse} = $collapse;
806 $self->{_attrs} = $attrs;
810 my ($self, $a, $b) = @_;
813 if (ref $b eq 'HASH' && ref $a eq 'HASH') {
814 foreach my $key (keys %{$b}) {
815 if (exists $a->{$key}) {
816 $a->{$key} = $self->_merge_attr($a->{$key}, $b->{$key});
818 $a->{$key} = $b->{$key};
823 $a = [$a] unless (ref $a eq 'ARRAY');
824 $b = [$b] unless (ref $b eq 'ARRAY');
829 foreach my $element (@{$_}) {
830 if (ref $element eq 'HASH') {
831 $hash = $self->_merge_attr($hash, $element);
832 } elsif (ref $element eq 'ARRAY') {
833 $array = [@{$array}, @{$element}];
836 $self->_merge_array($array, $element);
838 push(@{$array}, $element);
844 my $final_array = [];
845 foreach my $element (@{$array}) {
846 push(@{$final_array}, $element) unless (exists $hash->{$element});
848 $array = $final_array;
850 if ((keys %{$hash}) && (scalar(@{$array} > 0))) {
851 return [$hash, @{$array}];
853 return (keys %{$hash}) ? $hash : $array;
859 my ($self, $a, $b) = @_;
861 $b = [$b] unless (ref $b eq 'ARRAY');
862 # add elements from @{$b} to @{$a} which aren't already in @{$a}
863 foreach my $b_element (@{$b}) {
864 push(@{$a}, $b_element) unless grep {$b_element eq $_} @{$a};
868 # bring the joins (which are from the original class) to the level
869 # of the current class so that we can resolve them properly
871 my ($self, $p, $attrs) = @_;
874 foreach (@{$attrs->{_live_join_stack}}) {
875 if (ref $p eq 'HASH') {
876 if (exists $p->{$_}) {
881 } elsif (ref $p eq 'ARRAY') {
882 foreach my $pe (@{$p}) {
886 if ((ref $pe eq 'HASH') && (exists $pe->{$_})) {
899 sub _construct_object {
900 my ($self, @row) = @_;
901 my @as = @{ $self->{_attrs}{as} };
903 my $info = $self->_collapse_result(\@as, \@row);
904 my $new = $self->result_class->inflate_result($self->result_source, @$info);
905 $new = $self->{_attrs}{record_filter}->($new)
906 if exists $self->{_attrs}{record_filter};
910 sub _collapse_result {
911 my ($self, $as, $row, $prefix) = @_;
913 my $live_join = $self->{attrs}->{_live_join} ||="";
917 foreach my $this_as (@$as) {
918 my $val = shift @copy;
919 if (defined $prefix) {
920 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
922 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
923 $const{$1||''}{$2} = $val;
926 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
927 $const{$1||''}{$2} = $val;
931 my $info = [ {}, {} ];
932 foreach my $key (keys %const) {
933 if (length $key && $key ne $live_join) {
935 my @parts = split(/\./, $key);
936 foreach my $p (@parts) {
937 $target = $target->[1]->{$p} ||= [];
939 $target->[0] = $const{$key};
941 $info->[0] = $const{$key};
946 if (defined $prefix) {
948 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
949 } keys %{$self->{_attrs}->{collapse}}
951 @collapse = keys %{$self->{_attrs}->{collapse}};
955 my ($c) = sort { length $a <=> length $b } @collapse;
957 foreach my $p (split(/\./, $c)) {
958 $target = $target->[1]->{$p} ||= [];
960 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
961 my @co_key = @{$self->{_attrs}->{collapse}{$c_prefix}};
962 my $tree = $self->_collapse_result($as, $row, $c_prefix);
963 my %co_check = map { ($_, $tree->[0]->{$_}); } @co_key;
969 !defined($tree->[0]->{$_}) || $co_check{$_} ne $tree->[0]->{$_}
974 last unless (@raw = $self->cursor->next);
975 $row = $self->{stashed_row} = \@raw;
976 $tree = $self->_collapse_result($as, $row, $c_prefix);
978 @$target = (@final ? @final : [ {}, {} ]);
979 # single empty result to indicate an empty prefetched has_many
982 #print "final info: " . Dumper($info);
990 =item Arguments: $result_source?
992 =item Return Value: $result_source
996 An accessor for the primary ResultSource object from which this ResultSet
1006 =item Arguments: $cond, \%attrs??
1008 =item Return Value: $count
1012 Performs an SQL C<COUNT> with the same query as the resultset was built
1013 with to find the number of elements. If passed arguments, does a search
1014 on the resultset and counts the results of that.
1016 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
1017 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
1018 not support C<DISTINCT> with multiple columns. If you are using such a
1019 database, you should only use columns from the main table in your C<group_by>
1026 return $self->search(@_)->count if @_ and defined $_[0];
1027 return scalar @{ $self->get_cache } if $self->get_cache;
1028 my $count = $self->_count;
1029 return 0 unless $count;
1031 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
1032 $count = $self->{attrs}{rows} if
1033 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
1037 sub _count { # Separated out so pager can get the full count
1039 my $select = { count => '*' };
1042 my $attrs = { %{ $self->{_attrs} } };
1043 if (my $group_by = delete $attrs->{group_by}) {
1044 delete $attrs->{having};
1045 my @distinct = (ref $group_by ? @$group_by : ($group_by));
1046 # todo: try CONCAT for multi-column pk
1047 my @pk = $self->result_source->primary_columns;
1049 foreach my $column (@distinct) {
1050 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
1051 @distinct = ($column);
1057 $select = { count => { distinct => \@distinct } };
1060 $attrs->{select} = $select;
1061 $attrs->{as} = [qw/count/];
1063 # offset, order by and page are not needed to count. record_filter is cdbi
1064 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
1065 my $tmp_rs = (ref $self)->new($self->result_source, $attrs);
1066 $tmp_rs->{_parent_rs} = $self->{_parent_rs} if ($self->{_parent_rs});
1067 #XXX - hack to pass through parent of related resultsets
1069 my ($count) = $tmp_rs->cursor->next;
1073 =head2 count_literal
1077 =item Arguments: $sql_fragment, @bind_values
1079 =item Return Value: $count
1083 Counts the results in a literal query. Equivalent to calling L</search_literal>
1084 with the passed arguments, then L</count>.
1088 sub count_literal { shift->search_literal(@_)->count; }
1094 =item Arguments: none
1096 =item Return Value: @objects
1100 Returns all elements in the resultset. Called implicitly if the resultset
1101 is returned in list context.
1107 return @{ $self->get_cache } if $self->get_cache;
1111 # TODO: don't call resolve here
1113 if (keys %{$self->{_attrs}->{collapse}}) {
1114 # if ($self->{attrs}->{prefetch}) {
1115 # Using $self->cursor->all is really just an optimisation.
1116 # If we're collapsing has_many prefetches it probably makes
1117 # very little difference, and this is cleaner than hacking
1118 # _construct_object to survive the approach
1119 my @row = $self->cursor->next;
1121 push(@obj, $self->_construct_object(@row));
1122 @row = (exists $self->{stashed_row}
1123 ? @{delete $self->{stashed_row}}
1124 : $self->cursor->next);
1127 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
1130 $self->set_cache(\@obj) if $self->{attrs}{cache};
1138 =item Arguments: none
1140 =item Return Value: $self
1144 Resets the resultset's cursor, so you can iterate through the elements again.
1150 delete $self->{_attrs} if (exists $self->{_attrs});
1152 $self->{all_cache_position} = 0;
1153 $self->cursor->reset;
1161 =item Arguments: none
1163 =item Return Value: $object?
1167 Resets the resultset and returns an object for the first result (if the
1168 resultset returns anything).
1173 return $_[0]->reset->next;
1176 # _cond_for_update_delete
1178 # update/delete require the condition to be modified to handle
1179 # the differing SQL syntax available. This transforms the $self->{cond}
1180 # appropriately, returning the new condition.
1182 sub _cond_for_update_delete {
1186 if (!ref($self->{cond})) {
1187 # No-op. No condition, we're updating/deleting everything
1189 elsif (ref $self->{cond} eq 'ARRAY') {
1193 foreach my $key (keys %{$_}) {
1195 $hash{$1} = $_->{$key};
1201 elsif (ref $self->{cond} eq 'HASH') {
1202 if ((keys %{$self->{cond}})[0] eq '-and') {
1205 my @cond = @{$self->{cond}{-and}};
1206 for (my $i = 0; $i <= @cond - 1; $i++) {
1207 my $entry = $cond[$i];
1210 if (ref $entry eq 'HASH') {
1211 foreach my $key (keys %{$entry}) {
1213 $hash{$1} = $entry->{$key};
1217 $entry =~ /([^.]+)$/;
1218 $hash{$1} = $cond[++$i];
1221 push @{$cond->{-and}}, \%hash;
1225 foreach my $key (keys %{$self->{cond}}) {
1227 $cond->{$1} = $self->{cond}{$key};
1232 $self->throw_exception(
1233 "Can't update/delete on resultset with condition unless hash or array"
1245 =item Arguments: \%values
1247 =item Return Value: $storage_rv
1251 Sets the specified columns in the resultset to the supplied values in a
1252 single query. Return value will be true if the update succeeded or false
1253 if no records were updated; exact type of success value is storage-dependent.
1258 my ($self, $values) = @_;
1259 $self->throw_exception("Values for update must be a hash")
1260 unless ref $values eq 'HASH';
1262 my $cond = $self->_cond_for_update_delete;
1264 return $self->result_source->storage->update(
1265 $self->result_source->from, $values, $cond
1273 =item Arguments: \%values
1275 =item Return Value: 1
1279 Fetches all objects and updates them one at a time. Note that C<update_all>
1280 will run DBIC cascade triggers, while L</update> will not.
1285 my ($self, $values) = @_;
1286 $self->throw_exception("Values for update must be a hash")
1287 unless ref $values eq 'HASH';
1288 foreach my $obj ($self->all) {
1289 $obj->set_columns($values)->update;
1298 =item Arguments: none
1300 =item Return Value: 1
1304 Deletes the contents of the resultset from its result source. Note that this
1305 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1314 my $cond = $self->_cond_for_update_delete;
1316 $self->result_source->storage->delete($self->result_source->from, $cond);
1324 =item Arguments: none
1326 =item Return Value: 1
1330 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1331 will run DBIC cascade triggers, while L</delete> will not.
1337 $_->delete for $self->all;
1345 =item Arguments: none
1347 =item Return Value: $pager
1351 Return Value a L<Data::Page> object for the current resultset. Only makes
1352 sense for queries with a C<page> attribute.
1358 my $attrs = $self->{attrs};
1359 $self->throw_exception("Can't create pager for non-paged rs")
1360 unless $self->{page};
1361 $attrs->{rows} ||= 10;
1362 return $self->{pager} ||= Data::Page->new(
1363 $self->_count, $attrs->{rows}, $self->{page});
1370 =item Arguments: $page_number
1372 =item Return Value: $rs
1376 Returns a resultset for the $page_number page of the resultset on which page
1377 is called, where each page contains a number of rows equal to the 'rows'
1378 attribute set on the resultset (10 by default).
1383 my ($self, $page) = @_;
1384 my $attrs = { %{$self->{attrs}} };
1385 $attrs->{page} = $page;
1386 return (ref $self)->new($self->result_source, $attrs);
1393 =item Arguments: \%vals
1395 =item Return Value: $object
1399 Creates an object in the resultset's result class and returns it.
1404 my ($self, $values) = @_;
1405 $self->throw_exception( "new_result needs a hash" )
1406 unless (ref $values eq 'HASH');
1407 $self->throw_exception(
1408 "Can't abstract implicit construct, condition not a hash"
1409 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1411 my $alias = $self->{attrs}{alias};
1412 foreach my $key (keys %{$self->{cond}||{}}) {
1413 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1415 my $obj = $self->result_class->new(\%new);
1416 $obj->result_source($self->result_source) if $obj->can('result_source');
1424 =item Arguments: \%vals, \%attrs?
1426 =item Return Value: $object
1430 Find an existing record from this resultset. If none exists, instantiate a new
1431 result object and return it. The object will not be saved into your storage
1432 until you call L<DBIx::Class::Row/insert> on it.
1434 If you want objects to be saved immediately, use L</find_or_create> instead.
1440 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1441 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1442 my $exists = $self->find($hash, $attrs);
1443 return defined $exists ? $exists : $self->new_result($hash);
1450 =item Arguments: \%vals
1452 =item Return Value: $object
1456 Inserts a record into the resultset and returns the object representing it.
1458 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1463 my ($self, $attrs) = @_;
1464 $self->throw_exception( "create needs a hashref" )
1465 unless ref $attrs eq 'HASH';
1466 return $self->new_result($attrs)->insert;
1469 =head2 find_or_create
1473 =item Arguments: \%vals, \%attrs?
1475 =item Return Value: $object
1479 $class->find_or_create({ key => $val, ... });
1481 Tries to find a record based on its primary key or unique constraint; if none
1482 is found, creates one and returns that instead.
1484 my $cd = $schema->resultset('CD')->find_or_create({
1486 artist => 'Massive Attack',
1487 title => 'Mezzanine',
1491 Also takes an optional C<key> attribute, to search by a specific key or unique
1492 constraint. For example:
1494 my $cd = $schema->resultset('CD')->find_or_create(
1496 artist => 'Massive Attack',
1497 title => 'Mezzanine',
1499 { key => 'cd_artist_title' }
1502 See also L</find> and L</update_or_create>. For information on how to declare
1503 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1507 sub find_or_create {
1509 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1510 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1511 my $exists = $self->find($hash, $attrs);
1512 return defined $exists ? $exists : $self->create($hash);
1515 =head2 update_or_create
1519 =item Arguments: \%col_values, { key => $unique_constraint }?
1521 =item Return Value: $object
1525 $class->update_or_create({ col => $val, ... });
1527 First, searches for an existing row matching one of the unique constraints
1528 (including the primary key) on the source of this resultset. If a row is
1529 found, updates it with the other given column values. Otherwise, creates a new
1532 Takes an optional C<key> attribute to search on a specific unique constraint.
1535 # In your application
1536 my $cd = $schema->resultset('CD')->update_or_create(
1538 artist => 'Massive Attack',
1539 title => 'Mezzanine',
1542 { key => 'cd_artist_title' }
1545 If no C<key> is specified, it searches on all unique constraints defined on the
1546 source, including the primary key.
1548 If the C<key> is specified as C<primary>, it searches only on the primary key.
1550 See also L</find> and L</find_or_create>. For information on how to declare
1551 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1555 sub update_or_create {
1557 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1558 my $cond = ref $_[0] eq 'HASH' ? shift : {@_};
1560 my $row = $self->find($cond);
1562 $row->update($cond);
1566 return $self->create($cond);
1573 =item Arguments: none
1575 =item Return Value: \@cache_objects?
1579 Gets the contents of the cache for the resultset, if the cache is set.
1591 =item Arguments: \@cache_objects
1593 =item Return Value: \@cache_objects
1597 Sets the contents of the cache for the resultset. Expects an arrayref
1598 of objects of the same class as those produced by the resultset. Note that
1599 if the cache is set the resultset will return the cached objects rather
1600 than re-querying the database even if the cache attr is not set.
1605 my ( $self, $data ) = @_;
1606 $self->throw_exception("set_cache requires an arrayref")
1607 if defined($data) && (ref $data ne 'ARRAY');
1608 $self->{all_cache} = $data;
1615 =item Arguments: none
1617 =item Return Value: []
1621 Clears the cache for the resultset.
1626 shift->set_cache(undef);
1629 =head2 related_resultset
1633 =item Arguments: $relationship_name
1635 =item Return Value: $resultset
1639 Returns a related resultset for the supplied relationship name.
1641 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1645 sub related_resultset {
1646 my ( $self, $rel ) = @_;
1648 $self->{related_resultsets} ||= {};
1649 return $self->{related_resultsets}{$rel} ||= do {
1650 #warn "fetching related resultset for rel '$rel' " . $self->result_source->{name};
1651 my $rel_obj = $self->result_source->relationship_info($rel);
1652 #print Dumper($self->result_source->_relationships);
1653 $self->throw_exception(
1654 "search_related: result source '" . $self->result_source->name .
1655 "' has no such relationship ${rel}")
1656 unless $rel_obj; #die Dumper $self->{attrs};
1658 my @live_join_stack = (
1659 exists $self->{attrs}->{_live_join_stack})
1660 ? @{$self->{attrs}->{_live_join_stack}}
1663 push(@live_join_stack, $rel);
1665 my $rs = $self->result_source->schema->resultset($rel_obj->{class})->search(
1669 _live_join => $rel, #the most recent
1670 _live_join_stack => \@live_join_stack, #the trail of rels
1671 _parent_attrs => $self->{attrs}}
1674 # keep reference of the original resultset
1675 $rs->{_parent_rs} = ($self->{_parent_rs})
1676 ? $self->{_parent_rs}
1677 : $self->result_source;
1683 =head2 throw_exception
1685 See L<DBIx::Class::Schema/throw_exception> for details.
1689 sub throw_exception {
1691 $self->result_source->schema->throw_exception(@_);
1694 # XXX: FIXME: Attributes docs need clearing up
1698 The resultset takes various attributes that modify its behavior. Here's an
1705 =item Value: ($order_by | \@order_by)
1709 Which column(s) to order the results by. This is currently passed
1710 through directly to SQL, so you can give e.g. C<year DESC> for a
1711 descending order on the column `year'.
1713 Please note that if you have quoting enabled (see
1714 L<DBIx::Class::Storage/quote_char>) you will need to do C<\'year DESC' > to
1715 specify an order. (The scalar ref causes it to be passed as raw sql to the DB,
1716 so you will need to manually quote things as appropriate.)
1722 =item Value: \@columns
1726 Shortcut to request a particular set of columns to be retrieved. Adds
1727 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1728 from that, then auto-populates C<as> from C<select> as normal. (You may also
1729 use the C<cols> attribute, as in earlier versions of DBIC.)
1731 =head2 include_columns
1735 =item Value: \@columns
1739 Shortcut to include additional columns in the returned results - for example
1741 $schema->resultset('CD')->search(undef, {
1742 include_columns => ['artist.name'],
1746 would return all CDs and include a 'name' column to the information
1747 passed to object inflation
1753 =item Value: \@select_columns
1757 Indicates which columns should be selected from the storage. You can use
1758 column names, or in the case of RDBMS back ends, function or stored procedure
1761 $rs = $schema->resultset('Employee')->search(undef, {
1764 { count => 'employeeid' },
1769 When you use function/stored procedure names and do not supply an C<as>
1770 attribute, the column names returned are storage-dependent. E.g. MySQL would
1771 return a column named C<count(employeeid)> in the above example.
1777 Indicates additional columns to be selected from storage. Works the same as
1778 L<select> but adds columns to the selection.
1786 Indicates additional column names for those added via L<+select>.
1794 =item Value: \@inflation_names
1798 Indicates column names for object inflation. This is used in conjunction with
1799 C<select>, usually when C<select> contains one or more function or stored
1802 $rs = $schema->resultset('Employee')->search(undef, {
1805 { count => 'employeeid' }
1807 as => ['name', 'employee_count'],
1810 my $employee = $rs->first(); # get the first Employee
1812 If the object against which the search is performed already has an accessor
1813 matching a column name specified in C<as>, the value can be retrieved using
1814 the accessor as normal:
1816 my $name = $employee->name();
1818 If on the other hand an accessor does not exist in the object, you need to
1819 use C<get_column> instead:
1821 my $employee_count = $employee->get_column('employee_count');
1823 You can create your own accessors if required - see
1824 L<DBIx::Class::Manual::Cookbook> for details.
1826 Please note: This will NOT insert an C<AS employee_count> into the SQL statement
1827 produced, it is used for internal access only. Thus attempting to use the accessor
1828 in an C<order_by> clause or similar will fail misrably.
1834 =item Value: ($rel_name | \@rel_names | \%rel_names)
1838 Contains a list of relationships that should be joined for this query. For
1841 # Get CDs by Nine Inch Nails
1842 my $rs = $schema->resultset('CD')->search(
1843 { 'artist.name' => 'Nine Inch Nails' },
1844 { join => 'artist' }
1847 Can also contain a hash reference to refer to the other relation's relations.
1850 package MyApp::Schema::Track;
1851 use base qw/DBIx::Class/;
1852 __PACKAGE__->table('track');
1853 __PACKAGE__->add_columns(qw/trackid cd position title/);
1854 __PACKAGE__->set_primary_key('trackid');
1855 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1858 # In your application
1859 my $rs = $schema->resultset('Artist')->search(
1860 { 'track.title' => 'Teardrop' },
1862 join => { cd => 'track' },
1863 order_by => 'artist.name',
1867 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1868 similarly for a third time). For e.g.
1870 my $rs = $schema->resultset('Artist')->search({
1871 'cds.title' => 'Down to Earth',
1872 'cds_2.title' => 'Popular',
1874 join => [ qw/cds cds/ ],
1877 will return a set of all artists that have both a cd with title 'Down
1878 to Earth' and a cd with title 'Popular'.
1880 If you want to fetch related objects from other tables as well, see C<prefetch>
1887 =item Value: ($rel_name | \@rel_names | \%rel_names)
1891 Contains one or more relationships that should be fetched along with the main
1892 query (when they are accessed afterwards they will have already been
1893 "prefetched"). This is useful for when you know you will need the related
1894 objects, because it saves at least one query:
1896 my $rs = $schema->resultset('Tag')->search(
1905 The initial search results in SQL like the following:
1907 SELECT tag.*, cd.*, artist.* FROM tag
1908 JOIN cd ON tag.cd = cd.cdid
1909 JOIN artist ON cd.artist = artist.artistid
1911 L<DBIx::Class> has no need to go back to the database when we access the
1912 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1915 Simple prefetches will be joined automatically, so there is no need
1916 for a C<join> attribute in the above search. If you're prefetching to
1917 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1918 specify the join as well.
1920 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1921 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1922 with an accessor type of 'single' or 'filter').
1932 Makes the resultset paged and specifies the page to retrieve. Effectively
1933 identical to creating a non-pages resultset and then calling ->page($page)
1936 If L<rows> attribute is not specified it defualts to 10 rows per page.
1946 Specifes the maximum number of rows for direct retrieval or the number of
1947 rows per page if the page attribute or method is used.
1953 =item Value: $offset
1957 Specifies the (zero-based) row number for the first row to be returned, or the
1958 of the first row of the first page if paging is used.
1964 =item Value: \@columns
1968 A arrayref of columns to group by. Can include columns of joined tables.
1970 group_by => [qw/ column1 column2 ... /]
1976 =item Value: $condition
1980 HAVING is a select statement attribute that is applied between GROUP BY and
1981 ORDER BY. It is applied to the after the grouping calculations have been
1984 having => { 'count(employee)' => { '>=', 100 } }
1990 =item Value: (0 | 1)
1994 Set to 1 to group by all columns.
2000 Adds to the WHERE clause.
2002 # only return rows WHERE deleted IS NULL for all searches
2003 __PACKAGE__->resultset_attributes({ where => { deleted => undef } }); )
2005 Can be overridden by passing C<{ where => undef }> as an attribute
2012 Set to 1 to cache search results. This prevents extra SQL queries if you
2013 revisit rows in your ResultSet:
2015 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
2017 while( my $artist = $resultset->next ) {
2021 $rs->first; # without cache, this would issue a query
2023 By default, searches are not cached.
2025 For more examples of using these attributes, see
2026 L<DBIx::Class::Manual::Cookbook>.
2032 =item Value: \@from_clause
2036 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
2037 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
2040 NOTE: Use this on your own risk. This allows you to shoot off your foot!
2042 C<join> will usually do what you need and it is strongly recommended that you
2043 avoid using C<from> unless you cannot achieve the desired result using C<join>.
2044 And we really do mean "cannot", not just tried and failed. Attempting to use
2045 this because you're having problems with C<join> is like trying to use x86
2046 ASM because you've got a syntax error in your C. Trust us on this.
2048 Now, if you're still really, really sure you need to use this (and if you're
2049 not 100% sure, ask the mailing list first), here's an explanation of how this
2052 The syntax is as follows -
2055 { <alias1> => <table1> },
2057 { <alias2> => <table2>, -join_type => 'inner|left|right' },
2058 [], # nested JOIN (optional)
2059 { <table1.column1> => <table2.column2>, ... (more conditions) },
2061 # More of the above [ ] may follow for additional joins
2068 ON <table1.column1> = <table2.column2>
2069 <more joins may follow>
2071 An easy way to follow the examples below is to remember the following:
2073 Anything inside "[]" is a JOIN
2074 Anything inside "{}" is a condition for the enclosing JOIN
2076 The following examples utilize a "person" table in a family tree application.
2077 In order to express parent->child relationships, this table is self-joined:
2079 # Person->belongs_to('father' => 'Person');
2080 # Person->belongs_to('mother' => 'Person');
2082 C<from> can be used to nest joins. Here we return all children with a father,
2083 then search against all mothers of those children:
2085 $rs = $schema->resultset('Person')->search(
2088 alias => 'mother', # alias columns in accordance with "from"
2090 { mother => 'person' },
2093 { child => 'person' },
2095 { father => 'person' },
2096 { 'father.person_id' => 'child.father_id' }
2099 { 'mother.person_id' => 'child.mother_id' }
2106 # SELECT mother.* FROM person mother
2109 # JOIN person father
2110 # ON ( father.person_id = child.father_id )
2112 # ON ( mother.person_id = child.mother_id )
2114 The type of any join can be controlled manually. To search against only people
2115 with a father in the person table, we could explicitly use C<INNER JOIN>:
2117 $rs = $schema->resultset('Person')->search(
2120 alias => 'child', # alias columns in accordance with "from"
2122 { child => 'person' },
2124 { father => 'person', -join_type => 'inner' },
2125 { 'father.id' => 'child.father_id' }
2132 # SELECT child.* FROM person child
2133 # INNER JOIN person father ON child.father_id = father.id