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 See also L</find_or_create> and L</update_or_create>.
295 my ($self, @vals) = @_;
296 my $attrs = (@vals > 1 && ref $vals[$#vals] eq 'HASH' ? pop(@vals) : {});
298 my %unique_constraints = $self->result_source->unique_constraints;
299 $self->throw_exception(
300 "Can't find unless a primary key or unique constraint is defined"
301 ) unless %unique_constraints;
303 my @constraint_names = keys %unique_constraints;
304 if (exists $attrs->{key}) {
305 $self->throw_exception(
306 "Unknown key $attrs->{key} on '" . $self->result_source->name . "'"
307 ) unless exists $unique_constraints{$attrs->{key}};
309 @constraint_names = ($attrs->{key});
313 foreach my $name (@constraint_names) {
314 my @unique_cols = @{ $unique_constraints{$name} };
316 if (ref $vals[0] eq 'HASH') {
317 # Stupid hack for CDBICompat
318 my %hash = %{ $vals[0] };
319 foreach my $key (keys %hash) {
320 $hash{lc $key} = delete $hash{$key};
324 map { $_ => $hash{$_} }
325 grep { exists $hash{$_} }
328 elsif (@unique_cols == @vals) {
329 # Assume the argument order corresponds to the constraint definition
330 @unique_hash{@unique_cols} = @vals;
332 elsif (@vals % 2 == 0) {
333 # Fix for CDBI calling with a hash
334 %unique_hash = @vals;
337 foreach my $key (grep { ! m/\./ } keys %unique_hash) {
338 $unique_hash{"$self->{attrs}{alias}.$key"} = delete $unique_hash{$key};
341 #use Data::Dumper; warn Dumper \@vals, \@unique_cols, \%unique_hash;
342 push @unique_hashes, \%unique_hash if %unique_hash;
345 # Handle cases where the ResultSet already defines the query
346 my $query = @unique_hashes ? \@unique_hashes : undef;
349 my $rs = $self->search($query, $attrs);
350 return keys %{$rs->{collapse}} ? $rs->next : $rs->single;
353 return keys %{$self->{collapse}}
354 ? $self->search($query)->next
355 : $self->single($query);
359 =head2 search_related
363 =item Arguments: $cond, \%attrs?
365 =item Return Value: $new_resultset
369 $new_rs = $cd_rs->search_related('artist', {
373 Searches the specified relationship, optionally specifying a condition and
374 attributes for matching records. See L</ATTRIBUTES> for more information.
379 return shift->related_resultset(shift)->search(@_);
386 =item Arguments: none
388 =item Return Value: $cursor
392 Returns a storage-driven cursor to the given resultset. See
393 L<DBIx::Class::Cursor> for more information.
399 my $attrs = { %{$self->{attrs}} };
400 return $self->{cursor}
401 ||= $self->result_source->storage->select($self->{from}, $attrs->{select},
402 $attrs->{where},$attrs);
409 =item Arguments: $cond?
411 =item Return Value: $row_object?
415 my $cd = $schema->resultset('CD')->single({ year => 2001 });
417 Inflates the first result without creating a cursor if the resultset has
418 any records in it; if not returns nothing. Used by find() as an optimisation.
423 my ($self, $where) = @_;
424 my $attrs = { %{$self->{attrs}} };
426 if (defined $attrs->{where}) {
429 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
430 $where, delete $attrs->{where} ]
433 $attrs->{where} = $where;
436 my @data = $self->result_source->storage->select_single(
437 $self->{from}, $attrs->{select},
438 $attrs->{where},$attrs);
439 return (@data ? $self->_construct_object(@data) : ());
446 =item Arguments: $cond?
448 =item Return Value: $resultsetcolumn
452 my $max_length = $rs->get_column('length')->max;
454 Returns a ResultSetColumn instance for $column based on $self
459 my ($self, $column) = @_;
461 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
469 =item Arguments: $cond, \%attrs?
471 =item Return Value: $resultset (scalar context), @row_objs (list context)
475 # WHERE title LIKE '%blue%'
476 $cd_rs = $rs->search_like({ title => '%blue%'});
478 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
479 that this is simply a convenience method. You most likely want to use
480 L</search> with specific operators.
482 For more information, see L<DBIx::Class::Manual::Cookbook>.
488 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
489 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
490 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
491 return $class->search($query, { %$attrs });
498 =item Arguments: $first, $last
500 =item Return Value: $resultset (scalar context), @row_objs (list context)
504 Returns a resultset or object list representing a subset of elements from the
505 resultset slice is called on. Indexes are from 0, i.e., to get the first
508 my ($one, $two, $three) = $rs->slice(0, 2);
513 my ($self, $min, $max) = @_;
514 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
515 $attrs->{offset} = $self->{attrs}{offset} || 0;
516 $attrs->{offset} += $min;
517 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
518 return $self->search(undef(), $attrs);
519 #my $slice = (ref $self)->new($self->result_source, $attrs);
520 #return (wantarray ? $slice->all : $slice);
527 =item Arguments: none
529 =item Return Value: $result?
533 Returns the next element in the resultset (C<undef> is there is none).
535 Can be used to efficiently iterate over records in the resultset:
537 my $rs = $schema->resultset('CD')->search;
538 while (my $cd = $rs->next) {
542 Note that you need to store the resultset object, and call C<next> on it.
543 Calling C<< resultset('Table')->next >> repeatedly will always return the
544 first record from the resultset.
550 if (@{$self->{all_cache} || []}) {
551 $self->{all_cache_position} ||= 0;
552 return $self->{all_cache}->[$self->{all_cache_position}++];
554 if ($self->{attrs}{cache}) {
555 $self->{all_cache_position} = 1;
556 return ($self->all)[0];
558 my @row = (exists $self->{stashed_row} ?
559 @{delete $self->{stashed_row}} :
562 # warn Dumper(\@row); use Data::Dumper;
563 return unless (@row);
564 return $self->_construct_object(@row);
567 sub _construct_object {
568 my ($self, @row) = @_;
569 my @as = @{ $self->{attrs}{as} };
571 my $info = $self->_collapse_result(\@as, \@row);
573 my $new = $self->result_class->inflate_result($self->result_source, @$info);
575 $new = $self->{attrs}{record_filter}->($new)
576 if exists $self->{attrs}{record_filter};
580 sub _collapse_result {
581 my ($self, $as, $row, $prefix) = @_;
586 foreach my $this_as (@$as) {
587 my $val = shift @copy;
588 if (defined $prefix) {
589 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
591 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
592 $const{$1||''}{$2} = $val;
595 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
596 $const{$1||''}{$2} = $val;
600 my $info = [ {}, {} ];
601 foreach my $key (keys %const) {
604 my @parts = split(/\./, $key);
605 foreach my $p (@parts) {
606 $target = $target->[1]->{$p} ||= [];
608 $target->[0] = $const{$key};
610 $info->[0] = $const{$key};
615 if (defined $prefix) {
617 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
618 } keys %{$self->{collapse}}
620 @collapse = keys %{$self->{collapse}};
624 my ($c) = sort { length $a <=> length $b } @collapse;
626 foreach my $p (split(/\./, $c)) {
627 $target = $target->[1]->{$p} ||= [];
629 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
630 my @co_key = @{$self->{collapse}{$c_prefix}};
631 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
632 my $tree = $self->_collapse_result($as, $row, $c_prefix);
635 !defined($tree->[0]->{$_}) ||
636 $co_check{$_} ne $tree->[0]->{$_}
639 last unless (@raw = $self->cursor->next);
640 $row = $self->{stashed_row} = \@raw;
641 $tree = $self->_collapse_result($as, $row, $c_prefix);
642 #warn Data::Dumper::Dumper($tree, $row);
654 =item Arguments: $result_source?
656 =item Return Value: $result_source
660 An accessor for the primary ResultSource object from which this ResultSet
670 =item Arguments: $cond, \%attrs??
672 =item Return Value: $count
676 Performs an SQL C<COUNT> with the same query as the resultset was built
677 with to find the number of elements. If passed arguments, does a search
678 on the resultset and counts the results of that.
680 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
681 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
682 not support C<DISTINCT> with multiple columns. If you are using such a
683 database, you should only use columns from the main table in your C<group_by>
690 return $self->search(@_)->count if @_ and defined $_[0];
691 return scalar @{ $self->get_cache } if @{ $self->get_cache };
693 my $count = $self->_count;
694 return 0 unless $count;
696 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
697 $count = $self->{attrs}{rows} if
698 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
702 sub _count { # Separated out so pager can get the full count
704 my $select = { count => '*' };
705 my $attrs = { %{ $self->{attrs} } };
706 if (my $group_by = delete $attrs->{group_by}) {
707 delete $attrs->{having};
708 my @distinct = (ref $group_by ? @$group_by : ($group_by));
709 # todo: try CONCAT for multi-column pk
710 my @pk = $self->result_source->primary_columns;
712 foreach my $column (@distinct) {
713 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
714 @distinct = ($column);
720 $select = { count => { distinct => \@distinct } };
721 #use Data::Dumper; die Dumper $select;
724 $attrs->{select} = $select;
725 $attrs->{as} = [qw/count/];
727 # offset, order by and page are not needed to count. record_filter is cdbi
728 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
730 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
738 =item Arguments: $sql_fragment, @bind_values
740 =item Return Value: $count
744 Counts the results in a literal query. Equivalent to calling L</search_literal>
745 with the passed arguments, then L</count>.
749 sub count_literal { shift->search_literal(@_)->count; }
755 =item Arguments: none
757 =item Return Value: @objects
761 Returns all elements in the resultset. Called implicitly if the resultset
762 is returned in list context.
768 return @{ $self->get_cache } if @{ $self->get_cache };
772 if (keys %{$self->{collapse}}) {
773 # Using $self->cursor->all is really just an optimisation.
774 # If we're collapsing has_many prefetches it probably makes
775 # very little difference, and this is cleaner than hacking
776 # _construct_object to survive the approach
777 $self->cursor->reset;
778 my @row = $self->cursor->next;
780 push(@obj, $self->_construct_object(@row));
781 @row = (exists $self->{stashed_row}
782 ? @{delete $self->{stashed_row}}
783 : $self->cursor->next);
786 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
789 $self->set_cache(\@obj) if $self->{attrs}{cache};
797 =item Arguments: none
799 =item Return Value: $self
803 Resets the resultset's cursor, so you can iterate through the elements again.
809 $self->{all_cache_position} = 0;
810 $self->cursor->reset;
818 =item Arguments: none
820 =item Return Value: $object?
824 Resets the resultset and returns an object for the first result (if the
825 resultset returns anything).
830 return $_[0]->reset->next;
833 # _cond_for_update_delete
835 # update/delete require the condition to be modified to handle
836 # the differing SQL syntax available. This transforms the $self->{cond}
837 # appropriately, returning the new condition.
839 sub _cond_for_update_delete {
843 if (!ref($self->{cond})) {
844 # No-op. No condition, we're updating/deleting everything
846 elsif (ref $self->{cond} eq 'ARRAY') {
850 foreach my $key (keys %{$_}) {
852 $hash{$1} = $_->{$key};
858 elsif (ref $self->{cond} eq 'HASH') {
859 if ((keys %{$self->{cond}})[0] eq '-and') {
862 my @cond = @{$self->{cond}{-and}};
863 for (my $i = 0; $i < @cond - 1; $i++) {
864 my $entry = $cond[$i];
867 if (ref $entry eq 'HASH') {
868 foreach my $key (keys %{$entry}) {
870 $hash{$1} = $entry->{$key};
874 $entry =~ /([^.]+)$/;
875 $hash{$entry} = $cond[++$i];
878 push @{$cond->{-and}}, \%hash;
882 foreach my $key (keys %{$self->{cond}}) {
884 $cond->{$1} = $self->{cond}{$key};
889 $self->throw_exception(
890 "Can't update/delete on resultset with condition unless hash or array"
902 =item Arguments: \%values
904 =item Return Value: $storage_rv
908 Sets the specified columns in the resultset to the supplied values in a
909 single query. Return value will be true if the update succeeded or false
910 if no records were updated; exact type of success value is storage-dependent.
915 my ($self, $values) = @_;
916 $self->throw_exception("Values for update must be a hash")
917 unless ref $values eq 'HASH';
919 my $cond = $self->_cond_for_update_delete;
921 return $self->result_source->storage->update(
922 $self->result_source->from, $values, $cond
930 =item Arguments: \%values
932 =item Return Value: 1
936 Fetches all objects and updates them one at a time. Note that C<update_all>
937 will run DBIC cascade triggers, while L</update> will not.
942 my ($self, $values) = @_;
943 $self->throw_exception("Values for update must be a hash")
944 unless ref $values eq 'HASH';
945 foreach my $obj ($self->all) {
946 $obj->set_columns($values)->update;
955 =item Arguments: none
957 =item Return Value: 1
961 Deletes the contents of the resultset from its result source. Note that this
962 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
971 my $cond = $self->_cond_for_update_delete;
973 $self->result_source->storage->delete($self->result_source->from, $cond);
981 =item Arguments: none
983 =item Return Value: 1
987 Fetches all objects and deletes them one at a time. Note that C<delete_all>
988 will run DBIC cascade triggers, while L</delete> will not.
994 $_->delete for $self->all;
1002 =item Arguments: none
1004 =item Return Value: $pager
1008 Return Value a L<Data::Page> object for the current resultset. Only makes
1009 sense for queries with a C<page> attribute.
1015 my $attrs = $self->{attrs};
1016 $self->throw_exception("Can't create pager for non-paged rs")
1017 unless $self->{page};
1018 $attrs->{rows} ||= 10;
1019 return $self->{pager} ||= Data::Page->new(
1020 $self->_count, $attrs->{rows}, $self->{page});
1027 =item Arguments: $page_number
1029 =item Return Value: $rs
1033 Returns a resultset for the $page_number page of the resultset on which page
1034 is called, where each page contains a number of rows equal to the 'rows'
1035 attribute set on the resultset (10 by default).
1040 my ($self, $page) = @_;
1041 my $attrs = { %{$self->{attrs}} };
1042 $attrs->{page} = $page;
1043 return (ref $self)->new($self->result_source, $attrs);
1050 =item Arguments: \%vals
1052 =item Return Value: $object
1056 Creates an object in the resultset's result class and returns it.
1061 my ($self, $values) = @_;
1062 $self->throw_exception( "new_result needs a hash" )
1063 unless (ref $values eq 'HASH');
1064 $self->throw_exception(
1065 "Can't abstract implicit construct, condition not a hash"
1066 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1068 my $alias = $self->{attrs}{alias};
1069 foreach my $key (keys %{$self->{cond}||{}}) {
1070 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1072 my $obj = $self->result_class->new(\%new);
1073 $obj->result_source($self->result_source) if $obj->can('result_source');
1081 =item Arguments: \%vals
1083 =item Return Value: $object
1087 Inserts a record into the resultset and returns the object representing it.
1089 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1094 my ($self, $attrs) = @_;
1095 $self->throw_exception( "create needs a hashref" )
1096 unless ref $attrs eq 'HASH';
1097 return $self->new_result($attrs)->insert;
1100 =head2 find_or_create
1104 =item Arguments: \%vals, \%attrs?
1106 =item Return Value: $object
1110 $class->find_or_create({ key => $val, ... });
1112 Searches for a record matching the search condition; if it doesn't find one,
1113 creates one and returns that instead.
1115 my $cd = $schema->resultset('CD')->find_or_create({
1117 artist => 'Massive Attack',
1118 title => 'Mezzanine',
1122 Also takes an optional C<key> attribute, to search by a specific key or unique
1123 constraint. For example:
1125 my $cd = $schema->resultset('CD')->find_or_create(
1127 artist => 'Massive Attack',
1128 title => 'Mezzanine',
1130 { key => 'artist_title' }
1133 See also L</find> and L</update_or_create>.
1137 sub find_or_create {
1139 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1140 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1141 my $exists = $self->find($hash, $attrs);
1142 return defined $exists ? $exists : $self->create($hash);
1145 =head2 update_or_create
1149 =item Arguments: \%col_values, { key => $unique_constraint }?
1151 =item Return Value: $object
1155 $class->update_or_create({ col => $val, ... });
1157 First, searches for an existing row matching one of the unique constraints
1158 (including the primary key) on the source of this resultset. If a row is
1159 found, updates it with the other given column values. Otherwise, creates a new
1162 Takes an optional C<key> attribute to search on a specific unique constraint.
1165 # In your application
1166 my $cd = $schema->resultset('CD')->update_or_create(
1168 artist => 'Massive Attack',
1169 title => 'Mezzanine',
1172 { key => 'artist_title' }
1175 If no C<key> is specified, it searches on all unique constraints defined on the
1176 source, including the primary key.
1178 If the C<key> is specified as C<primary>, it searches only on the primary key.
1180 See also L</find> and L</find_or_create>.
1184 sub update_or_create {
1186 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1187 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1189 my $row = $self->find($hash, $attrs);
1191 $row->set_columns($hash);
1196 return $self->create($hash);
1203 =item Arguments: none
1205 =item Return Value: \@cache_objects?
1209 Gets the contents of the cache for the resultset, if the cache is set.
1214 shift->{all_cache} || [];
1221 =item Arguments: \@cache_objects
1223 =item Return Value: \@cache_objects
1227 Sets the contents of the cache for the resultset. Expects an arrayref
1228 of objects of the same class as those produced by the resultset. Note that
1229 if the cache is set the resultset will return the cached objects rather
1230 than re-querying the database even if the cache attr is not set.
1235 my ( $self, $data ) = @_;
1236 $self->throw_exception("set_cache requires an arrayref")
1237 if ref $data ne 'ARRAY';
1238 my $result_class = $self->result_class;
1240 $self->throw_exception(
1241 "cannot cache object of type '$_', expected '$result_class'"
1242 ) if ref $_ ne $result_class;
1244 $self->{all_cache} = $data;
1251 =item Arguments: none
1253 =item Return Value: []
1257 Clears the cache for the resultset.
1262 shift->set_cache([]);
1265 =head2 related_resultset
1269 =item Arguments: $relationship_name
1271 =item Return Value: $resultset
1275 Returns a related resultset for the supplied relationship name.
1277 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1281 sub related_resultset {
1282 my ( $self, $rel ) = @_;
1283 $self->{related_resultsets} ||= {};
1284 return $self->{related_resultsets}{$rel} ||= do {
1285 #warn "fetching related resultset for rel '$rel'";
1286 my $rel_obj = $self->result_source->relationship_info($rel);
1287 $self->throw_exception(
1288 "search_related: result source '" . $self->result_source->name .
1289 "' has no such relationship ${rel}")
1290 unless $rel_obj; #die Dumper $self->{attrs};
1292 my $rs = $self->search(undef, { join => $rel });
1293 my $alias = defined $rs->{attrs}{seen_join}{$rel}
1294 && $rs->{attrs}{seen_join}{$rel} > 1
1295 ? join('_', $rel, $rs->{attrs}{seen_join}{$rel})
1298 $self->result_source->schema->resultset($rel_obj->{class}
1308 =head2 throw_exception
1310 See L<DBIx::Class::Schema/throw_exception> for details.
1314 sub throw_exception {
1316 $self->result_source->schema->throw_exception(@_);
1319 # XXX: FIXME: Attributes docs need clearing up
1323 The resultset takes various attributes that modify its behavior. Here's an
1330 =item Value: ($order_by | \@order_by)
1334 Which column(s) to order the results by. This is currently passed
1335 through directly to SQL, so you can give e.g. C<year DESC> for a
1336 descending order on the column `year'.
1342 =item Value: \@columns
1346 Shortcut to request a particular set of columns to be retrieved. Adds
1347 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1348 from that, then auto-populates C<as> from C<select> as normal. (You may also
1349 use the C<cols> attribute, as in earlier versions of DBIC.)
1351 =head2 include_columns
1355 =item Value: \@columns
1359 Shortcut to include additional columns in the returned results - for example
1361 $schema->resultset('CD')->search(undef, {
1362 include_columns => ['artist.name'],
1366 would return all CDs and include a 'name' column to the information
1367 passed to object inflation
1373 =item Value: \@select_columns
1377 Indicates which columns should be selected from the storage. You can use
1378 column names, or in the case of RDBMS back ends, function or stored procedure
1381 $rs = $schema->resultset('Employee')->search(undef, {
1384 { count => 'employeeid' },
1389 When you use function/stored procedure names and do not supply an C<as>
1390 attribute, the column names returned are storage-dependent. E.g. MySQL would
1391 return a column named C<count(employeeid)> in the above example.
1397 =item Value: \@inflation_names
1401 Indicates column names for object inflation. This is used in conjunction with
1402 C<select>, usually when C<select> contains one or more function or stored
1405 $rs = $schema->resultset('Employee')->search(undef, {
1408 { count => 'employeeid' }
1410 as => ['name', 'employee_count'],
1413 my $employee = $rs->first(); # get the first Employee
1415 If the object against which the search is performed already has an accessor
1416 matching a column name specified in C<as>, the value can be retrieved using
1417 the accessor as normal:
1419 my $name = $employee->name();
1421 If on the other hand an accessor does not exist in the object, you need to
1422 use C<get_column> instead:
1424 my $employee_count = $employee->get_column('employee_count');
1426 You can create your own accessors if required - see
1427 L<DBIx::Class::Manual::Cookbook> for details.
1433 =item Value: ($rel_name | \@rel_names | \%rel_names)
1437 Contains a list of relationships that should be joined for this query. For
1440 # Get CDs by Nine Inch Nails
1441 my $rs = $schema->resultset('CD')->search(
1442 { 'artist.name' => 'Nine Inch Nails' },
1443 { join => 'artist' }
1446 Can also contain a hash reference to refer to the other relation's relations.
1449 package MyApp::Schema::Track;
1450 use base qw/DBIx::Class/;
1451 __PACKAGE__->table('track');
1452 __PACKAGE__->add_columns(qw/trackid cd position title/);
1453 __PACKAGE__->set_primary_key('trackid');
1454 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1457 # In your application
1458 my $rs = $schema->resultset('Artist')->search(
1459 { 'track.title' => 'Teardrop' },
1461 join => { cd => 'track' },
1462 order_by => 'artist.name',
1466 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1467 similarly for a third time). For e.g.
1469 my $rs = $schema->resultset('Artist')->search({
1470 'cds.title' => 'Down to Earth',
1471 'cds_2.title' => 'Popular',
1473 join => [ qw/cds cds/ ],
1476 will return a set of all artists that have both a cd with title 'Down
1477 to Earth' and a cd with title 'Popular'.
1479 If you want to fetch related objects from other tables as well, see C<prefetch>
1486 =item Value: ($rel_name | \@rel_names | \%rel_names)
1490 Contains one or more relationships that should be fetched along with the main
1491 query (when they are accessed afterwards they will have already been
1492 "prefetched"). This is useful for when you know you will need the related
1493 objects, because it saves at least one query:
1495 my $rs = $schema->resultset('Tag')->search(
1504 The initial search results in SQL like the following:
1506 SELECT tag.*, cd.*, artist.* FROM tag
1507 JOIN cd ON tag.cd = cd.cdid
1508 JOIN artist ON cd.artist = artist.artistid
1510 L<DBIx::Class> has no need to go back to the database when we access the
1511 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1514 Simple prefetches will be joined automatically, so there is no need
1515 for a C<join> attribute in the above search. If you're prefetching to
1516 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1517 specify the join as well.
1519 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1520 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1521 with an accessor type of 'single' or 'filter').
1527 =item Value: \@from_clause
1531 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1532 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1535 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1536 C<join> will usually do what you need and it is strongly recommended that you
1537 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1539 In simple terms, C<from> works as follows:
1542 { <alias> => <table>, -join_type => 'inner|left|right' }
1543 [] # nested JOIN (optional)
1544 { <table.column> => <foreign_table.foreign_key> }
1550 ON <table.column> = <foreign_table.foreign_key>
1552 An easy way to follow the examples below is to remember the following:
1554 Anything inside "[]" is a JOIN
1555 Anything inside "{}" is a condition for the enclosing JOIN
1557 The following examples utilize a "person" table in a family tree application.
1558 In order to express parent->child relationships, this table is self-joined:
1560 # Person->belongs_to('father' => 'Person');
1561 # Person->belongs_to('mother' => 'Person');
1563 C<from> can be used to nest joins. Here we return all children with a father,
1564 then search against all mothers of those children:
1566 $rs = $schema->resultset('Person')->search(
1569 alias => 'mother', # alias columns in accordance with "from"
1571 { mother => 'person' },
1574 { child => 'person' },
1576 { father => 'person' },
1577 { 'father.person_id' => 'child.father_id' }
1580 { 'mother.person_id' => 'child.mother_id' }
1587 # SELECT mother.* FROM person mother
1590 # JOIN person father
1591 # ON ( father.person_id = child.father_id )
1593 # ON ( mother.person_id = child.mother_id )
1595 The type of any join can be controlled manually. To search against only people
1596 with a father in the person table, we could explicitly use C<INNER JOIN>:
1598 $rs = $schema->resultset('Person')->search(
1601 alias => 'child', # alias columns in accordance with "from"
1603 { child => 'person' },
1605 { father => 'person', -join_type => 'inner' },
1606 { 'father.id' => 'child.father_id' }
1613 # SELECT child.* FROM person child
1614 # INNER JOIN person father ON child.father_id = father.id
1624 Makes the resultset paged and specifies the page to retrieve. Effectively
1625 identical to creating a non-pages resultset and then calling ->page($page)
1636 Specifes the maximum number of rows for direct retrieval or the number of
1637 rows per page if the page attribute or method is used.
1643 =item Value: \@columns
1647 A arrayref of columns to group by. Can include columns of joined tables.
1649 group_by => [qw/ column1 column2 ... /]
1655 =item Value: $condition
1659 HAVING is a select statement attribute that is applied between GROUP BY and
1660 ORDER BY. It is applied to the after the grouping calculations have been
1663 having => { 'count(employee)' => { '>=', 100 } }
1669 =item Value: (0 | 1)
1673 Set to 1 to group by all columns.
1677 Set to 1 to cache search results. This prevents extra SQL queries if you
1678 revisit rows in your ResultSet:
1680 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1682 while( my $artist = $resultset->next ) {
1686 $rs->first; # without cache, this would issue a query
1688 By default, searches are not cached.
1690 For more examples of using these attributes, see
1691 L<DBIx::Class::Manual::Cookbook>.