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) = @_;
91 $attrs->{rows} ||= 10;
92 $attrs->{offset} ||= 0;
93 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
96 $attrs->{alias} ||= 'me';
99 result_source => $source,
100 result_class => $attrs->{result_class} || $source->result_class,
101 cond => $attrs->{where},
102 # from => $attrs->{from},
103 # collapse => $collapse,
105 page => delete $attrs->{page},
115 =item Arguments: $cond, \%attrs?
117 =item Return Value: $resultset (scalar context), @row_objs (list context)
121 my @cds = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
122 my $new_rs = $cd_rs->search({ year => 2005 });
124 my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
125 # year = 2005 OR year = 2004
127 If you need to pass in additional attributes but no additional condition,
128 call it as C<search(undef, \%attrs)>.
130 # "SELECT name, artistid FROM $artist_table"
131 my @all_artists = $schema->resultset('Artist')->search(undef, {
132 columns => [qw/name artistid/],
140 my $attrs = { %{$self->{attrs}} };
141 my $having = delete $attrs->{having};
142 $attrs = { %$attrs, %{ pop(@_) } } if @_ > 1 and ref $_[$#_] eq 'HASH';
145 ? ((@_ == 1 || ref $_[0] eq "HASH")
148 ? $self->throw_exception(
149 "Odd number of arguments to search")
152 if (defined $where) {
153 $attrs->{where} = (defined $attrs->{where}
155 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
156 $where, $attrs->{where} ] }
160 if (defined $having) {
161 $attrs->{having} = (defined $attrs->{having}
163 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
164 $having, $attrs->{having} ] }
168 my $rs = (ref $self)->new($self->result_source, $attrs);
169 $rs->{_parent_rs} = $self->{_parent_rs} if ($self->{_parent_rs}); #XXX - hack to pass through parent of related resultsets
171 unless (@_) { # no search, effectively just a clone
172 my $rows = $self->get_cache;
174 $rs->set_cache($rows);
178 return (wantarray ? $rs->all : $rs);
181 =head2 search_literal
185 =item Arguments: $sql_fragment, @bind_values
187 =item Return Value: $resultset (scalar context), @row_objs (list context)
191 my @cds = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
192 my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
194 Pass a literal chunk of SQL to be added to the conditional part of the
200 my ($self, $cond, @vals) = @_;
201 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
202 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
203 return $self->search(\$cond, $attrs);
210 =item Arguments: @values | \%cols, \%attrs?
212 =item Return Value: $row_object
216 Finds a row based on its primary key or unique constraint. For example, to find
217 a row by its primary key:
219 my $cd = $schema->resultset('CD')->find(5);
221 You can also find a row by a specific unique constraint using the C<key>
222 attribute. For example:
224 my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', { key => 'artist_title' });
226 Additionally, you can specify the columns explicitly by name:
228 my $cd = $schema->resultset('CD')->find(
230 artist => 'Massive Attack',
231 title => 'Mezzanine',
233 { key => 'artist_title' }
236 If no C<key> is specified and you explicitly name columns, it searches on all
237 unique constraints defined on the source, including the primary key.
239 If the C<key> is specified as C<primary>, it searches only on the primary key.
241 See also L</find_or_create> and L</update_or_create>. For information on how to
242 declare unique constraints, see
243 L<DBIx::Class::ResultSource/add_unique_constraint>.
249 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
251 # Parse out a hash from input
252 my @cols = exists $attrs->{key}
253 ? $self->result_source->unique_constraint_columns($attrs->{key})
254 : $self->result_source->primary_columns;
257 if (ref $_[0] eq 'HASH') {
258 $hash = { %{$_[0]} };
260 elsif (@_ == @cols) {
262 @{$hash}{@cols} = @_;
265 $self->throw_exception(
266 "Arguments to find must be a hashref or match the number of columns in the "
267 . exists $attrs->{key} ? "$attrs->{key} unique constraint" : "primary key"
271 # Check the hash we just parsed against our source's unique constraints
272 my @constraint_names = exists $attrs->{key}
274 : $self->result_source->unique_constraint_names;
275 $self->throw_exception(
276 "Can't find unless a primary key or unique constraint is defined"
277 ) unless @constraint_names;
280 foreach my $name (@constraint_names) {
281 my @unique_cols = $self->result_source->unique_constraint_columns($name);
282 my $unique_query = $self->_build_unique_query($hash, \@unique_cols);
284 # Add the ResultSet's alias
285 foreach my $key (grep { ! m/\./ } keys %$unique_query) {
286 my $alias = $self->{attrs}->{alias};
287 $unique_query->{"$alias.$key"} = delete $unique_query->{$key};
290 push @unique_queries, $unique_query if %$unique_query;
293 # Handle cases where the ResultSet already defines the query
294 my $query = @unique_queries ? \@unique_queries : undef;
299 my $rs = $self->search($query, $attrs);
301 return keys %{$rs->{_attrs}->{collapse}} ? $rs->next : $rs->single;
305 return (keys %{$self->{_attrs}->{collapse}})
306 ? $self->search($query)->next
307 : $self->single($query);
311 # _build_unique_query
313 # Constrain the specified query hash based on the specified column names.
315 sub _build_unique_query {
316 my ($self, $query, $unique_cols) = @_;
319 map { $_ => $query->{$_} }
320 grep { exists $query->{$_} }
323 return \%unique_query;
326 =head2 search_related
330 =item Arguments: $cond, \%attrs?
332 =item Return Value: $new_resultset
336 $new_rs = $cd_rs->search_related('artist', {
340 Searches the specified relationship, optionally specifying a condition and
341 attributes for matching records. See L</ATTRIBUTES> for more information.
346 return shift->related_resultset(shift)->search(@_);
353 =item Arguments: none
355 =item Return Value: $cursor
359 Returns a storage-driven cursor to the given resultset. See
360 L<DBIx::Class::Cursor> for more information.
368 my $attrs = { %{$self->{_attrs}} };
369 return $self->{cursor}
370 ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
371 $attrs->{where},$attrs);
378 =item Arguments: $cond?
380 =item Return Value: $row_object?
384 my $cd = $schema->resultset('CD')->single({ year => 2001 });
386 Inflates the first result without creating a cursor if the resultset has
387 any records in it; if not returns nothing. Used by L</find> as an optimisation.
392 my ($self, $where) = @_;
394 my $attrs = { %{$self->{_attrs}} };
396 if (defined $attrs->{where}) {
399 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
400 $where, delete $attrs->{where} ]
403 $attrs->{where} = $where;
407 my @data = $self->result_source->storage->select_single(
408 $attrs->{from}, $attrs->{select},
409 $attrs->{where},$attrs);
410 return (@data ? $self->_construct_object(@data) : ());
417 =item Arguments: $cond?
419 =item Return Value: $resultsetcolumn
423 my $max_length = $rs->get_column('length')->max;
425 Returns a ResultSetColumn instance for $column based on $self
430 my ($self, $column) = @_;
432 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
440 =item Arguments: $cond, \%attrs?
442 =item Return Value: $resultset (scalar context), @row_objs (list context)
446 # WHERE title LIKE '%blue%'
447 $cd_rs = $rs->search_like({ title => '%blue%'});
449 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
450 that this is simply a convenience method. You most likely want to use
451 L</search> with specific operators.
453 For more information, see L<DBIx::Class::Manual::Cookbook>.
459 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
460 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
461 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
462 return $class->search($query, { %$attrs });
469 =item Arguments: $first, $last
471 =item Return Value: $resultset (scalar context), @row_objs (list context)
475 Returns a resultset or object list representing a subset of elements from the
476 resultset slice is called on. Indexes are from 0, i.e., to get the first
479 my ($one, $two, $three) = $rs->slice(0, 2);
484 my ($self, $min, $max) = @_;
485 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
486 $attrs->{offset} = $self->{attrs}{offset} || 0;
487 $attrs->{offset} += $min;
488 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
489 return $self->search(undef(), $attrs);
490 #my $slice = (ref $self)->new($self->result_source, $attrs);
491 #return (wantarray ? $slice->all : $slice);
498 =item Arguments: none
500 =item Return Value: $result?
504 Returns the next element in the resultset (C<undef> is there is none).
506 Can be used to efficiently iterate over records in the resultset:
508 my $rs = $schema->resultset('CD')->search;
509 while (my $cd = $rs->next) {
513 Note that you need to store the resultset object, and call C<next> on it.
514 Calling C<< resultset('Table')->next >> repeatedly will always return the
515 first record from the resultset.
521 if (@{$self->{all_cache} || []}) {
522 $self->{all_cache_position} ||= 0;
523 return $self->{all_cache}->[$self->{all_cache_position}++];
525 if ($self->{attrs}{cache}) {
526 $self->{all_cache_position} = 1;
527 return ($self->all)[0];
529 my @row = (exists $self->{stashed_row} ?
530 @{delete $self->{stashed_row}} :
533 return unless (@row);
534 return $self->_construct_object(@row);
537 # XXX - this is essentially just the old new(). rewrite / tidy up?
541 return if(exists $self->{_attrs}); #return if _resolve has already been called
543 my $attrs = $self->{attrs};
544 my $source = ($self->{_parent_rs}) ? $self->{_parent_rs} : $self->{result_source};
546 # XXX - this is a hack to prevent dclone dieing because of the code ref, get's put back in $attrs afterwards
547 my $record_filter = delete $attrs->{record_filter} if (defined $attrs->{record_filter});
548 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
549 $attrs->{record_filter} = $record_filter if ($record_filter);
550 $self->{attrs}->{record_filter} = $record_filter if ($record_filter);
552 my $alias = $attrs->{alias};
554 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
555 delete $attrs->{as} if $attrs->{columns};
556 $attrs->{columns} ||= [ $self->{result_source}->columns ] unless $attrs->{select};
557 my $select_alias = ($self->{_parent_rs}) ? $self->{attrs}->{_live_join} : $alias;
559 map { m/\./ ? $_ : "${select_alias}.$_" } @{delete $attrs->{columns}}
560 ] if $attrs->{columns};
562 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
564 if (my $include = delete $attrs->{include_columns}) {
565 push(@{$attrs->{select}}, @$include);
566 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
569 $attrs->{from} ||= [ { $alias => $source->from } ];
570 $attrs->{seen_join} ||= {};
572 if (my $join = delete $attrs->{join}) {
573 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
574 if (ref $j eq 'HASH') {
575 $seen{$_} = 1 foreach keys %$j;
581 push(@{$attrs->{from}}, $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join}));
583 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
584 $attrs->{order_by} = [ $attrs->{order_by} ] if
585 $attrs->{order_by} and !ref($attrs->{order_by});
586 $attrs->{order_by} ||= [];
588 my $collapse = $attrs->{collapse} || {};
589 if (my $prefetch = delete $attrs->{prefetch}) {
591 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
592 if ( ref $p eq 'HASH' ) {
593 foreach my $key (keys %$p) {
594 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
598 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
601 my @prefetch = $source->resolve_prefetch(
602 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
603 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
604 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
606 push(@{$attrs->{order_by}}, @pre_order);
608 $attrs->{collapse} = $collapse;
609 $self->{_attrs} = $attrs;
612 sub _construct_object {
613 my ($self, @row) = @_;
614 my @as = @{ $self->{_attrs}{as} };
616 my $info = $self->_collapse_result(\@as, \@row);
617 my $new = $self->result_class->inflate_result($self->result_source, @$info, $self->{_parent_rs});
618 $new = $self->{_attrs}{record_filter}->($new)
619 if exists $self->{_attrs}{record_filter};
623 sub _collapse_result {
624 my ($self, $as, $row, $prefix) = @_;
626 my $live_join = $self->{attrs}->{_live_join} ||="";
630 foreach my $this_as (@$as) {
631 my $val = shift @copy;
632 if (defined $prefix) {
633 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
635 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
636 $const{$1||''}{$2} = $val;
639 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
640 $const{$1||''}{$2} = $val;
644 my $info = [ {}, {} ];
645 foreach my $key (keys %const) {
646 if (length $key && $key ne $live_join) {
648 my @parts = split(/\./, $key);
649 foreach my $p (@parts) {
650 $target = $target->[1]->{$p} ||= [];
652 $target->[0] = $const{$key};
654 $info->[0] = $const{$key};
659 if (defined $prefix) {
661 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
662 } keys %{$self->{_attrs}->{collapse}}
664 @collapse = keys %{$self->{_attrs}->{collapse}};
668 my ($c) = sort { length $a <=> length $b } @collapse;
670 foreach my $p (split(/\./, $c)) {
671 $target = $target->[1]->{$p} ||= [];
673 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
674 my @co_key = @{$self->{_attrs}->{collapse}{$c_prefix}};
675 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
676 my $tree = $self->_collapse_result($as, $row, $c_prefix);
679 !defined($tree->[0]->{$_}) ||
680 $co_check{$_} ne $tree->[0]->{$_}
683 last unless (@raw = $self->cursor->next);
684 $row = $self->{stashed_row} = \@raw;
685 $tree = $self->_collapse_result($as, $row, $c_prefix);
696 =item Arguments: $result_source?
698 =item Return Value: $result_source
702 An accessor for the primary ResultSource object from which this ResultSet
712 =item Arguments: $cond, \%attrs??
714 =item Return Value: $count
718 Performs an SQL C<COUNT> with the same query as the resultset was built
719 with to find the number of elements. If passed arguments, does a search
720 on the resultset and counts the results of that.
722 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
723 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
724 not support C<DISTINCT> with multiple columns. If you are using such a
725 database, you should only use columns from the main table in your C<group_by>
732 return $self->search(@_)->count if @_ and defined $_[0];
733 return scalar @{ $self->get_cache } if @{ $self->get_cache };
735 my $count = $self->_count;
736 return 0 unless $count;
738 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
739 $count = $self->{attrs}{rows} if
740 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
744 sub _count { # Separated out so pager can get the full count
746 my $select = { count => '*' };
749 my $attrs = { %{ $self->{_attrs} } };
750 if ($attrs->{distinct} && (my $group_by = $attrs->{group_by} || $attrs->{select})) {
751 delete $attrs->{having};
752 my @distinct = (ref $group_by ? @$group_by : ($group_by));
753 # todo: try CONCAT for multi-column pk
754 my @pk = $self->result_source->primary_columns;
756 foreach my $column (@distinct) {
757 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
758 @distinct = ($column);
764 $select = { count => { distinct => \@distinct } };
765 #use Data::Dumper; die Dumper $select;
768 $attrs->{select} = $select;
769 $attrs->{as} = [qw/count/];
771 # offset, order by and page are not needed to count. record_filter is cdbi
772 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
773 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
781 =item Arguments: $sql_fragment, @bind_values
783 =item Return Value: $count
787 Counts the results in a literal query. Equivalent to calling L</search_literal>
788 with the passed arguments, then L</count>.
792 sub count_literal { shift->search_literal(@_)->count; }
798 =item Arguments: none
800 =item Return Value: @objects
804 Returns all elements in the resultset. Called implicitly if the resultset
805 is returned in list context.
811 return @{ $self->get_cache } if @{ $self->get_cache };
815 # TODO: don't call resolve here
817 if (keys %{$self->{_attrs}->{collapse}}) {
818 # if ($self->{attrs}->{prefetch}) {
819 # Using $self->cursor->all is really just an optimisation.
820 # If we're collapsing has_many prefetches it probably makes
821 # very little difference, and this is cleaner than hacking
822 # _construct_object to survive the approach
823 my @row = $self->cursor->next;
825 push(@obj, $self->_construct_object(@row));
826 @row = (exists $self->{stashed_row}
827 ? @{delete $self->{stashed_row}}
828 : $self->cursor->next);
831 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
834 $self->set_cache(\@obj) if $self->{attrs}{cache};
842 =item Arguments: none
844 =item Return Value: $self
848 Resets the resultset's cursor, so you can iterate through the elements again.
854 delete $self->{_attrs} if (exists $self->{_attrs});
856 $self->{all_cache_position} = 0;
857 $self->cursor->reset;
865 =item Arguments: none
867 =item Return Value: $object?
871 Resets the resultset and returns an object for the first result (if the
872 resultset returns anything).
877 return $_[0]->reset->next;
880 # _cond_for_update_delete
882 # update/delete require the condition to be modified to handle
883 # the differing SQL syntax available. This transforms the $self->{cond}
884 # appropriately, returning the new condition.
886 sub _cond_for_update_delete {
890 if (!ref($self->{cond})) {
891 # No-op. No condition, we're updating/deleting everything
893 elsif (ref $self->{cond} eq 'ARRAY') {
897 foreach my $key (keys %{$_}) {
899 $hash{$1} = $_->{$key};
905 elsif (ref $self->{cond} eq 'HASH') {
906 if ((keys %{$self->{cond}})[0] eq '-and') {
909 my @cond = @{$self->{cond}{-and}};
910 for (my $i = 0; $i < @cond - 1; $i++) {
911 my $entry = $cond[$i];
914 if (ref $entry eq 'HASH') {
915 foreach my $key (keys %{$entry}) {
917 $hash{$1} = $entry->{$key};
921 $entry =~ /([^.]+)$/;
922 $hash{$entry} = $cond[++$i];
925 push @{$cond->{-and}}, \%hash;
929 foreach my $key (keys %{$self->{cond}}) {
931 $cond->{$1} = $self->{cond}{$key};
936 $self->throw_exception(
937 "Can't update/delete on resultset with condition unless hash or array"
949 =item Arguments: \%values
951 =item Return Value: $storage_rv
955 Sets the specified columns in the resultset to the supplied values in a
956 single query. Return value will be true if the update succeeded or false
957 if no records were updated; exact type of success value is storage-dependent.
962 my ($self, $values) = @_;
963 $self->throw_exception("Values for update must be a hash")
964 unless ref $values eq 'HASH';
966 my $cond = $self->_cond_for_update_delete;
968 return $self->result_source->storage->update(
969 $self->result_source->from, $values, $cond
977 =item Arguments: \%values
979 =item Return Value: 1
983 Fetches all objects and updates them one at a time. Note that C<update_all>
984 will run DBIC cascade triggers, while L</update> will not.
989 my ($self, $values) = @_;
990 $self->throw_exception("Values for update must be a hash")
991 unless ref $values eq 'HASH';
992 foreach my $obj ($self->all) {
993 $obj->set_columns($values)->update;
1002 =item Arguments: none
1004 =item Return Value: 1
1008 Deletes the contents of the resultset from its result source. Note that this
1009 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1018 my $cond = $self->_cond_for_update_delete;
1020 $self->result_source->storage->delete($self->result_source->from, $cond);
1028 =item Arguments: none
1030 =item Return Value: 1
1034 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1035 will run DBIC cascade triggers, while L</delete> will not.
1041 $_->delete for $self->all;
1049 =item Arguments: none
1051 =item Return Value: $pager
1055 Return Value a L<Data::Page> object for the current resultset. Only makes
1056 sense for queries with a C<page> attribute.
1062 my $attrs = $self->{attrs};
1063 $self->throw_exception("Can't create pager for non-paged rs")
1064 unless $self->{page};
1065 $attrs->{rows} ||= 10;
1066 return $self->{pager} ||= Data::Page->new(
1067 $self->_count, $attrs->{rows}, $self->{page});
1074 =item Arguments: $page_number
1076 =item Return Value: $rs
1080 Returns a resultset for the $page_number page of the resultset on which page
1081 is called, where each page contains a number of rows equal to the 'rows'
1082 attribute set on the resultset (10 by default).
1087 my ($self, $page) = @_;
1088 my $attrs = { %{$self->{attrs}} };
1089 $attrs->{page} = $page;
1090 return (ref $self)->new($self->result_source, $attrs);
1097 =item Arguments: \%vals
1099 =item Return Value: $object
1103 Creates an object in the resultset's result class and returns it.
1108 my ($self, $values) = @_;
1109 $self->throw_exception( "new_result needs a hash" )
1110 unless (ref $values eq 'HASH');
1111 $self->throw_exception(
1112 "Can't abstract implicit construct, condition not a hash"
1113 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1115 my $alias = $self->{attrs}{alias};
1116 foreach my $key (keys %{$self->{cond}||{}}) {
1117 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1119 my $obj = $self->result_class->new(\%new);
1120 $obj->result_source($self->result_source) if $obj->can('result_source');
1128 =item Arguments: \%vals, \%attrs?
1130 =item Return Value: $object
1134 Find an existing record from this resultset. If none exists, instantiate a new
1135 result object and return it. The object will not be saved into your storage
1136 until you call L<DBIx::Class::Row/insert> on it.
1138 If you want objects to be saved immediately, use L</find_or_create> instead.
1144 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1145 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1146 my $exists = $self->find($hash, $attrs);
1147 return defined $exists ? $exists : $self->new_result($hash);
1154 =item Arguments: \%vals
1156 =item Return Value: $object
1160 Inserts a record into the resultset and returns the object representing it.
1162 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1167 my ($self, $attrs) = @_;
1168 $self->throw_exception( "create needs a hashref" )
1169 unless ref $attrs eq 'HASH';
1170 return $self->new_result($attrs)->insert;
1173 =head2 find_or_create
1177 =item Arguments: \%vals, \%attrs?
1179 =item Return Value: $object
1183 $class->find_or_create({ key => $val, ... });
1185 Searches for a record matching the search condition; if it doesn't find one,
1186 creates one and returns that instead.
1188 my $cd = $schema->resultset('CD')->find_or_create({
1190 artist => 'Massive Attack',
1191 title => 'Mezzanine',
1195 Also takes an optional C<key> attribute, to search by a specific key or unique
1196 constraint. For example:
1198 my $cd = $schema->resultset('CD')->find_or_create(
1200 artist => 'Massive Attack',
1201 title => 'Mezzanine',
1203 { key => 'artist_title' }
1206 See also L</find> and L</update_or_create>. For information on how to declare
1207 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1211 sub find_or_create {
1213 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1214 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1215 my $exists = $self->find($hash, $attrs);
1216 return defined $exists ? $exists : $self->create($hash);
1219 =head2 update_or_create
1223 =item Arguments: \%col_values, { key => $unique_constraint }?
1225 =item Return Value: $object
1229 $class->update_or_create({ col => $val, ... });
1231 First, searches for an existing row matching one of the unique constraints
1232 (including the primary key) on the source of this resultset. If a row is
1233 found, updates it with the other given column values. Otherwise, creates a new
1236 Takes an optional C<key> attribute to search on a specific unique constraint.
1239 # In your application
1240 my $cd = $schema->resultset('CD')->update_or_create(
1242 artist => 'Massive Attack',
1243 title => 'Mezzanine',
1246 { key => 'artist_title' }
1249 If no C<key> is specified, it searches on all unique constraints defined on the
1250 source, including the primary key.
1252 If the C<key> is specified as C<primary>, it searches only on the primary key.
1254 See also L</find> and L</find_or_create>. For information on how to declare
1255 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1259 sub update_or_create {
1261 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1262 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1264 my $row = $self->find($hash, $attrs);
1266 $row->set_columns($hash);
1271 return $self->create($hash);
1278 =item Arguments: none
1280 =item Return Value: \@cache_objects?
1284 Gets the contents of the cache for the resultset, if the cache is set.
1289 shift->{all_cache} || [];
1296 =item Arguments: \@cache_objects
1298 =item Return Value: \@cache_objects
1302 Sets the contents of the cache for the resultset. Expects an arrayref
1303 of objects of the same class as those produced by the resultset. Note that
1304 if the cache is set the resultset will return the cached objects rather
1305 than re-querying the database even if the cache attr is not set.
1310 my ( $self, $data ) = @_;
1311 $self->throw_exception("set_cache requires an arrayref")
1312 if ref $data ne 'ARRAY';
1313 my $result_class = $self->result_class;
1315 $self->throw_exception(
1316 "cannot cache object of type '$_', expected '$result_class'"
1317 ) if ref $_ ne $result_class;
1319 $self->{all_cache} = $data;
1326 =item Arguments: none
1328 =item Return Value: []
1332 Clears the cache for the resultset.
1337 shift->set_cache([]);
1340 =head2 related_resultset
1344 =item Arguments: $relationship_name
1346 =item Return Value: $resultset
1350 Returns a related resultset for the supplied relationship name.
1352 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1356 sub related_resultset {
1357 my ( $self, $rel ) = @_;
1359 $self->{related_resultsets} ||= {};
1360 return $self->{related_resultsets}{$rel} ||= do {
1361 #warn "fetching related resultset for rel '$rel' " . $self->result_source->{name};
1362 my $rel_obj = $self->result_source->relationship_info($rel);
1363 $self->throw_exception(
1364 "search_related: result source '" . $self->result_source->name .
1365 "' has no such relationship ${rel}")
1366 unless $rel_obj; #die Dumper $self->{attrs};
1368 my $rs = $self->result_source->schema->resultset($rel_obj->{class}
1370 { %{$self->{attrs}},
1374 _live_join => $rel }
1377 # keep reference of the original resultset
1378 $rs->{_parent_rs} = $self->result_source;
1383 =head2 throw_exception
1385 See L<DBIx::Class::Schema/throw_exception> for details.
1389 sub throw_exception {
1391 $self->result_source->schema->throw_exception(@_);
1394 # XXX: FIXME: Attributes docs need clearing up
1398 The resultset takes various attributes that modify its behavior. Here's an
1405 =item Value: ($order_by | \@order_by)
1409 Which column(s) to order the results by. This is currently passed
1410 through directly to SQL, so you can give e.g. C<year DESC> for a
1411 descending order on the column `year'.
1417 =item Value: \@columns
1421 Shortcut to request a particular set of columns to be retrieved. Adds
1422 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1423 from that, then auto-populates C<as> from C<select> as normal. (You may also
1424 use the C<cols> attribute, as in earlier versions of DBIC.)
1426 =head2 include_columns
1430 =item Value: \@columns
1434 Shortcut to include additional columns in the returned results - for example
1436 $schema->resultset('CD')->search(undef, {
1437 include_columns => ['artist.name'],
1441 would return all CDs and include a 'name' column to the information
1442 passed to object inflation
1448 =item Value: \@select_columns
1452 Indicates which columns should be selected from the storage. You can use
1453 column names, or in the case of RDBMS back ends, function or stored procedure
1456 $rs = $schema->resultset('Employee')->search(undef, {
1459 { count => 'employeeid' },
1464 When you use function/stored procedure names and do not supply an C<as>
1465 attribute, the column names returned are storage-dependent. E.g. MySQL would
1466 return a column named C<count(employeeid)> in the above example.
1472 =item Value: \@inflation_names
1476 Indicates column names for object inflation. This is used in conjunction with
1477 C<select>, usually when C<select> contains one or more function or stored
1480 $rs = $schema->resultset('Employee')->search(undef, {
1483 { count => 'employeeid' }
1485 as => ['name', 'employee_count'],
1488 my $employee = $rs->first(); # get the first Employee
1490 If the object against which the search is performed already has an accessor
1491 matching a column name specified in C<as>, the value can be retrieved using
1492 the accessor as normal:
1494 my $name = $employee->name();
1496 If on the other hand an accessor does not exist in the object, you need to
1497 use C<get_column> instead:
1499 my $employee_count = $employee->get_column('employee_count');
1501 You can create your own accessors if required - see
1502 L<DBIx::Class::Manual::Cookbook> for details.
1508 =item Value: ($rel_name | \@rel_names | \%rel_names)
1512 Contains a list of relationships that should be joined for this query. For
1515 # Get CDs by Nine Inch Nails
1516 my $rs = $schema->resultset('CD')->search(
1517 { 'artist.name' => 'Nine Inch Nails' },
1518 { join => 'artist' }
1521 Can also contain a hash reference to refer to the other relation's relations.
1524 package MyApp::Schema::Track;
1525 use base qw/DBIx::Class/;
1526 __PACKAGE__->table('track');
1527 __PACKAGE__->add_columns(qw/trackid cd position title/);
1528 __PACKAGE__->set_primary_key('trackid');
1529 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1532 # In your application
1533 my $rs = $schema->resultset('Artist')->search(
1534 { 'track.title' => 'Teardrop' },
1536 join => { cd => 'track' },
1537 order_by => 'artist.name',
1541 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1542 similarly for a third time). For e.g.
1544 my $rs = $schema->resultset('Artist')->search({
1545 'cds.title' => 'Down to Earth',
1546 'cds_2.title' => 'Popular',
1548 join => [ qw/cds cds/ ],
1551 will return a set of all artists that have both a cd with title 'Down
1552 to Earth' and a cd with title 'Popular'.
1554 If you want to fetch related objects from other tables as well, see C<prefetch>
1561 =item Value: ($rel_name | \@rel_names | \%rel_names)
1565 Contains one or more relationships that should be fetched along with the main
1566 query (when they are accessed afterwards they will have already been
1567 "prefetched"). This is useful for when you know you will need the related
1568 objects, because it saves at least one query:
1570 my $rs = $schema->resultset('Tag')->search(
1579 The initial search results in SQL like the following:
1581 SELECT tag.*, cd.*, artist.* FROM tag
1582 JOIN cd ON tag.cd = cd.cdid
1583 JOIN artist ON cd.artist = artist.artistid
1585 L<DBIx::Class> has no need to go back to the database when we access the
1586 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1589 Simple prefetches will be joined automatically, so there is no need
1590 for a C<join> attribute in the above search. If you're prefetching to
1591 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1592 specify the join as well.
1594 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1595 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1596 with an accessor type of 'single' or 'filter').
1602 =item Value: \@from_clause
1606 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1607 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1610 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1611 C<join> will usually do what you need and it is strongly recommended that you
1612 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1614 In simple terms, C<from> works as follows:
1617 { <alias> => <table>, -join_type => 'inner|left|right' }
1618 [] # nested JOIN (optional)
1619 { <table.column> => <foreign_table.foreign_key> }
1625 ON <table.column> = <foreign_table.foreign_key>
1627 An easy way to follow the examples below is to remember the following:
1629 Anything inside "[]" is a JOIN
1630 Anything inside "{}" is a condition for the enclosing JOIN
1632 The following examples utilize a "person" table in a family tree application.
1633 In order to express parent->child relationships, this table is self-joined:
1635 # Person->belongs_to('father' => 'Person');
1636 # Person->belongs_to('mother' => 'Person');
1638 C<from> can be used to nest joins. Here we return all children with a father,
1639 then search against all mothers of those children:
1641 $rs = $schema->resultset('Person')->search(
1644 alias => 'mother', # alias columns in accordance with "from"
1646 { mother => 'person' },
1649 { child => 'person' },
1651 { father => 'person' },
1652 { 'father.person_id' => 'child.father_id' }
1655 { 'mother.person_id' => 'child.mother_id' }
1662 # SELECT mother.* FROM person mother
1665 # JOIN person father
1666 # ON ( father.person_id = child.father_id )
1668 # ON ( mother.person_id = child.mother_id )
1670 The type of any join can be controlled manually. To search against only people
1671 with a father in the person table, we could explicitly use C<INNER JOIN>:
1673 $rs = $schema->resultset('Person')->search(
1676 alias => 'child', # alias columns in accordance with "from"
1678 { child => 'person' },
1680 { father => 'person', -join_type => 'inner' },
1681 { 'father.id' => 'child.father_id' }
1688 # SELECT child.* FROM person child
1689 # INNER JOIN person father ON child.father_id = father.id
1699 Makes the resultset paged and specifies the page to retrieve. Effectively
1700 identical to creating a non-pages resultset and then calling ->page($page)
1711 Specifes the maximum number of rows for direct retrieval or the number of
1712 rows per page if the page attribute or method is used.
1718 =item Value: \@columns
1722 A arrayref of columns to group by. Can include columns of joined tables.
1724 group_by => [qw/ column1 column2 ... /]
1730 =item Value: $condition
1734 HAVING is a select statement attribute that is applied between GROUP BY and
1735 ORDER BY. It is applied to the after the grouping calculations have been
1738 having => { 'count(employee)' => { '>=', 100 } }
1744 =item Value: (0 | 1)
1748 Set to 1 to group by all columns.
1752 Set to 1 to cache search results. This prevents extra SQL queries if you
1753 revisit rows in your ResultSet:
1755 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1757 while( my $artist = $resultset->next ) {
1761 $rs->first; # without cache, this would issue a query
1763 By default, searches are not cached.
1765 For more examples of using these attributes, see
1766 L<DBIx::Class::Manual::Cookbook>.