1 package DBIx::Class::ResultSet;
11 use Scalar::Util qw/weaken/;
13 use DBIx::Class::ResultSetColumn;
14 use base qw/DBIx::Class/;
15 __PACKAGE__->load_components(qw/AccessorGroup/);
16 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
20 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
24 my $rs = $schema->resultset('User')->search(registered => 1);
25 my @rows = $schema->resultset('CD')->search(year => 2005);
29 The resultset is also known as an iterator. It is responsible for handling
30 queries that may return an arbitrary number of rows, e.g. via L</search>
31 or a C<has_many> relationship.
33 In the examples below, the following table classes are used:
35 package MyApp::Schema::Artist;
36 use base qw/DBIx::Class/;
37 __PACKAGE__->load_components(qw/Core/);
38 __PACKAGE__->table('artist');
39 __PACKAGE__->add_columns(qw/artistid name/);
40 __PACKAGE__->set_primary_key('artistid');
41 __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
44 package MyApp::Schema::CD;
45 use base qw/DBIx::Class/;
46 __PACKAGE__->load_components(qw/Core/);
47 __PACKAGE__->table('cd');
48 __PACKAGE__->add_columns(qw/cdid artist title year/);
49 __PACKAGE__->set_primary_key('cdid');
50 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
59 =item Arguments: $source, \%$attrs
61 =item Return Value: $rs
65 The resultset constructor. Takes a source object (usually a
66 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
67 L</ATTRIBUTES> below). Does not perform any queries -- these are
68 executed as needed by the other methods.
70 Generally you won't need to construct a resultset manually. You'll
71 automatically get one from e.g. a L</search> called in scalar context:
73 my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
75 IMPORTANT: If called on an object, proxies to new_result instead so
77 my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
79 will return a CD object, not a ResultSet.
85 return $class->new_result(@_) if ref $class;
87 my ($source, $attrs) = @_;
89 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
90 #use Data::Dumper; warn Dumper($attrs);
91 my $alias = ($attrs->{alias} ||= 'me');
93 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
94 delete $attrs->{as} if $attrs->{columns};
95 $attrs->{columns} ||= [ $source->columns ] unless $attrs->{select};
97 map { m/\./ ? $_ : "${alias}.$_" } @{delete $attrs->{columns}}
98 ] if $attrs->{columns};
100 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
102 if (my $include = delete $attrs->{include_columns}) {
103 push(@{$attrs->{select}}, @$include);
104 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
106 #use Data::Dumper; warn Dumper(@{$attrs}{qw/select as/});
108 $attrs->{from} ||= [ { $alias => $source->from } ];
109 $attrs->{seen_join} ||= {};
111 if (my $join = delete $attrs->{join}) {
112 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
113 if (ref $j eq 'HASH') {
114 $seen{$_} = 1 foreach keys %$j;
119 push(@{$attrs->{from}}, $source->resolve_join(
120 $join, $attrs->{alias}, $attrs->{seen_join})
124 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
125 $attrs->{order_by} = [ $attrs->{order_by} ] if
126 $attrs->{order_by} and !ref($attrs->{order_by});
127 $attrs->{order_by} ||= [];
129 my $collapse = $attrs->{collapse} || {};
130 if (my $prefetch = delete $attrs->{prefetch}) {
132 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
133 if ( ref $p eq 'HASH' ) {
134 foreach my $key (keys %$p) {
135 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
139 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
142 my @prefetch = $source->resolve_prefetch(
143 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
144 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
145 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
147 push(@{$attrs->{order_by}}, @pre_order);
149 $attrs->{collapse} = $collapse;
150 # use Data::Dumper; warn Dumper($collapse) if keys %{$collapse};
152 if ($attrs->{page}) {
153 $attrs->{rows} ||= 10;
154 $attrs->{offset} ||= 0;
155 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
159 result_source => $source,
160 result_class => $attrs->{result_class} || $source->result_class,
161 cond => $attrs->{where},
162 from => $attrs->{from},
163 collapse => $collapse,
165 page => delete $attrs->{page},
175 =item Arguments: $cond, \%attrs?
177 =item Return Value: $resultset (scalar context), @row_objs (list context)
181 my @cds = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
182 my $new_rs = $cd_rs->search({ year => 2005 });
184 my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
185 # year = 2005 OR year = 2004
187 If you need to pass in additional attributes but no additional condition,
188 call it as C<search(undef, \%attrs)>.
190 # "SELECT name, artistid FROM $artist_table"
191 my @all_artists = $schema->resultset('Artist')->search(undef, {
192 columns => [qw/name artistid/],
203 my $attrs = { %{$self->{attrs}} };
204 my $having = delete $attrs->{having};
205 $attrs = { %$attrs, %{ pop(@_) } } if @_ > 1 and ref $_[$#_] eq 'HASH';
208 ? ((@_ == 1 || ref $_[0] eq "HASH")
211 ? $self->throw_exception(
212 "Odd number of arguments to search")
215 if (defined $where) {
216 $attrs->{where} = (defined $attrs->{where}
218 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
219 $where, $attrs->{where} ] }
223 if (defined $having) {
224 $attrs->{having} = (defined $attrs->{having}
226 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
227 $having, $attrs->{having} ] }
231 $rs = (ref $self)->new($self->result_source, $attrs);
237 return (wantarray ? $rs->all : $rs);
240 =head2 search_literal
244 =item Arguments: $sql_fragment, @bind_values
246 =item Return Value: $resultset (scalar context), @row_objs (list context)
250 my @cds = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
251 my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
253 Pass a literal chunk of SQL to be added to the conditional part of the
259 my ($self, $cond, @vals) = @_;
260 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
261 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
262 return $self->search(\$cond, $attrs);
269 =item Arguments: @values | \%cols, \%attrs?
271 =item Return Value: $row_object
275 Finds a row based on its primary key or unique constraint. For example:
277 my $cd = $schema->resultset('CD')->find(5);
279 Also takes an optional C<key> attribute, to search by a specific key or unique
280 constraint. For example:
282 my $cd = $schema->resultset('CD')->find(
284 artist => 'Massive Attack',
285 title => 'Mezzanine',
287 { key => 'artist_title' }
290 If no C<key> is specified, it searches on all unique constraints defined on the
291 source, including the primary key.
293 If the C<key> is specified as C<primary>, it searches only on the primary key.
295 See also L</find_or_create> and L</update_or_create>.
300 my ($self, @vals) = @_;
301 my $attrs = (@vals > 1 && ref $vals[$#vals] eq 'HASH' ? pop(@vals) : {});
303 my %unique_constraints = $self->result_source->unique_constraints;
304 $self->throw_exception(
305 "Can't find unless a primary key or unique constraint is defined"
306 ) unless %unique_constraints;
308 my @constraint_names = keys %unique_constraints;
309 if (exists $attrs->{key}) {
310 $self->throw_exception(
311 "Unknown key $attrs->{key} on '" . $self->result_source->name . "'"
312 ) unless exists $unique_constraints{$attrs->{key}};
314 @constraint_names = ($attrs->{key});
318 foreach my $name (@constraint_names) {
319 my @unique_cols = @{ $unique_constraints{$name} };
321 if (ref $vals[0] eq 'HASH') {
322 # Stupid hack for CDBICompat
323 my %hash = %{ $vals[0] };
324 foreach my $key (keys %hash) {
325 $hash{lc $key} = delete $hash{$key};
329 map { $_ => $hash{$_} }
330 grep { exists $hash{$_} }
333 elsif (@unique_cols == @vals) {
334 # Assume the argument order corresponds to the constraint definition
335 @unique_hash{@unique_cols} = @vals;
337 elsif (@vals % 2 == 0) {
338 # Fix for CDBI calling with a hash
339 %unique_hash = @vals;
342 foreach my $key (grep { ! m/\./ } keys %unique_hash) {
343 $unique_hash{"$self->{attrs}{alias}.$key"} = delete $unique_hash{$key};
346 #use Data::Dumper; warn Dumper \@vals, \@unique_cols, \%unique_hash;
347 push @unique_hashes, \%unique_hash if %unique_hash;
350 # Handle cases where the ResultSet already defines the query
351 my $query = @unique_hashes ? \@unique_hashes : undef;
354 my $rs = $self->search($query, $attrs);
355 return keys %{$rs->{collapse}} ? $rs->next : $rs->single;
358 return keys %{$self->{collapse}}
359 ? $self->search($query)->next
360 : $self->single($query);
364 =head2 search_related
368 =item Arguments: $cond, \%attrs?
370 =item Return Value: $new_resultset
374 $new_rs = $cd_rs->search_related('artist', {
378 Searches the specified relationship, optionally specifying a condition and
379 attributes for matching records. See L</ATTRIBUTES> for more information.
384 return shift->related_resultset(shift)->search(@_);
391 =item Arguments: none
393 =item Return Value: $cursor
397 Returns a storage-driven cursor to the given resultset. See
398 L<DBIx::Class::Cursor> for more information.
404 my $attrs = { %{$self->{attrs}} };
405 return $self->{cursor}
406 ||= $self->result_source->storage->select($self->{from}, $attrs->{select},
407 $attrs->{where},$attrs);
414 =item Arguments: $cond?
416 =item Return Value: $row_object?
420 my $cd = $schema->resultset('CD')->single({ year => 2001 });
422 Inflates the first result without creating a cursor if the resultset has
423 any records in it; if not returns nothing. Used by find() as an optimisation.
428 my ($self, $where) = @_;
429 my $attrs = { %{$self->{attrs}} };
431 if (defined $attrs->{where}) {
434 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
435 $where, delete $attrs->{where} ]
438 $attrs->{where} = $where;
441 my @data = $self->result_source->storage->select_single(
442 $self->{from}, $attrs->{select},
443 $attrs->{where},$attrs);
444 return (@data ? $self->_construct_object(@data) : ());
451 =item Arguments: $cond?
453 =item Return Value: $resultsetcolumn
457 my $max_length = $rs->get_column('length')->max;
459 Returns a ResultSetColumn instance for $column based on $self
464 my ($self, $column) = @_;
466 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
474 =item Arguments: $cond, \%attrs?
476 =item Return Value: $resultset (scalar context), @row_objs (list context)
480 # WHERE title LIKE '%blue%'
481 $cd_rs = $rs->search_like({ title => '%blue%'});
483 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
484 that this is simply a convenience method. You most likely want to use
485 L</search> with specific operators.
487 For more information, see L<DBIx::Class::Manual::Cookbook>.
493 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
494 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
495 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
496 return $class->search($query, { %$attrs });
503 =item Arguments: $first, $last
505 =item Return Value: $resultset (scalar context), @row_objs (list context)
509 Returns a resultset or object list representing a subset of elements from the
510 resultset slice is called on. Indexes are from 0, i.e., to get the first
513 my ($one, $two, $three) = $rs->slice(0, 2);
518 my ($self, $min, $max) = @_;
519 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
520 $attrs->{offset} = $self->{attrs}{offset} || 0;
521 $attrs->{offset} += $min;
522 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
523 return $self->search(undef(), $attrs);
524 #my $slice = (ref $self)->new($self->result_source, $attrs);
525 #return (wantarray ? $slice->all : $slice);
532 =item Arguments: none
534 =item Return Value: $result?
538 Returns the next element in the resultset (C<undef> is there is none).
540 Can be used to efficiently iterate over records in the resultset:
542 my $rs = $schema->resultset('CD')->search;
543 while (my $cd = $rs->next) {
547 Note that you need to store the resultset object, and call C<next> on it.
548 Calling C<< resultset('Table')->next >> repeatedly will always return the
549 first record from the resultset.
555 if (@{$self->{all_cache} || []}) {
556 $self->{all_cache_position} ||= 0;
557 return $self->{all_cache}->[$self->{all_cache_position}++];
559 if ($self->{attrs}{cache}) {
560 $self->{all_cache_position} = 1;
561 return ($self->all)[0];
563 my @row = (exists $self->{stashed_row} ?
564 @{delete $self->{stashed_row}} :
567 # warn Dumper(\@row); use Data::Dumper;
568 return unless (@row);
569 return $self->_construct_object(@row);
572 sub _construct_object {
573 my ($self, @row) = @_;
574 my @as = @{ $self->{attrs}{as} };
576 my $info = $self->_collapse_result(\@as, \@row);
578 my $new = $self->result_class->inflate_result($self->result_source, @$info);
580 $new = $self->{attrs}{record_filter}->($new)
581 if exists $self->{attrs}{record_filter};
585 sub _collapse_result {
586 my ($self, $as, $row, $prefix) = @_;
591 foreach my $this_as (@$as) {
592 my $val = shift @copy;
593 if (defined $prefix) {
594 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
596 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
597 $const{$1||''}{$2} = $val;
600 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
601 $const{$1||''}{$2} = $val;
605 my $info = [ {}, {} ];
606 foreach my $key (keys %const) {
609 my @parts = split(/\./, $key);
610 foreach my $p (@parts) {
611 $target = $target->[1]->{$p} ||= [];
613 $target->[0] = $const{$key};
615 $info->[0] = $const{$key};
620 if (defined $prefix) {
622 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
623 } keys %{$self->{collapse}}
625 @collapse = keys %{$self->{collapse}};
629 my ($c) = sort { length $a <=> length $b } @collapse;
631 foreach my $p (split(/\./, $c)) {
632 $target = $target->[1]->{$p} ||= [];
634 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
635 my @co_key = @{$self->{collapse}{$c_prefix}};
636 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
637 my $tree = $self->_collapse_result($as, $row, $c_prefix);
640 !defined($tree->[0]->{$_}) ||
641 $co_check{$_} ne $tree->[0]->{$_}
644 last unless (@raw = $self->cursor->next);
645 $row = $self->{stashed_row} = \@raw;
646 $tree = $self->_collapse_result($as, $row, $c_prefix);
647 #warn Data::Dumper::Dumper($tree, $row);
659 =item Arguments: $result_source?
661 =item Return Value: $result_source
665 An accessor for the primary ResultSource object from which this ResultSet
675 =item Arguments: $cond, \%attrs??
677 =item Return Value: $count
681 Performs an SQL C<COUNT> with the same query as the resultset was built
682 with to find the number of elements. If passed arguments, does a search
683 on the resultset and counts the results of that.
685 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
686 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
687 not support C<DISTINCT> with multiple columns. If you are using such a
688 database, you should only use columns from the main table in your C<group_by>
695 return $self->search(@_)->count if @_ and defined $_[0];
696 return scalar @{ $self->get_cache } if @{ $self->get_cache };
698 my $count = $self->_count;
699 return 0 unless $count;
701 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
702 $count = $self->{attrs}{rows} if
703 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
707 sub _count { # Separated out so pager can get the full count
709 my $select = { count => '*' };
710 my $attrs = { %{ $self->{attrs} } };
711 if (my $group_by = delete $attrs->{group_by}) {
712 delete $attrs->{having};
713 my @distinct = (ref $group_by ? @$group_by : ($group_by));
714 # todo: try CONCAT for multi-column pk
715 my @pk = $self->result_source->primary_columns;
717 foreach my $column (@distinct) {
718 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
719 @distinct = ($column);
725 $select = { count => { distinct => \@distinct } };
726 #use Data::Dumper; die Dumper $select;
729 $attrs->{select} = $select;
730 $attrs->{as} = [qw/count/];
732 # offset, order by and page are not needed to count. record_filter is cdbi
733 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
735 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
743 =item Arguments: $sql_fragment, @bind_values
745 =item Return Value: $count
749 Counts the results in a literal query. Equivalent to calling L</search_literal>
750 with the passed arguments, then L</count>.
754 sub count_literal { shift->search_literal(@_)->count; }
760 =item Arguments: none
762 =item Return Value: @objects
766 Returns all elements in the resultset. Called implicitly if the resultset
767 is returned in list context.
773 return @{ $self->get_cache } if @{ $self->get_cache };
777 if (keys %{$self->{collapse}}) {
778 # Using $self->cursor->all is really just an optimisation.
779 # If we're collapsing has_many prefetches it probably makes
780 # very little difference, and this is cleaner than hacking
781 # _construct_object to survive the approach
782 $self->cursor->reset;
783 my @row = $self->cursor->next;
785 push(@obj, $self->_construct_object(@row));
786 @row = (exists $self->{stashed_row}
787 ? @{delete $self->{stashed_row}}
788 : $self->cursor->next);
791 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
794 $self->set_cache(\@obj) if $self->{attrs}{cache};
802 =item Arguments: none
804 =item Return Value: $self
808 Resets the resultset's cursor, so you can iterate through the elements again.
814 $self->{all_cache_position} = 0;
815 $self->cursor->reset;
823 =item Arguments: none
825 =item Return Value: $object?
829 Resets the resultset and returns an object for the first result (if the
830 resultset returns anything).
835 return $_[0]->reset->next;
838 # _cond_for_update_delete
840 # update/delete require the condition to be modified to handle
841 # the differing SQL syntax available. This transforms the $self->{cond}
842 # appropriately, returning the new condition.
844 sub _cond_for_update_delete {
848 if (!ref($self->{cond})) {
849 # No-op. No condition, we're updating/deleting everything
851 elsif (ref $self->{cond} eq 'ARRAY') {
855 foreach my $key (keys %{$_}) {
857 $hash{$1} = $_->{$key};
863 elsif (ref $self->{cond} eq 'HASH') {
864 if ((keys %{$self->{cond}})[0] eq '-and') {
867 my @cond = @{$self->{cond}{-and}};
868 for (my $i = 0; $i < @cond - 1; $i++) {
869 my $entry = $cond[$i];
872 if (ref $entry eq 'HASH') {
873 foreach my $key (keys %{$entry}) {
875 $hash{$1} = $entry->{$key};
879 $entry =~ /([^.]+)$/;
880 $hash{$entry} = $cond[++$i];
883 push @{$cond->{-and}}, \%hash;
887 foreach my $key (keys %{$self->{cond}}) {
889 $cond->{$1} = $self->{cond}{$key};
894 $self->throw_exception(
895 "Can't update/delete on resultset with condition unless hash or array"
907 =item Arguments: \%values
909 =item Return Value: $storage_rv
913 Sets the specified columns in the resultset to the supplied values in a
914 single query. Return value will be true if the update succeeded or false
915 if no records were updated; exact type of success value is storage-dependent.
920 my ($self, $values) = @_;
921 $self->throw_exception("Values for update must be a hash")
922 unless ref $values eq 'HASH';
924 my $cond = $self->_cond_for_update_delete;
926 return $self->result_source->storage->update(
927 $self->result_source->from, $values, $cond
935 =item Arguments: \%values
937 =item Return Value: 1
941 Fetches all objects and updates them one at a time. Note that C<update_all>
942 will run DBIC cascade triggers, while L</update> will not.
947 my ($self, $values) = @_;
948 $self->throw_exception("Values for update must be a hash")
949 unless ref $values eq 'HASH';
950 foreach my $obj ($self->all) {
951 $obj->set_columns($values)->update;
960 =item Arguments: none
962 =item Return Value: 1
966 Deletes the contents of the resultset from its result source. Note that this
967 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
976 my $cond = $self->_cond_for_update_delete;
978 $self->result_source->storage->delete($self->result_source->from, $cond);
986 =item Arguments: none
988 =item Return Value: 1
992 Fetches all objects and deletes them one at a time. Note that C<delete_all>
993 will run DBIC cascade triggers, while L</delete> will not.
999 $_->delete for $self->all;
1007 =item Arguments: none
1009 =item Return Value: $pager
1013 Return Value a L<Data::Page> object for the current resultset. Only makes
1014 sense for queries with a C<page> attribute.
1020 my $attrs = $self->{attrs};
1021 $self->throw_exception("Can't create pager for non-paged rs")
1022 unless $self->{page};
1023 $attrs->{rows} ||= 10;
1024 return $self->{pager} ||= Data::Page->new(
1025 $self->_count, $attrs->{rows}, $self->{page});
1032 =item Arguments: $page_number
1034 =item Return Value: $rs
1038 Returns a resultset for the $page_number page of the resultset on which page
1039 is called, where each page contains a number of rows equal to the 'rows'
1040 attribute set on the resultset (10 by default).
1045 my ($self, $page) = @_;
1046 my $attrs = { %{$self->{attrs}} };
1047 $attrs->{page} = $page;
1048 return (ref $self)->new($self->result_source, $attrs);
1055 =item Arguments: \%vals
1057 =item Return Value: $object
1061 Creates an object in the resultset's result class and returns it.
1066 my ($self, $values) = @_;
1067 $self->throw_exception( "new_result needs a hash" )
1068 unless (ref $values eq 'HASH');
1069 $self->throw_exception(
1070 "Can't abstract implicit construct, condition not a hash"
1071 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1073 my $alias = $self->{attrs}{alias};
1074 foreach my $key (keys %{$self->{cond}||{}}) {
1075 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1077 my $obj = $self->result_class->new(\%new);
1078 $obj->result_source($self->result_source) if $obj->can('result_source');
1086 =item Arguments: \%vals, \%attrs?
1088 =item Return Value: $object
1092 Find an existing record from this resultset. If none exists, instantiate a new
1093 result object and return it. The object will not be saved into your storage
1094 until you call L</DBIx::Class::Row/insert> on it.
1096 If you want objects to be saved immediately, use L</find_or_create> instead.
1102 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1103 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1104 my $exists = $self->find($hash, $attrs);
1105 return defined $exists ? $exists : $self->new_result($hash);
1112 =item Arguments: \%vals
1114 =item Return Value: $object
1118 Inserts a record into the resultset and returns the object representing it.
1120 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1125 my ($self, $attrs) = @_;
1126 $self->throw_exception( "create needs a hashref" )
1127 unless ref $attrs eq 'HASH';
1128 return $self->new_result($attrs)->insert;
1131 =head2 find_or_create
1135 =item Arguments: \%vals, \%attrs?
1137 =item Return Value: $object
1141 $class->find_or_create({ key => $val, ... });
1143 Searches for a record matching the search condition; if it doesn't find one,
1144 creates one and returns that instead.
1146 my $cd = $schema->resultset('CD')->find_or_create({
1148 artist => 'Massive Attack',
1149 title => 'Mezzanine',
1153 Also takes an optional C<key> attribute, to search by a specific key or unique
1154 constraint. For example:
1156 my $cd = $schema->resultset('CD')->find_or_create(
1158 artist => 'Massive Attack',
1159 title => 'Mezzanine',
1161 { key => 'artist_title' }
1164 See also L</find> and L</update_or_create>.
1168 sub find_or_create {
1170 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1171 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1172 my $exists = $self->find($hash, $attrs);
1173 return defined $exists ? $exists : $self->create($hash);
1176 =head2 update_or_create
1180 =item Arguments: \%col_values, { key => $unique_constraint }?
1182 =item Return Value: $object
1186 $class->update_or_create({ col => $val, ... });
1188 First, searches for an existing row matching one of the unique constraints
1189 (including the primary key) on the source of this resultset. If a row is
1190 found, updates it with the other given column values. Otherwise, creates a new
1193 Takes an optional C<key> attribute to search on a specific unique constraint.
1196 # In your application
1197 my $cd = $schema->resultset('CD')->update_or_create(
1199 artist => 'Massive Attack',
1200 title => 'Mezzanine',
1203 { key => 'artist_title' }
1206 If no C<key> is specified, it searches on all unique constraints defined on the
1207 source, including the primary key.
1209 If the C<key> is specified as C<primary>, it searches only on the primary key.
1211 See also L</find> and L</find_or_create>.
1215 sub update_or_create {
1217 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1218 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1220 my $row = $self->find($hash, $attrs);
1222 $row->set_columns($hash);
1227 return $self->create($hash);
1234 =item Arguments: none
1236 =item Return Value: \@cache_objects?
1240 Gets the contents of the cache for the resultset, if the cache is set.
1245 shift->{all_cache} || [];
1252 =item Arguments: \@cache_objects
1254 =item Return Value: \@cache_objects
1258 Sets the contents of the cache for the resultset. Expects an arrayref
1259 of objects of the same class as those produced by the resultset. Note that
1260 if the cache is set the resultset will return the cached objects rather
1261 than re-querying the database even if the cache attr is not set.
1266 my ( $self, $data ) = @_;
1267 $self->throw_exception("set_cache requires an arrayref")
1268 if ref $data ne 'ARRAY';
1269 my $result_class = $self->result_class;
1271 $self->throw_exception(
1272 "cannot cache object of type '$_', expected '$result_class'"
1273 ) if ref $_ ne $result_class;
1275 $self->{all_cache} = $data;
1282 =item Arguments: none
1284 =item Return Value: []
1288 Clears the cache for the resultset.
1293 shift->set_cache([]);
1296 =head2 related_resultset
1300 =item Arguments: $relationship_name
1302 =item Return Value: $resultset
1306 Returns a related resultset for the supplied relationship name.
1308 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1312 sub related_resultset {
1313 my ( $self, $rel ) = @_;
1314 $self->{related_resultsets} ||= {};
1315 return $self->{related_resultsets}{$rel} ||= do {
1316 #warn "fetching related resultset for rel '$rel'";
1317 my $rel_obj = $self->result_source->relationship_info($rel);
1318 $self->throw_exception(
1319 "search_related: result source '" . $self->result_source->name .
1320 "' has no such relationship ${rel}")
1321 unless $rel_obj; #die Dumper $self->{attrs};
1323 my $rs = $self->search(undef, { join => $rel });
1324 my $alias = defined $rs->{attrs}{seen_join}{$rel}
1325 && $rs->{attrs}{seen_join}{$rel} > 1
1326 ? join('_', $rel, $rs->{attrs}{seen_join}{$rel})
1329 $self->result_source->schema->resultset($rel_obj->{class}
1339 =head2 throw_exception
1341 See L<DBIx::Class::Schema/throw_exception> for details.
1345 sub throw_exception {
1347 $self->result_source->schema->throw_exception(@_);
1350 # XXX: FIXME: Attributes docs need clearing up
1354 The resultset takes various attributes that modify its behavior. Here's an
1361 =item Value: ($order_by | \@order_by)
1365 Which column(s) to order the results by. This is currently passed
1366 through directly to SQL, so you can give e.g. C<year DESC> for a
1367 descending order on the column `year'.
1373 =item Value: \@columns
1377 Shortcut to request a particular set of columns to be retrieved. Adds
1378 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1379 from that, then auto-populates C<as> from C<select> as normal. (You may also
1380 use the C<cols> attribute, as in earlier versions of DBIC.)
1382 =head2 include_columns
1386 =item Value: \@columns
1390 Shortcut to include additional columns in the returned results - for example
1392 $schema->resultset('CD')->search(undef, {
1393 include_columns => ['artist.name'],
1397 would return all CDs and include a 'name' column to the information
1398 passed to object inflation
1404 =item Value: \@select_columns
1408 Indicates which columns should be selected from the storage. You can use
1409 column names, or in the case of RDBMS back ends, function or stored procedure
1412 $rs = $schema->resultset('Employee')->search(undef, {
1415 { count => 'employeeid' },
1420 When you use function/stored procedure names and do not supply an C<as>
1421 attribute, the column names returned are storage-dependent. E.g. MySQL would
1422 return a column named C<count(employeeid)> in the above example.
1428 =item Value: \@inflation_names
1432 Indicates column names for object inflation. This is used in conjunction with
1433 C<select>, usually when C<select> contains one or more function or stored
1436 $rs = $schema->resultset('Employee')->search(undef, {
1439 { count => 'employeeid' }
1441 as => ['name', 'employee_count'],
1444 my $employee = $rs->first(); # get the first Employee
1446 If the object against which the search is performed already has an accessor
1447 matching a column name specified in C<as>, the value can be retrieved using
1448 the accessor as normal:
1450 my $name = $employee->name();
1452 If on the other hand an accessor does not exist in the object, you need to
1453 use C<get_column> instead:
1455 my $employee_count = $employee->get_column('employee_count');
1457 You can create your own accessors if required - see
1458 L<DBIx::Class::Manual::Cookbook> for details.
1464 =item Value: ($rel_name | \@rel_names | \%rel_names)
1468 Contains a list of relationships that should be joined for this query. For
1471 # Get CDs by Nine Inch Nails
1472 my $rs = $schema->resultset('CD')->search(
1473 { 'artist.name' => 'Nine Inch Nails' },
1474 { join => 'artist' }
1477 Can also contain a hash reference to refer to the other relation's relations.
1480 package MyApp::Schema::Track;
1481 use base qw/DBIx::Class/;
1482 __PACKAGE__->table('track');
1483 __PACKAGE__->add_columns(qw/trackid cd position title/);
1484 __PACKAGE__->set_primary_key('trackid');
1485 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1488 # In your application
1489 my $rs = $schema->resultset('Artist')->search(
1490 { 'track.title' => 'Teardrop' },
1492 join => { cd => 'track' },
1493 order_by => 'artist.name',
1497 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1498 similarly for a third time). For e.g.
1500 my $rs = $schema->resultset('Artist')->search({
1501 'cds.title' => 'Down to Earth',
1502 'cds_2.title' => 'Popular',
1504 join => [ qw/cds cds/ ],
1507 will return a set of all artists that have both a cd with title 'Down
1508 to Earth' and a cd with title 'Popular'.
1510 If you want to fetch related objects from other tables as well, see C<prefetch>
1517 =item Value: ($rel_name | \@rel_names | \%rel_names)
1521 Contains one or more relationships that should be fetched along with the main
1522 query (when they are accessed afterwards they will have already been
1523 "prefetched"). This is useful for when you know you will need the related
1524 objects, because it saves at least one query:
1526 my $rs = $schema->resultset('Tag')->search(
1535 The initial search results in SQL like the following:
1537 SELECT tag.*, cd.*, artist.* FROM tag
1538 JOIN cd ON tag.cd = cd.cdid
1539 JOIN artist ON cd.artist = artist.artistid
1541 L<DBIx::Class> has no need to go back to the database when we access the
1542 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1545 Simple prefetches will be joined automatically, so there is no need
1546 for a C<join> attribute in the above search. If you're prefetching to
1547 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1548 specify the join as well.
1550 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1551 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1552 with an accessor type of 'single' or 'filter').
1558 =item Value: \@from_clause
1562 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1563 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1566 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1567 C<join> will usually do what you need and it is strongly recommended that you
1568 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1570 In simple terms, C<from> works as follows:
1573 { <alias> => <table>, -join_type => 'inner|left|right' }
1574 [] # nested JOIN (optional)
1575 { <table.column> => <foreign_table.foreign_key> }
1581 ON <table.column> = <foreign_table.foreign_key>
1583 An easy way to follow the examples below is to remember the following:
1585 Anything inside "[]" is a JOIN
1586 Anything inside "{}" is a condition for the enclosing JOIN
1588 The following examples utilize a "person" table in a family tree application.
1589 In order to express parent->child relationships, this table is self-joined:
1591 # Person->belongs_to('father' => 'Person');
1592 # Person->belongs_to('mother' => 'Person');
1594 C<from> can be used to nest joins. Here we return all children with a father,
1595 then search against all mothers of those children:
1597 $rs = $schema->resultset('Person')->search(
1600 alias => 'mother', # alias columns in accordance with "from"
1602 { mother => 'person' },
1605 { child => 'person' },
1607 { father => 'person' },
1608 { 'father.person_id' => 'child.father_id' }
1611 { 'mother.person_id' => 'child.mother_id' }
1618 # SELECT mother.* FROM person mother
1621 # JOIN person father
1622 # ON ( father.person_id = child.father_id )
1624 # ON ( mother.person_id = child.mother_id )
1626 The type of any join can be controlled manually. To search against only people
1627 with a father in the person table, we could explicitly use C<INNER JOIN>:
1629 $rs = $schema->resultset('Person')->search(
1632 alias => 'child', # alias columns in accordance with "from"
1634 { child => 'person' },
1636 { father => 'person', -join_type => 'inner' },
1637 { 'father.id' => 'child.father_id' }
1644 # SELECT child.* FROM person child
1645 # INNER JOIN person father ON child.father_id = father.id
1655 Makes the resultset paged and specifies the page to retrieve. Effectively
1656 identical to creating a non-pages resultset and then calling ->page($page)
1667 Specifes the maximum number of rows for direct retrieval or the number of
1668 rows per page if the page attribute or method is used.
1674 =item Value: \@columns
1678 A arrayref of columns to group by. Can include columns of joined tables.
1680 group_by => [qw/ column1 column2 ... /]
1686 =item Value: $condition
1690 HAVING is a select statement attribute that is applied between GROUP BY and
1691 ORDER BY. It is applied to the after the grouping calculations have been
1694 having => { 'count(employee)' => { '>=', 100 } }
1700 =item Value: (0 | 1)
1704 Set to 1 to group by all columns.
1708 Set to 1 to cache search results. This prevents extra SQL queries if you
1709 revisit rows in your ResultSet:
1711 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1713 while( my $artist = $resultset->next ) {
1717 $rs->first; # without cache, this would issue a query
1719 By default, searches are not cached.
1721 For more examples of using these attributes, see
1722 L<DBIx::Class::Manual::Cookbook>.