1 package DBIx::Class::ResultSet;
12 use Scalar::Util qw/weaken/;
14 use DBIx::Class::ResultSetColumn;
15 use base qw/DBIx::Class/;
16 __PACKAGE__->load_components(qw/AccessorGroup/);
17 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
21 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
25 my $rs = $schema->resultset('User')->search(registered => 1);
26 my @rows = $schema->resultset('CD')->search(year => 2005);
30 The resultset is also known as an iterator. It is responsible for handling
31 queries that may return an arbitrary number of rows, e.g. via L</search>
32 or a C<has_many> relationship.
34 In the examples below, the following table classes are used:
36 package MyApp::Schema::Artist;
37 use base qw/DBIx::Class/;
38 __PACKAGE__->load_components(qw/Core/);
39 __PACKAGE__->table('artist');
40 __PACKAGE__->add_columns(qw/artistid name/);
41 __PACKAGE__->set_primary_key('artistid');
42 __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
45 package MyApp::Schema::CD;
46 use base qw/DBIx::Class/;
47 __PACKAGE__->load_components(qw/Core/);
48 __PACKAGE__->table('cd');
49 __PACKAGE__->add_columns(qw/cdid artist title year/);
50 __PACKAGE__->set_primary_key('cdid');
51 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
60 =item Arguments: $source, \%$attrs
62 =item Return Value: $rs
66 The resultset constructor. Takes a source object (usually a
67 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
68 L</ATTRIBUTES> below). Does not perform any queries -- these are
69 executed as needed by the other methods.
71 Generally you won't need to construct a resultset manually. You'll
72 automatically get one from e.g. a L</search> called in scalar context:
74 my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
76 IMPORTANT: If called on an object, proxies to new_result instead so
78 my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
80 will return a CD object, not a ResultSet.
86 return $class->new_result(@_) if ref $class;
88 my ($source, $attrs) = @_;
92 $attrs->{rows} ||= 10;
93 $attrs->{offset} ||= 0;
94 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
97 $attrs->{alias} ||= 'me';
100 result_source => $source,
101 result_class => $attrs->{result_class} || $source->result_class,
102 cond => $attrs->{where},
103 # from => $attrs->{from},
104 # collapse => $collapse,
106 page => delete $attrs->{page},
116 =item Arguments: $cond, \%attrs?
118 =item Return Value: $resultset (scalar context), @row_objs (list context)
122 my @cds = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
123 my $new_rs = $cd_rs->search({ year => 2005 });
125 my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
126 # year = 2005 OR year = 2004
128 If you need to pass in additional attributes but no additional condition,
129 call it as C<search(undef, \%attrs)>.
131 # "SELECT name, artistid FROM $artist_table"
132 my @all_artists = $schema->resultset('Artist')->search(undef, {
133 columns => [qw/name artistid/],
140 my $rs = $self->search_rs( @_ );
141 return (wantarray ? $rs->all : $rs);
148 =item Arguments: $cond, \%attrs?
150 =item Return Value: $resultset
154 This method does the same exact thing as search() except it will
155 always return a resultset, even in list context.
162 my $our_attrs = { %{$self->{attrs}} };
163 my $having = delete $our_attrs->{having};
165 $attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
167 # merge new attrs into old
168 foreach my $key (qw/join prefetch/) {
169 next unless (exists $attrs->{$key});
170 if (exists $our_attrs->{$key}) {
171 $our_attrs->{$key} = $self->_merge_attr($our_attrs->{$key}, $attrs->{$key});
173 $our_attrs->{$key} = $attrs->{$key};
175 delete $attrs->{$key};
178 if (exists $our_attrs->{prefetch}) {
179 $our_attrs->{join} = $self->_merge_attr($our_attrs->{join}, $our_attrs->{prefetch}, 1);
182 my $new_attrs = { %{$our_attrs}, %{$attrs} };
184 # merge new where and having into old
186 ? ((@_ == 1 || ref $_[0] eq "HASH")
189 ? $self->throw_exception(
190 "Odd number of arguments to search")
193 if (defined $where) {
194 $new_attrs->{where} = (defined $new_attrs->{where}
196 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
197 $where, $new_attrs->{where} ] }
201 if (defined $having) {
202 $new_attrs->{having} = (defined $new_attrs->{having}
204 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
205 $having, $new_attrs->{having} ] }
209 my $rs = (ref $self)->new($self->result_source, $new_attrs);
210 $rs->{_parent_rs} = $self->{_parent_rs} if ($self->{_parent_rs}); #XXX - hack to pass through parent of related resultsets
212 unless (@_) { # no search, effectively just a clone
213 my $rows = $self->get_cache;
215 $rs->set_cache($rows);
222 =head2 search_literal
226 =item Arguments: $sql_fragment, @bind_values
228 =item Return Value: $resultset (scalar context), @row_objs (list context)
232 my @cds = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
233 my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
235 Pass a literal chunk of SQL to be added to the conditional part of the
241 my ($self, $cond, @vals) = @_;
242 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
243 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
244 return $self->search(\$cond, $attrs);
251 =item Arguments: @values | \%cols, \%attrs?
253 =item Return Value: $row_object
257 Finds a row based on its primary key or unique constraint. For example, to find
258 a row by its primary key:
260 my $cd = $schema->resultset('CD')->find(5);
262 You can also find a row by a specific unique constraint using the C<key>
263 attribute. For example:
265 my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', { key => 'artist_title' });
267 Additionally, you can specify the columns explicitly by name:
269 my $cd = $schema->resultset('CD')->find(
271 artist => 'Massive Attack',
272 title => 'Mezzanine',
274 { key => 'artist_title' }
277 If no C<key> is specified and you explicitly name columns, it searches on all
278 unique constraints defined on the source, including the primary key.
280 If the C<key> is specified as C<primary>, it searches only on the primary key.
282 See also L</find_or_create> and L</update_or_create>. For information on how to
283 declare unique constraints, see
284 L<DBIx::Class::ResultSource/add_unique_constraint>.
290 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
292 # Parse out a hash from input
293 my @cols = exists $attrs->{key}
294 ? $self->result_source->unique_constraint_columns($attrs->{key})
295 : $self->result_source->primary_columns;
298 if (ref $_[0] eq 'HASH') {
299 $hash = { %{$_[0]} };
301 elsif (@_ == @cols) {
303 @{$hash}{@cols} = @_;
306 # For backwards compatibility
310 $self->throw_exception(
311 "Arguments to find must be a hashref or match the number of columns in the "
312 . (exists $attrs->{key} ? "$attrs->{key} unique constraint" : "primary key")
316 # Check the hash we just parsed against our source's unique constraints
317 my @constraint_names = exists $attrs->{key}
319 : $self->result_source->unique_constraint_names;
320 $self->throw_exception(
321 "Can't find unless a primary key or unique constraint is defined"
322 ) unless @constraint_names;
325 foreach my $name (@constraint_names) {
326 my @unique_cols = $self->result_source->unique_constraint_columns($name);
327 my $unique_query = $self->_build_unique_query($hash, \@unique_cols);
329 # Add the ResultSet's alias
330 foreach my $key (grep { ! m/\./ } keys %$unique_query) {
331 my $alias = $self->{attrs}->{alias};
332 $unique_query->{"$alias.$key"} = delete $unique_query->{$key};
335 push @unique_queries, $unique_query if %$unique_query;
338 # Handle cases where the ResultSet already defines the query
339 my $query = @unique_queries ? \@unique_queries : undef;
343 my $rs = $self->search($query, $attrs);
345 return keys %{$rs->{_attrs}->{collapse}} ? $rs->next : $rs->single;
349 return (keys %{$self->{_attrs}->{collapse}})
350 ? $self->search($query)->next
351 : $self->single($query);
355 # _build_unique_query
357 # Constrain the specified query hash based on the specified column names.
359 sub _build_unique_query {
360 my ($self, $query, $unique_cols) = @_;
363 map { $_ => $query->{$_} }
364 grep { exists $query->{$_} }
367 return \%unique_query;
370 =head2 search_related
374 =item Arguments: $cond, \%attrs?
376 =item Return Value: $new_resultset
380 $new_rs = $cd_rs->search_related('artist', {
384 Searches the specified relationship, optionally specifying a condition and
385 attributes for matching records. See L</ATTRIBUTES> for more information.
390 return shift->related_resultset(shift)->search(@_);
397 =item Arguments: none
399 =item Return Value: $cursor
403 Returns a storage-driven cursor to the given resultset. See
404 L<DBIx::Class::Cursor> for more information.
412 my $attrs = { %{$self->{_attrs}} };
413 return $self->{cursor}
414 ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
415 $attrs->{where},$attrs);
422 =item Arguments: $cond?
424 =item Return Value: $row_object?
428 my $cd = $schema->resultset('CD')->single({ year => 2001 });
430 Inflates the first result without creating a cursor if the resultset has
431 any records in it; if not returns nothing. Used by L</find> as an optimisation.
436 my ($self, $where) = @_;
438 my $attrs = { %{$self->{_attrs}} };
440 if (defined $attrs->{where}) {
443 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
444 $where, delete $attrs->{where} ]
447 $attrs->{where} = $where;
451 my @data = $self->result_source->storage->select_single(
452 $attrs->{from}, $attrs->{select},
453 $attrs->{where},$attrs);
454 return (@data ? $self->_construct_object(@data) : ());
461 =item Arguments: $cond?
463 =item Return Value: $resultsetcolumn
467 my $max_length = $rs->get_column('length')->max;
469 Returns a ResultSetColumn instance for $column based on $self
474 my ($self, $column) = @_;
476 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
484 =item Arguments: $cond, \%attrs?
486 =item Return Value: $resultset (scalar context), @row_objs (list context)
490 # WHERE title LIKE '%blue%'
491 $cd_rs = $rs->search_like({ title => '%blue%'});
493 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
494 that this is simply a convenience method. You most likely want to use
495 L</search> with specific operators.
497 For more information, see L<DBIx::Class::Manual::Cookbook>.
503 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
504 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
505 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
506 return $class->search($query, { %$attrs });
513 =item Arguments: $first, $last
515 =item Return Value: $resultset (scalar context), @row_objs (list context)
519 Returns a resultset or object list representing a subset of elements from the
520 resultset slice is called on. Indexes are from 0, i.e., to get the first
523 my ($one, $two, $three) = $rs->slice(0, 2);
528 my ($self, $min, $max) = @_;
529 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
530 $attrs->{offset} = $self->{attrs}{offset} || 0;
531 $attrs->{offset} += $min;
532 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
533 return $self->search(undef(), $attrs);
534 #my $slice = (ref $self)->new($self->result_source, $attrs);
535 #return (wantarray ? $slice->all : $slice);
542 =item Arguments: none
544 =item Return Value: $result?
548 Returns the next element in the resultset (C<undef> is there is none).
550 Can be used to efficiently iterate over records in the resultset:
552 my $rs = $schema->resultset('CD')->search;
553 while (my $cd = $rs->next) {
557 Note that you need to store the resultset object, and call C<next> on it.
558 Calling C<< resultset('Table')->next >> repeatedly will always return the
559 first record from the resultset.
565 if (my $cache = $self->get_cache) {
566 $self->{all_cache_position} ||= 0;
567 return $cache->[$self->{all_cache_position}++];
569 if ($self->{attrs}{cache}) {
570 $self->{all_cache_position} = 1;
571 return ($self->all)[0];
573 my @row = (exists $self->{stashed_row} ?
574 @{delete $self->{stashed_row}} :
577 return unless (@row);
578 return $self->_construct_object(@row);
584 return if(exists $self->{_attrs}); #return if _resolve has already been called
586 my $attrs = $self->{attrs};
587 my $source = ($self->{_parent_rs}) ? $self->{_parent_rs} : $self->{result_source};
589 # XXX - lose storable dclone
590 my $record_filter = delete $attrs->{record_filter} if (defined $attrs->{record_filter});
591 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
592 $attrs->{record_filter} = $record_filter if ($record_filter);
593 $self->{attrs}->{record_filter} = $record_filter if ($record_filter);
595 my $alias = $attrs->{alias};
597 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
598 delete $attrs->{as} if $attrs->{columns};
599 $attrs->{columns} ||= [ $self->{result_source}->columns ] unless $attrs->{select};
600 my $select_alias = ($self->{_parent_rs}) ? $self->{attrs}->{_live_join} : $alias;
602 map { m/\./ ? $_ : "${select_alias}.$_" } @{delete $attrs->{columns}}
603 ] if $attrs->{columns};
605 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
607 if (my $include = delete $attrs->{include_columns}) {
608 push(@{$attrs->{select}}, @$include);
609 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
612 $attrs->{from} ||= [ { $alias => $source->from } ];
613 $attrs->{seen_join} ||= {};
615 if (my $join = delete $attrs->{join}) {
616 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
617 if (ref $j eq 'HASH') {
618 $seen{$_} = 1 foreach keys %$j;
624 push(@{$attrs->{from}}, $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join}));
626 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
627 $attrs->{order_by} = [ $attrs->{order_by} ] if
628 $attrs->{order_by} and !ref($attrs->{order_by});
629 $attrs->{order_by} ||= [];
631 my $collapse = $attrs->{collapse} || {};
632 if (my $prefetch = delete $attrs->{prefetch}) {
634 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
635 if ( ref $p eq 'HASH' ) {
636 foreach my $key (keys %$p) {
637 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
641 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
644 my @prefetch = $source->resolve_prefetch(
645 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
646 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
647 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
649 push(@{$attrs->{order_by}}, @pre_order);
651 $attrs->{collapse} = $collapse;
652 $self->{_attrs} = $attrs;
656 my ($self, $a, $b, $is_prefetch) = @_;
659 if (ref $b eq 'HASH' && ref $a eq 'HASH') {
660 foreach my $key (keys %{$b}) {
661 if (exists $a->{$key}) {
662 $a->{$key} = $self->_merge_attr($a->{$key}, $b->{$key}, $is_prefetch);
664 $a->{$key} = delete $b->{$key};
669 $a = [$a] unless (ref $a eq 'ARRAY');
670 $b = [$b] unless (ref $b eq 'ARRAY');
675 foreach my $element (@{$_}) {
676 if (ref $element eq 'HASH') {
677 $hash = $self->_merge_attr($hash, $element, $is_prefetch);
678 } elsif (ref $element eq 'ARRAY') {
679 $array = [@{$array}, @{$element}];
681 if (($b == $_) && $is_prefetch) {
682 $self->_merge_array($array, $element, $is_prefetch);
684 push(@{$array}, $element);
690 if ((keys %{$hash}) && (scalar(@{$array} > 0))) {
691 return [$hash, @{$array}];
693 return (keys %{$hash}) ? $hash : $array;
699 my ($self, $a, $b) = @_;
701 $b = [$b] unless (ref $b eq 'ARRAY');
702 # add elements from @{$b} to @{$a} which aren't already in @{$a}
703 foreach my $b_element (@{$b}) {
704 push(@{$a}, $b_element) unless grep {$b_element eq $_} @{$a};
708 sub _construct_object {
709 my ($self, @row) = @_;
710 my @as = @{ $self->{_attrs}{as} };
712 my $info = $self->_collapse_result(\@as, \@row);
713 my $new = $self->result_class->inflate_result($self->result_source, @$info);
714 $new = $self->{_attrs}{record_filter}->($new)
715 if exists $self->{_attrs}{record_filter};
719 sub _collapse_result {
720 my ($self, $as, $row, $prefix) = @_;
722 my $live_join = $self->{attrs}->{_live_join} ||="";
726 foreach my $this_as (@$as) {
727 my $val = shift @copy;
728 if (defined $prefix) {
729 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
731 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
732 $const{$1||''}{$2} = $val;
735 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
736 $const{$1||''}{$2} = $val;
740 my $info = [ {}, {} ];
741 foreach my $key (keys %const) {
742 if (length $key && $key ne $live_join) {
744 my @parts = split(/\./, $key);
745 foreach my $p (@parts) {
746 $target = $target->[1]->{$p} ||= [];
748 $target->[0] = $const{$key};
750 $info->[0] = $const{$key};
755 if (defined $prefix) {
757 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
758 } keys %{$self->{_attrs}->{collapse}}
760 @collapse = keys %{$self->{_attrs}->{collapse}};
764 my ($c) = sort { length $a <=> length $b } @collapse;
766 foreach my $p (split(/\./, $c)) {
767 $target = $target->[1]->{$p} ||= [];
769 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
770 my @co_key = @{$self->{_attrs}->{collapse}{$c_prefix}};
771 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
772 my $tree = $self->_collapse_result($as, $row, $c_prefix);
775 !defined($tree->[0]->{$_}) ||
776 $co_check{$_} ne $tree->[0]->{$_}
779 last unless (@raw = $self->cursor->next);
780 $row = $self->{stashed_row} = \@raw;
781 $tree = $self->_collapse_result($as, $row, $c_prefix);
783 @$target = (@final ? @final : [ {}, {} ]);
784 # single empty result to indicate an empty prefetched has_many
793 =item Arguments: $result_source?
795 =item Return Value: $result_source
799 An accessor for the primary ResultSource object from which this ResultSet
809 =item Arguments: $cond, \%attrs??
811 =item Return Value: $count
815 Performs an SQL C<COUNT> with the same query as the resultset was built
816 with to find the number of elements. If passed arguments, does a search
817 on the resultset and counts the results of that.
819 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
820 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
821 not support C<DISTINCT> with multiple columns. If you are using such a
822 database, you should only use columns from the main table in your C<group_by>
829 return $self->search(@_)->count if @_ and defined $_[0];
830 return scalar @{ $self->get_cache } if $self->get_cache;
832 my $count = $self->_count;
833 return 0 unless $count;
835 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
836 $count = $self->{attrs}{rows} if
837 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
841 sub _count { # Separated out so pager can get the full count
843 my $select = { count => '*' };
846 my $attrs = { %{ $self->{_attrs} } };
847 if ($attrs->{distinct} && (my $group_by = $attrs->{group_by} || $attrs->{select})) {
848 delete $attrs->{having};
849 my @distinct = (ref $group_by ? @$group_by : ($group_by));
850 # todo: try CONCAT for multi-column pk
851 my @pk = $self->result_source->primary_columns;
853 foreach my $column (@distinct) {
854 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
855 @distinct = ($column);
861 $select = { count => { distinct => \@distinct } };
864 $attrs->{select} = $select;
865 $attrs->{as} = [qw/count/];
867 # offset, order by and page are not needed to count. record_filter is cdbi
868 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
869 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
877 =item Arguments: $sql_fragment, @bind_values
879 =item Return Value: $count
883 Counts the results in a literal query. Equivalent to calling L</search_literal>
884 with the passed arguments, then L</count>.
888 sub count_literal { shift->search_literal(@_)->count; }
894 =item Arguments: none
896 =item Return Value: @objects
900 Returns all elements in the resultset. Called implicitly if the resultset
901 is returned in list context.
907 return @{ $self->get_cache } if $self->get_cache;
911 # TODO: don't call resolve here
913 if (keys %{$self->{_attrs}->{collapse}}) {
914 # if ($self->{attrs}->{prefetch}) {
915 # Using $self->cursor->all is really just an optimisation.
916 # If we're collapsing has_many prefetches it probably makes
917 # very little difference, and this is cleaner than hacking
918 # _construct_object to survive the approach
919 my @row = $self->cursor->next;
921 push(@obj, $self->_construct_object(@row));
922 @row = (exists $self->{stashed_row}
923 ? @{delete $self->{stashed_row}}
924 : $self->cursor->next);
927 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
930 $self->set_cache(\@obj) if $self->{attrs}{cache};
938 =item Arguments: none
940 =item Return Value: $self
944 Resets the resultset's cursor, so you can iterate through the elements again.
950 delete $self->{_attrs} if (exists $self->{_attrs});
952 $self->{all_cache_position} = 0;
953 $self->cursor->reset;
961 =item Arguments: none
963 =item Return Value: $object?
967 Resets the resultset and returns an object for the first result (if the
968 resultset returns anything).
973 return $_[0]->reset->next;
976 # _cond_for_update_delete
978 # update/delete require the condition to be modified to handle
979 # the differing SQL syntax available. This transforms the $self->{cond}
980 # appropriately, returning the new condition.
982 sub _cond_for_update_delete {
986 if (!ref($self->{cond})) {
987 # No-op. No condition, we're updating/deleting everything
989 elsif (ref $self->{cond} eq 'ARRAY') {
993 foreach my $key (keys %{$_}) {
995 $hash{$1} = $_->{$key};
1001 elsif (ref $self->{cond} eq 'HASH') {
1002 if ((keys %{$self->{cond}})[0] eq '-and') {
1005 my @cond = @{$self->{cond}{-and}};
1006 for (my $i = 0; $i < @cond - 1; $i++) {
1007 my $entry = $cond[$i];
1010 if (ref $entry eq 'HASH') {
1011 foreach my $key (keys %{$entry}) {
1013 $hash{$1} = $entry->{$key};
1017 $entry =~ /([^.]+)$/;
1018 $hash{$entry} = $cond[++$i];
1021 push @{$cond->{-and}}, \%hash;
1025 foreach my $key (keys %{$self->{cond}}) {
1027 $cond->{$1} = $self->{cond}{$key};
1032 $self->throw_exception(
1033 "Can't update/delete on resultset with condition unless hash or array"
1045 =item Arguments: \%values
1047 =item Return Value: $storage_rv
1051 Sets the specified columns in the resultset to the supplied values in a
1052 single query. Return value will be true if the update succeeded or false
1053 if no records were updated; exact type of success value is storage-dependent.
1058 my ($self, $values) = @_;
1059 $self->throw_exception("Values for update must be a hash")
1060 unless ref $values eq 'HASH';
1062 my $cond = $self->_cond_for_update_delete;
1064 return $self->result_source->storage->update(
1065 $self->result_source->from, $values, $cond
1073 =item Arguments: \%values
1075 =item Return Value: 1
1079 Fetches all objects and updates them one at a time. Note that C<update_all>
1080 will run DBIC cascade triggers, while L</update> will not.
1085 my ($self, $values) = @_;
1086 $self->throw_exception("Values for update must be a hash")
1087 unless ref $values eq 'HASH';
1088 foreach my $obj ($self->all) {
1089 $obj->set_columns($values)->update;
1098 =item Arguments: none
1100 =item Return Value: 1
1104 Deletes the contents of the resultset from its result source. Note that this
1105 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1114 my $cond = $self->_cond_for_update_delete;
1116 $self->result_source->storage->delete($self->result_source->from, $cond);
1124 =item Arguments: none
1126 =item Return Value: 1
1130 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1131 will run DBIC cascade triggers, while L</delete> will not.
1137 $_->delete for $self->all;
1145 =item Arguments: none
1147 =item Return Value: $pager
1151 Return Value a L<Data::Page> object for the current resultset. Only makes
1152 sense for queries with a C<page> attribute.
1158 my $attrs = $self->{attrs};
1159 $self->throw_exception("Can't create pager for non-paged rs")
1160 unless $self->{page};
1161 $attrs->{rows} ||= 10;
1162 return $self->{pager} ||= Data::Page->new(
1163 $self->_count, $attrs->{rows}, $self->{page});
1170 =item Arguments: $page_number
1172 =item Return Value: $rs
1176 Returns a resultset for the $page_number page of the resultset on which page
1177 is called, where each page contains a number of rows equal to the 'rows'
1178 attribute set on the resultset (10 by default).
1183 my ($self, $page) = @_;
1184 my $attrs = { %{$self->{attrs}} };
1185 $attrs->{page} = $page;
1186 return (ref $self)->new($self->result_source, $attrs);
1193 =item Arguments: \%vals
1195 =item Return Value: $object
1199 Creates an object in the resultset's result class and returns it.
1204 my ($self, $values) = @_;
1205 $self->throw_exception( "new_result needs a hash" )
1206 unless (ref $values eq 'HASH');
1207 $self->throw_exception(
1208 "Can't abstract implicit construct, condition not a hash"
1209 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1211 my $alias = $self->{attrs}{alias};
1212 foreach my $key (keys %{$self->{cond}||{}}) {
1213 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1215 my $obj = $self->result_class->new(\%new);
1216 $obj->result_source($self->result_source) if $obj->can('result_source');
1224 =item Arguments: \%vals, \%attrs?
1226 =item Return Value: $object
1230 Find an existing record from this resultset. If none exists, instantiate a new
1231 result object and return it. The object will not be saved into your storage
1232 until you call L<DBIx::Class::Row/insert> on it.
1234 If you want objects to be saved immediately, use L</find_or_create> instead.
1240 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1241 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1242 my $exists = $self->find($hash, $attrs);
1243 return defined $exists ? $exists : $self->new_result($hash);
1250 =item Arguments: \%vals
1252 =item Return Value: $object
1256 Inserts a record into the resultset and returns the object representing it.
1258 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1263 my ($self, $attrs) = @_;
1264 $self->throw_exception( "create needs a hashref" )
1265 unless ref $attrs eq 'HASH';
1266 return $self->new_result($attrs)->insert;
1269 =head2 find_or_create
1273 =item Arguments: \%vals, \%attrs?
1275 =item Return Value: $object
1279 $class->find_or_create({ key => $val, ... });
1281 Searches for a record matching the search condition; if it doesn't find one,
1282 creates one and returns that instead.
1284 my $cd = $schema->resultset('CD')->find_or_create({
1286 artist => 'Massive Attack',
1287 title => 'Mezzanine',
1291 Also takes an optional C<key> attribute, to search by a specific key or unique
1292 constraint. For example:
1294 my $cd = $schema->resultset('CD')->find_or_create(
1296 artist => 'Massive Attack',
1297 title => 'Mezzanine',
1299 { key => 'artist_title' }
1302 See also L</find> and L</update_or_create>. For information on how to declare
1303 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1307 sub find_or_create {
1309 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1310 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1311 my $exists = $self->find($hash, $attrs);
1312 return defined $exists ? $exists : $self->create($hash);
1315 =head2 update_or_create
1319 =item Arguments: \%col_values, { key => $unique_constraint }?
1321 =item Return Value: $object
1325 $class->update_or_create({ col => $val, ... });
1327 First, searches for an existing row matching one of the unique constraints
1328 (including the primary key) on the source of this resultset. If a row is
1329 found, updates it with the other given column values. Otherwise, creates a new
1332 Takes an optional C<key> attribute to search on a specific unique constraint.
1335 # In your application
1336 my $cd = $schema->resultset('CD')->update_or_create(
1338 artist => 'Massive Attack',
1339 title => 'Mezzanine',
1342 { key => 'artist_title' }
1345 If no C<key> is specified, it searches on all unique constraints defined on the
1346 source, including the primary key.
1348 If the C<key> is specified as C<primary>, it searches only on the primary key.
1350 See also L</find> and L</find_or_create>. For information on how to declare
1351 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1355 sub update_or_create {
1357 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1358 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1360 my $row = $self->find($hash, $attrs);
1362 $row->update($hash);
1366 return $self->create($hash);
1373 =item Arguments: none
1375 =item Return Value: \@cache_objects?
1379 Gets the contents of the cache for the resultset, if the cache is set.
1391 =item Arguments: \@cache_objects
1393 =item Return Value: \@cache_objects
1397 Sets the contents of the cache for the resultset. Expects an arrayref
1398 of objects of the same class as those produced by the resultset. Note that
1399 if the cache is set the resultset will return the cached objects rather
1400 than re-querying the database even if the cache attr is not set.
1405 my ( $self, $data ) = @_;
1406 $self->throw_exception("set_cache requires an arrayref")
1407 if defined($data) && (ref $data ne 'ARRAY');
1408 $self->{all_cache} = $data;
1415 =item Arguments: none
1417 =item Return Value: []
1421 Clears the cache for the resultset.
1426 shift->set_cache(undef);
1429 =head2 related_resultset
1433 =item Arguments: $relationship_name
1435 =item Return Value: $resultset
1439 Returns a related resultset for the supplied relationship name.
1441 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1445 sub related_resultset {
1446 my ( $self, $rel ) = @_;
1448 $self->{related_resultsets} ||= {};
1449 return $self->{related_resultsets}{$rel} ||= do {
1450 #warn "fetching related resultset for rel '$rel' " . $self->result_source->{name};
1451 my $rel_obj = $self->result_source->relationship_info($rel);
1452 $self->throw_exception(
1453 "search_related: result source '" . $self->result_source->name .
1454 "' has no such relationship ${rel}")
1455 unless $rel_obj; #die Dumper $self->{attrs};
1457 my $rs = $self->result_source->schema->resultset($rel_obj->{class}
1459 { %{$self->{attrs}},
1463 _live_join => $rel }
1466 # keep reference of the original resultset
1467 $rs->{_parent_rs} = $self->result_source;
1472 =head2 throw_exception
1474 See L<DBIx::Class::Schema/throw_exception> for details.
1478 sub throw_exception {
1480 $self->result_source->schema->throw_exception(@_);
1483 # XXX: FIXME: Attributes docs need clearing up
1487 The resultset takes various attributes that modify its behavior. Here's an
1494 =item Value: ($order_by | \@order_by)
1498 Which column(s) to order the results by. This is currently passed
1499 through directly to SQL, so you can give e.g. C<year DESC> for a
1500 descending order on the column `year'.
1506 =item Value: \@columns
1510 Shortcut to request a particular set of columns to be retrieved. Adds
1511 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1512 from that, then auto-populates C<as> from C<select> as normal. (You may also
1513 use the C<cols> attribute, as in earlier versions of DBIC.)
1515 =head2 include_columns
1519 =item Value: \@columns
1523 Shortcut to include additional columns in the returned results - for example
1525 $schema->resultset('CD')->search(undef, {
1526 include_columns => ['artist.name'],
1530 would return all CDs and include a 'name' column to the information
1531 passed to object inflation
1537 =item Value: \@select_columns
1541 Indicates which columns should be selected from the storage. You can use
1542 column names, or in the case of RDBMS back ends, function or stored procedure
1545 $rs = $schema->resultset('Employee')->search(undef, {
1548 { count => 'employeeid' },
1553 When you use function/stored procedure names and do not supply an C<as>
1554 attribute, the column names returned are storage-dependent. E.g. MySQL would
1555 return a column named C<count(employeeid)> in the above example.
1561 =item Value: \@inflation_names
1565 Indicates column names for object inflation. This is used in conjunction with
1566 C<select>, usually when C<select> contains one or more function or stored
1569 $rs = $schema->resultset('Employee')->search(undef, {
1572 { count => 'employeeid' }
1574 as => ['name', 'employee_count'],
1577 my $employee = $rs->first(); # get the first Employee
1579 If the object against which the search is performed already has an accessor
1580 matching a column name specified in C<as>, the value can be retrieved using
1581 the accessor as normal:
1583 my $name = $employee->name();
1585 If on the other hand an accessor does not exist in the object, you need to
1586 use C<get_column> instead:
1588 my $employee_count = $employee->get_column('employee_count');
1590 You can create your own accessors if required - see
1591 L<DBIx::Class::Manual::Cookbook> for details.
1597 =item Value: ($rel_name | \@rel_names | \%rel_names)
1601 Contains a list of relationships that should be joined for this query. For
1604 # Get CDs by Nine Inch Nails
1605 my $rs = $schema->resultset('CD')->search(
1606 { 'artist.name' => 'Nine Inch Nails' },
1607 { join => 'artist' }
1610 Can also contain a hash reference to refer to the other relation's relations.
1613 package MyApp::Schema::Track;
1614 use base qw/DBIx::Class/;
1615 __PACKAGE__->table('track');
1616 __PACKAGE__->add_columns(qw/trackid cd position title/);
1617 __PACKAGE__->set_primary_key('trackid');
1618 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1621 # In your application
1622 my $rs = $schema->resultset('Artist')->search(
1623 { 'track.title' => 'Teardrop' },
1625 join => { cd => 'track' },
1626 order_by => 'artist.name',
1630 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1631 similarly for a third time). For e.g.
1633 my $rs = $schema->resultset('Artist')->search({
1634 'cds.title' => 'Down to Earth',
1635 'cds_2.title' => 'Popular',
1637 join => [ qw/cds cds/ ],
1640 will return a set of all artists that have both a cd with title 'Down
1641 to Earth' and a cd with title 'Popular'.
1643 If you want to fetch related objects from other tables as well, see C<prefetch>
1650 =item Value: ($rel_name | \@rel_names | \%rel_names)
1654 Contains one or more relationships that should be fetched along with the main
1655 query (when they are accessed afterwards they will have already been
1656 "prefetched"). This is useful for when you know you will need the related
1657 objects, because it saves at least one query:
1659 my $rs = $schema->resultset('Tag')->search(
1668 The initial search results in SQL like the following:
1670 SELECT tag.*, cd.*, artist.* FROM tag
1671 JOIN cd ON tag.cd = cd.cdid
1672 JOIN artist ON cd.artist = artist.artistid
1674 L<DBIx::Class> has no need to go back to the database when we access the
1675 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1678 Simple prefetches will be joined automatically, so there is no need
1679 for a C<join> attribute in the above search. If you're prefetching to
1680 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1681 specify the join as well.
1683 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1684 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1685 with an accessor type of 'single' or 'filter').
1691 =item Value: \@from_clause
1695 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1696 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1699 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1700 C<join> will usually do what you need and it is strongly recommended that you
1701 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1703 In simple terms, C<from> works as follows:
1706 { <alias> => <table>, -join_type => 'inner|left|right' }
1707 [] # nested JOIN (optional)
1708 { <table.column> => <foreign_table.foreign_key> }
1714 ON <table.column> = <foreign_table.foreign_key>
1716 An easy way to follow the examples below is to remember the following:
1718 Anything inside "[]" is a JOIN
1719 Anything inside "{}" is a condition for the enclosing JOIN
1721 The following examples utilize a "person" table in a family tree application.
1722 In order to express parent->child relationships, this table is self-joined:
1724 # Person->belongs_to('father' => 'Person');
1725 # Person->belongs_to('mother' => 'Person');
1727 C<from> can be used to nest joins. Here we return all children with a father,
1728 then search against all mothers of those children:
1730 $rs = $schema->resultset('Person')->search(
1733 alias => 'mother', # alias columns in accordance with "from"
1735 { mother => 'person' },
1738 { child => 'person' },
1740 { father => 'person' },
1741 { 'father.person_id' => 'child.father_id' }
1744 { 'mother.person_id' => 'child.mother_id' }
1751 # SELECT mother.* FROM person mother
1754 # JOIN person father
1755 # ON ( father.person_id = child.father_id )
1757 # ON ( mother.person_id = child.mother_id )
1759 The type of any join can be controlled manually. To search against only people
1760 with a father in the person table, we could explicitly use C<INNER JOIN>:
1762 $rs = $schema->resultset('Person')->search(
1765 alias => 'child', # alias columns in accordance with "from"
1767 { child => 'person' },
1769 { father => 'person', -join_type => 'inner' },
1770 { 'father.id' => 'child.father_id' }
1777 # SELECT child.* FROM person child
1778 # INNER JOIN person father ON child.father_id = father.id
1788 Makes the resultset paged and specifies the page to retrieve. Effectively
1789 identical to creating a non-pages resultset and then calling ->page($page)
1800 Specifes the maximum number of rows for direct retrieval or the number of
1801 rows per page if the page attribute or method is used.
1807 =item Value: \@columns
1811 A arrayref of columns to group by. Can include columns of joined tables.
1813 group_by => [qw/ column1 column2 ... /]
1819 =item Value: $condition
1823 HAVING is a select statement attribute that is applied between GROUP BY and
1824 ORDER BY. It is applied to the after the grouping calculations have been
1827 having => { 'count(employee)' => { '>=', 100 } }
1833 =item Value: (0 | 1)
1837 Set to 1 to group by all columns.
1841 Set to 1 to cache search results. This prevents extra SQL queries if you
1842 revisit rows in your ResultSet:
1844 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1846 while( my $artist = $resultset->next ) {
1850 $rs->first; # without cache, this would issue a query
1852 By default, searches are not cached.
1854 For more examples of using these attributes, see
1855 L<DBIx::Class::Manual::Cookbook>.