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});
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
201 my ($self, $cond, @vals) = @_;
202 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
203 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
204 return $self->search(\$cond, $attrs);
211 =item Arguments: @values | \%cols, \%attrs?
213 =item Return Value: $row_object
217 Finds a row based on its primary key or unique constraint. For example, to find
218 a row by its primary key:
220 my $cd = $schema->resultset('CD')->find(5);
222 You can also find a row by a specific unique constraint using the C<key>
223 attribute. For example:
225 my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', { key => 'artist_title' });
227 Additionally, you can specify the columns explicitly by name:
229 my $cd = $schema->resultset('CD')->find(
231 artist => 'Massive Attack',
232 title => 'Mezzanine',
234 { key => 'artist_title' }
237 If no C<key> is specified and you explicitly name columns, it searches on all
238 unique constraints defined on the source, including the primary key.
240 If the C<key> is specified as C<primary>, it searches only on the primary key.
242 See also L</find_or_create> and L</update_or_create>. For information on how to
243 declare unique constraints, see
244 L<DBIx::Class::ResultSource/add_unique_constraint>.
250 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
252 # Parse out a hash from input
253 my @cols = exists $attrs->{key}
254 ? $self->result_source->unique_constraint_columns($attrs->{key})
255 : $self->result_source->primary_columns;
258 if (ref $_[0] eq 'HASH') {
259 $hash = { %{$_[0]} };
261 elsif (@_ == @cols) {
263 @{$hash}{@cols} = @_;
266 $self->throw_exception(
267 "Arguments to find must be a hashref or match the number of columns in the "
268 . exists $attrs->{key} ? "$attrs->{key} unique constraint" : "primary key"
272 # Check the hash we just parsed against our source's unique constraints
273 my @constraint_names = exists $attrs->{key}
275 : $self->result_source->unique_constraint_names;
276 $self->throw_exception(
277 "Can't find unless a primary key or unique constraint is defined"
278 ) unless @constraint_names;
281 foreach my $name (@constraint_names) {
282 my @unique_cols = $self->result_source->unique_constraint_columns($name);
283 my $unique_query = $self->_build_unique_query($hash, \@unique_cols);
285 # Add the ResultSet's alias
286 foreach my $key (grep { ! m/\./ } keys %$unique_query) {
287 # TODO: tidy up alias shit
288 my $alias = $self->{attrs}{alias} || 'me';
289 $unique_query->{"$alias.$key"} = delete $unique_query->{$key};
292 push @unique_queries, $unique_query if %$unique_query;
295 # Handle cases where the ResultSet already defines the query
296 my $query = @unique_queries ? \@unique_queries : undef;
300 my $rs = $self->search($query, $attrs);
301 return $rs->{attrs}->{prefetch} ? $rs->next : $rs->single;
304 return ($self->{attrs}->{prefetch})
305 ? $self->search($query)->next
306 : $self->single($query);
310 # _build_unique_query
312 # Constrain the specified query hash based on the specified column names.
314 sub _build_unique_query {
315 my ($self, $query, $unique_cols) = @_;
318 map { $_ => $query->{$_} }
319 grep { exists $query->{$_} }
322 return \%unique_query;
325 =head2 search_related
329 =item Arguments: $cond, \%attrs?
331 =item Return Value: $new_resultset
335 $new_rs = $cd_rs->search_related('artist', {
339 Searches the specified relationship, optionally specifying a condition and
340 attributes for matching records. See L</ATTRIBUTES> for more information.
345 return shift->related_resultset(shift)->search(@_);
352 =item Arguments: none
354 =item Return Value: $cursor
358 Returns a storage-driven cursor to the given resultset. See
359 L<DBIx::Class::Cursor> for more information.
367 my $attrs = { %{$self->{_attrs}} };
368 return $self->{cursor}
369 ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
370 $attrs->{where},$attrs);
377 =item Arguments: $cond?
379 =item Return Value: $row_object?
383 my $cd = $schema->resultset('CD')->single({ year => 2001 });
385 Inflates the first result without creating a cursor if the resultset has
386 any records in it; if not returns nothing. Used by L</find> as an optimisation.
391 my ($self, $where) = @_;
393 my $attrs = { %{$self->{_attrs}} };
395 if (defined $attrs->{where}) {
398 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
399 $where, delete $attrs->{where} ]
402 $attrs->{where} = $where;
406 my @data = $self->result_source->storage->select_single(
407 $attrs->{from}, $attrs->{select},
408 $attrs->{where},$attrs);
409 return (@data ? $self->_construct_object(@data) : ());
416 =item Arguments: $cond?
418 =item Return Value: $resultsetcolumn
422 my $max_length = $rs->get_column('length')->max;
424 Returns a ResultSetColumn instance for $column based on $self
429 my ($self, $column) = @_;
431 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
439 =item Arguments: $cond, \%attrs?
441 =item Return Value: $resultset (scalar context), @row_objs (list context)
445 # WHERE title LIKE '%blue%'
446 $cd_rs = $rs->search_like({ title => '%blue%'});
448 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
449 that this is simply a convenience method. You most likely want to use
450 L</search> with specific operators.
452 For more information, see L<DBIx::Class::Manual::Cookbook>.
458 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
459 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
460 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
461 return $class->search($query, { %$attrs });
468 =item Arguments: $first, $last
470 =item Return Value: $resultset (scalar context), @row_objs (list context)
474 Returns a resultset or object list representing a subset of elements from the
475 resultset slice is called on. Indexes are from 0, i.e., to get the first
478 my ($one, $two, $three) = $rs->slice(0, 2);
483 my ($self, $min, $max) = @_;
484 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
485 $attrs->{offset} = $self->{attrs}{offset} || 0;
486 $attrs->{offset} += $min;
487 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
488 return $self->search(undef(), $attrs);
489 #my $slice = (ref $self)->new($self->result_source, $attrs);
490 #return (wantarray ? $slice->all : $slice);
497 =item Arguments: none
499 =item Return Value: $result?
503 Returns the next element in the resultset (C<undef> is there is none).
505 Can be used to efficiently iterate over records in the resultset:
507 my $rs = $schema->resultset('CD')->search;
508 while (my $cd = $rs->next) {
512 Note that you need to store the resultset object, and call C<next> on it.
513 Calling C<< resultset('Table')->next >> repeatedly will always return the
514 first record from the resultset.
520 if (@{$self->{all_cache} || []}) {
521 $self->{all_cache_position} ||= 0;
522 return $self->{all_cache}->[$self->{all_cache_position}++];
524 if ($self->{attrs}{cache}) {
525 $self->{all_cache_position} = 1;
526 return ($self->all)[0];
528 my @row = (exists $self->{stashed_row} ?
529 @{delete $self->{stashed_row}} :
532 return unless (@row);
533 return $self->_construct_object(@row);
536 # XXX - this is essentially just the old new(). rewrite / tidy up?
540 my $attrs = $self->{attrs};
541 my $source = ($self->{_parent_rs}) ? $self->{_parent_rs} : $self->{result_source};
543 # XXX - this is a hack to prevent dclone dieing because of the code ref, get's put back in $attrs afterwards
544 my $record_filter = delete $attrs->{record_filter} if (defined $attrs->{record_filter});
545 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
546 my $alias = $attrs->{alias};
548 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
549 delete $attrs->{as} if $attrs->{columns};
550 $attrs->{columns} ||= [ $self->{result_source}->columns ] unless $attrs->{select};
551 my $select_alias = ($self->{_parent_rs}) ? $self->{attrs}->{_live_join} : $alias;
553 map { m/\./ ? $_ : "${select_alias}.$_" } @{delete $attrs->{columns}}
554 ] if $attrs->{columns};
556 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
558 if (my $include = delete $attrs->{include_columns}) {
559 push(@{$attrs->{select}}, @$include);
560 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
562 #use Data::Dumper; warn Dumper(@{$attrs}{qw/select as/});
564 $attrs->{from} ||= [ { $alias => $source->from } ];
565 $attrs->{seen_join} ||= {};
567 if (my $join = delete $attrs->{join}) {
568 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
569 if (ref $j eq 'HASH') {
570 $seen{$_} = 1 foreach keys %$j;
576 push(@{$attrs->{from}}, $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join}));
579 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
580 $attrs->{order_by} = [ $attrs->{order_by} ] if
581 $attrs->{order_by} and !ref($attrs->{order_by});
582 $attrs->{order_by} ||= [];
584 my $collapse = $attrs->{collapse} || {};
585 if (my $prefetch = delete $attrs->{prefetch}) {
587 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
588 if ( ref $p eq 'HASH' ) {
589 foreach my $key (keys %$p) {
590 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
594 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
597 my @prefetch = $source->resolve_prefetch(
598 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
599 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
600 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
602 push(@{$attrs->{order_by}}, @pre_order);
604 $attrs->{collapse} = $collapse;
605 $attrs->{record_filter} = $record_filter if ($record_filter);
606 $self->{_attrs} = $attrs;
609 sub _construct_object {
610 my ($self, @row) = @_;
611 my @as = @{ $self->{_attrs}{as} };
613 my $info = $self->_collapse_result(\@as, \@row);
614 my $new = $self->result_class->inflate_result($self->result_source, @$info, $self->{_parent_rs});
615 $new = $self->{_attrs}{record_filter}->($new)
616 if exists $self->{_attrs}{record_filter};
620 sub _collapse_result {
621 my ($self, $as, $row, $prefix) = @_;
623 my $live_join = $self->{attrs}->{_live_join} ||="";
627 foreach my $this_as (@$as) {
628 my $val = shift @copy;
629 if (defined $prefix) {
630 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
632 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
633 $const{$1||''}{$2} = $val;
636 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
637 $const{$1||''}{$2} = $val;
641 my $info = [ {}, {} ];
642 foreach my $key (keys %const) {
643 if (length $key && $key ne $live_join) {
645 my @parts = split(/\./, $key);
646 foreach my $p (@parts) {
647 $target = $target->[1]->{$p} ||= [];
649 $target->[0] = $const{$key};
651 $info->[0] = $const{$key};
656 if (defined $prefix) {
658 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
659 } keys %{$self->{_attrs}->{collapse}}
661 @collapse = keys %{$self->{_attrs}->{collapse}};
665 my ($c) = sort { length $a <=> length $b } @collapse;
667 foreach my $p (split(/\./, $c)) {
668 $target = $target->[1]->{$p} ||= [];
670 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
671 my @co_key = @{$self->{_attrs}->{collapse}{$c_prefix}};
672 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
673 my $tree = $self->_collapse_result($as, $row, $c_prefix);
676 !defined($tree->[0]->{$_}) ||
677 $co_check{$_} ne $tree->[0]->{$_}
680 last unless (@raw = $self->cursor->next);
681 $row = $self->{stashed_row} = \@raw;
682 $tree = $self->_collapse_result($as, $row, $c_prefix);
693 =item Arguments: $result_source?
695 =item Return Value: $result_source
699 An accessor for the primary ResultSource object from which this ResultSet
709 =item Arguments: $cond, \%attrs??
711 =item Return Value: $count
715 Performs an SQL C<COUNT> with the same query as the resultset was built
716 with to find the number of elements. If passed arguments, does a search
717 on the resultset and counts the results of that.
719 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
720 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
721 not support C<DISTINCT> with multiple columns. If you are using such a
722 database, you should only use columns from the main table in your C<group_by>
729 return $self->search(@_)->count if @_ and defined $_[0];
730 return scalar @{ $self->get_cache } if @{ $self->get_cache };
732 my $count = $self->_count;
733 return 0 unless $count;
735 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
736 $count = $self->{attrs}{rows} if
737 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
741 sub _count { # Separated out so pager can get the full count
743 my $select = { count => '*' };
746 my $attrs = { %{ $self->{_attrs} } };
747 if (my $group_by = delete $attrs->{group_by}) {
748 delete $attrs->{having};
749 my @distinct = (ref $group_by ? @$group_by : ($group_by));
750 # todo: try CONCAT for multi-column pk
751 my @pk = $self->result_source->primary_columns;
753 foreach my $column (@distinct) {
754 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
755 @distinct = ($column);
761 $select = { count => { distinct => \@distinct } };
762 #use Data::Dumper; die Dumper $select;
765 $attrs->{select} = $select;
766 $attrs->{as} = [qw/count/];
768 # offset, order by and page are not needed to count. record_filter is cdbi
769 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
771 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
779 =item Arguments: $sql_fragment, @bind_values
781 =item Return Value: $count
785 Counts the results in a literal query. Equivalent to calling L</search_literal>
786 with the passed arguments, then L</count>.
790 sub count_literal { shift->search_literal(@_)->count; }
796 =item Arguments: none
798 =item Return Value: @objects
802 Returns all elements in the resultset. Called implicitly if the resultset
803 is returned in list context.
809 return @{ $self->get_cache } if @{ $self->get_cache };
813 # XXX used to be 'if (keys %{$self->{collapse}})'
814 # XXX replaced by this as it seemed to do roughly the same thing
815 # XXX could be bad as never really understood exactly what collapse did
816 if ($self->{attrs}->{prefetch}) {
817 # Using $self->cursor->all is really just an optimisation.
818 # If we're collapsing has_many prefetches it probably makes
819 # very little difference, and this is cleaner than hacking
820 # _construct_object to survive the approach
821 my @row = $self->cursor->next;
823 push(@obj, $self->_construct_object(@row));
824 @row = (exists $self->{stashed_row}
825 ? @{delete $self->{stashed_row}}
826 : $self->cursor->next);
829 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
832 $self->set_cache(\@obj) if $self->{attrs}{cache};
840 =item Arguments: none
842 =item Return Value: $self
846 Resets the resultset's cursor, so you can iterate through the elements again.
852 $self->{all_cache_position} = 0;
853 $self->cursor->reset;
861 =item Arguments: none
863 =item Return Value: $object?
867 Resets the resultset and returns an object for the first result (if the
868 resultset returns anything).
873 return $_[0]->reset->next;
876 # _cond_for_update_delete
878 # update/delete require the condition to be modified to handle
879 # the differing SQL syntax available. This transforms the $self->{cond}
880 # appropriately, returning the new condition.
882 sub _cond_for_update_delete {
886 if (!ref($self->{cond})) {
887 # No-op. No condition, we're updating/deleting everything
889 elsif (ref $self->{cond} eq 'ARRAY') {
893 foreach my $key (keys %{$_}) {
895 $hash{$1} = $_->{$key};
901 elsif (ref $self->{cond} eq 'HASH') {
902 if ((keys %{$self->{cond}})[0] eq '-and') {
905 my @cond = @{$self->{cond}{-and}};
906 for (my $i = 0; $i < @cond - 1; $i++) {
907 my $entry = $cond[$i];
910 if (ref $entry eq 'HASH') {
911 foreach my $key (keys %{$entry}) {
913 $hash{$1} = $entry->{$key};
917 $entry =~ /([^.]+)$/;
918 $hash{$entry} = $cond[++$i];
921 push @{$cond->{-and}}, \%hash;
925 foreach my $key (keys %{$self->{cond}}) {
927 $cond->{$1} = $self->{cond}{$key};
932 $self->throw_exception(
933 "Can't update/delete on resultset with condition unless hash or array"
945 =item Arguments: \%values
947 =item Return Value: $storage_rv
951 Sets the specified columns in the resultset to the supplied values in a
952 single query. Return value will be true if the update succeeded or false
953 if no records were updated; exact type of success value is storage-dependent.
958 my ($self, $values) = @_;
959 $self->throw_exception("Values for update must be a hash")
960 unless ref $values eq 'HASH';
962 my $cond = $self->_cond_for_update_delete;
964 return $self->result_source->storage->update(
965 $self->result_source->from, $values, $cond
973 =item Arguments: \%values
975 =item Return Value: 1
979 Fetches all objects and updates them one at a time. Note that C<update_all>
980 will run DBIC cascade triggers, while L</update> will not.
985 my ($self, $values) = @_;
986 $self->throw_exception("Values for update must be a hash")
987 unless ref $values eq 'HASH';
988 foreach my $obj ($self->all) {
989 $obj->set_columns($values)->update;
998 =item Arguments: none
1000 =item Return Value: 1
1004 Deletes the contents of the resultset from its result source. Note that this
1005 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1014 # this is broken now
1015 my $cond = $self->_cond_for_update_delete;
1017 $self->result_source->storage->delete($self->result_source->from, $cond);
1025 =item Arguments: none
1027 =item Return Value: 1
1031 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1032 will run DBIC cascade triggers, while L</delete> will not.
1038 $_->delete for $self->all;
1046 =item Arguments: none
1048 =item Return Value: $pager
1052 Return Value a L<Data::Page> object for the current resultset. Only makes
1053 sense for queries with a C<page> attribute.
1059 my $attrs = $self->{attrs};
1060 $self->throw_exception("Can't create pager for non-paged rs")
1061 unless $self->{page};
1062 $attrs->{rows} ||= 10;
1063 return $self->{pager} ||= Data::Page->new(
1064 $self->_count, $attrs->{rows}, $self->{page});
1071 =item Arguments: $page_number
1073 =item Return Value: $rs
1077 Returns a resultset for the $page_number page of the resultset on which page
1078 is called, where each page contains a number of rows equal to the 'rows'
1079 attribute set on the resultset (10 by default).
1084 my ($self, $page) = @_;
1085 my $attrs = { %{$self->{attrs}} };
1086 $attrs->{page} = $page;
1087 return (ref $self)->new($self->result_source, $attrs);
1094 =item Arguments: \%vals
1096 =item Return Value: $object
1100 Creates an object in the resultset's result class and returns it.
1105 my ($self, $values) = @_;
1106 $self->throw_exception( "new_result needs a hash" )
1107 unless (ref $values eq 'HASH');
1108 $self->throw_exception(
1109 "Can't abstract implicit construct, condition not a hash"
1110 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1112 my $alias = $self->{attrs}{alias};
1113 foreach my $key (keys %{$self->{cond}||{}}) {
1114 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1116 my $obj = $self->result_class->new(\%new);
1117 $obj->result_source($self->result_source) if $obj->can('result_source');
1125 =item Arguments: \%vals, \%attrs?
1127 =item Return Value: $object
1131 Find an existing record from this resultset. If none exists, instantiate a new
1132 result object and return it. The object will not be saved into your storage
1133 until you call L<DBIx::Class::Row/insert> on it.
1135 If you want objects to be saved immediately, use L</find_or_create> instead.
1141 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1142 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1143 my $exists = $self->find($hash, $attrs);
1144 return defined $exists ? $exists : $self->new_result($hash);
1151 =item Arguments: \%vals
1153 =item Return Value: $object
1157 Inserts a record into the resultset and returns the object representing it.
1159 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1164 my ($self, $attrs) = @_;
1165 $self->throw_exception( "create needs a hashref" )
1166 unless ref $attrs eq 'HASH';
1167 return $self->new_result($attrs)->insert;
1170 =head2 find_or_create
1174 =item Arguments: \%vals, \%attrs?
1176 =item Return Value: $object
1180 $class->find_or_create({ key => $val, ... });
1182 Searches for a record matching the search condition; if it doesn't find one,
1183 creates one and returns that instead.
1185 my $cd = $schema->resultset('CD')->find_or_create({
1187 artist => 'Massive Attack',
1188 title => 'Mezzanine',
1192 Also takes an optional C<key> attribute, to search by a specific key or unique
1193 constraint. For example:
1195 my $cd = $schema->resultset('CD')->find_or_create(
1197 artist => 'Massive Attack',
1198 title => 'Mezzanine',
1200 { key => 'artist_title' }
1203 See also L</find> and L</update_or_create>. For information on how to declare
1204 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1208 sub find_or_create {
1210 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1211 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1212 my $exists = $self->find($hash, $attrs);
1213 return defined $exists ? $exists : $self->create($hash);
1216 =head2 update_or_create
1220 =item Arguments: \%col_values, { key => $unique_constraint }?
1222 =item Return Value: $object
1226 $class->update_or_create({ col => $val, ... });
1228 First, searches for an existing row matching one of the unique constraints
1229 (including the primary key) on the source of this resultset. If a row is
1230 found, updates it with the other given column values. Otherwise, creates a new
1233 Takes an optional C<key> attribute to search on a specific unique constraint.
1236 # In your application
1237 my $cd = $schema->resultset('CD')->update_or_create(
1239 artist => 'Massive Attack',
1240 title => 'Mezzanine',
1243 { key => 'artist_title' }
1246 If no C<key> is specified, it searches on all unique constraints defined on the
1247 source, including the primary key.
1249 If the C<key> is specified as C<primary>, it searches only on the primary key.
1251 See also L</find> and L</find_or_create>. For information on how to declare
1252 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1256 sub update_or_create {
1258 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1259 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1261 my $row = $self->find($hash, $attrs);
1263 $row->set_columns($hash);
1268 return $self->create($hash);
1275 =item Arguments: none
1277 =item Return Value: \@cache_objects?
1281 Gets the contents of the cache for the resultset, if the cache is set.
1286 shift->{all_cache} || [];
1293 =item Arguments: \@cache_objects
1295 =item Return Value: \@cache_objects
1299 Sets the contents of the cache for the resultset. Expects an arrayref
1300 of objects of the same class as those produced by the resultset. Note that
1301 if the cache is set the resultset will return the cached objects rather
1302 than re-querying the database even if the cache attr is not set.
1307 my ( $self, $data ) = @_;
1308 $self->throw_exception("set_cache requires an arrayref")
1309 if ref $data ne 'ARRAY';
1310 my $result_class = $self->result_class;
1312 $self->throw_exception(
1313 "cannot cache object of type '$_', expected '$result_class'"
1314 ) if ref $_ ne $result_class;
1316 $self->{all_cache} = $data;
1323 =item Arguments: none
1325 =item Return Value: []
1329 Clears the cache for the resultset.
1334 shift->set_cache([]);
1337 =head2 related_resultset
1341 =item Arguments: $relationship_name
1343 =item Return Value: $resultset
1347 Returns a related resultset for the supplied relationship name.
1349 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1353 sub related_resultset {
1354 my ( $self, $rel ) = @_;
1356 $self->{related_resultsets} ||= {};
1357 return $self->{related_resultsets}{$rel} ||= do {
1358 # warn "fetching related resultset for rel '$rel' " . $self->result_source->{name};
1359 my $rel_obj = $self->result_source->relationship_info($rel);
1360 $self->throw_exception(
1361 "search_related: result source '" . $self->result_source->name .
1362 "' has no such relationship ${rel}")
1363 unless $rel_obj; #die Dumper $self->{attrs};
1365 my $rs = $self->result_source->schema->resultset($rel_obj->{class}
1367 { %{$self->{attrs}},
1371 _live_join => $rel }
1373 $rs->{_parent_rs} = $self->result_source;
1378 =head2 throw_exception
1380 See L<DBIx::Class::Schema/throw_exception> for details.
1384 sub throw_exception {
1386 $self->result_source->schema->throw_exception(@_);
1389 # XXX: FIXME: Attributes docs need clearing up
1393 The resultset takes various attributes that modify its behavior. Here's an
1400 =item Value: ($order_by | \@order_by)
1404 Which column(s) to order the results by. This is currently passed
1405 through directly to SQL, so you can give e.g. C<year DESC> for a
1406 descending order on the column `year'.
1412 =item Value: \@columns
1416 Shortcut to request a particular set of columns to be retrieved. Adds
1417 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1418 from that, then auto-populates C<as> from C<select> as normal. (You may also
1419 use the C<cols> attribute, as in earlier versions of DBIC.)
1421 =head2 include_columns
1425 =item Value: \@columns
1429 Shortcut to include additional columns in the returned results - for example
1431 $schema->resultset('CD')->search(undef, {
1432 include_columns => ['artist.name'],
1436 would return all CDs and include a 'name' column to the information
1437 passed to object inflation
1443 =item Value: \@select_columns
1447 Indicates which columns should be selected from the storage. You can use
1448 column names, or in the case of RDBMS back ends, function or stored procedure
1451 $rs = $schema->resultset('Employee')->search(undef, {
1454 { count => 'employeeid' },
1459 When you use function/stored procedure names and do not supply an C<as>
1460 attribute, the column names returned are storage-dependent. E.g. MySQL would
1461 return a column named C<count(employeeid)> in the above example.
1467 =item Value: \@inflation_names
1471 Indicates column names for object inflation. This is used in conjunction with
1472 C<select>, usually when C<select> contains one or more function or stored
1475 $rs = $schema->resultset('Employee')->search(undef, {
1478 { count => 'employeeid' }
1480 as => ['name', 'employee_count'],
1483 my $employee = $rs->first(); # get the first Employee
1485 If the object against which the search is performed already has an accessor
1486 matching a column name specified in C<as>, the value can be retrieved using
1487 the accessor as normal:
1489 my $name = $employee->name();
1491 If on the other hand an accessor does not exist in the object, you need to
1492 use C<get_column> instead:
1494 my $employee_count = $employee->get_column('employee_count');
1496 You can create your own accessors if required - see
1497 L<DBIx::Class::Manual::Cookbook> for details.
1503 =item Value: ($rel_name | \@rel_names | \%rel_names)
1507 Contains a list of relationships that should be joined for this query. For
1510 # Get CDs by Nine Inch Nails
1511 my $rs = $schema->resultset('CD')->search(
1512 { 'artist.name' => 'Nine Inch Nails' },
1513 { join => 'artist' }
1516 Can also contain a hash reference to refer to the other relation's relations.
1519 package MyApp::Schema::Track;
1520 use base qw/DBIx::Class/;
1521 __PACKAGE__->table('track');
1522 __PACKAGE__->add_columns(qw/trackid cd position title/);
1523 __PACKAGE__->set_primary_key('trackid');
1524 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1527 # In your application
1528 my $rs = $schema->resultset('Artist')->search(
1529 { 'track.title' => 'Teardrop' },
1531 join => { cd => 'track' },
1532 order_by => 'artist.name',
1536 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1537 similarly for a third time). For e.g.
1539 my $rs = $schema->resultset('Artist')->search({
1540 'cds.title' => 'Down to Earth',
1541 'cds_2.title' => 'Popular',
1543 join => [ qw/cds cds/ ],
1546 will return a set of all artists that have both a cd with title 'Down
1547 to Earth' and a cd with title 'Popular'.
1549 If you want to fetch related objects from other tables as well, see C<prefetch>
1556 =item Value: ($rel_name | \@rel_names | \%rel_names)
1560 Contains one or more relationships that should be fetched along with the main
1561 query (when they are accessed afterwards they will have already been
1562 "prefetched"). This is useful for when you know you will need the related
1563 objects, because it saves at least one query:
1565 my $rs = $schema->resultset('Tag')->search(
1574 The initial search results in SQL like the following:
1576 SELECT tag.*, cd.*, artist.* FROM tag
1577 JOIN cd ON tag.cd = cd.cdid
1578 JOIN artist ON cd.artist = artist.artistid
1580 L<DBIx::Class> has no need to go back to the database when we access the
1581 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1584 Simple prefetches will be joined automatically, so there is no need
1585 for a C<join> attribute in the above search. If you're prefetching to
1586 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1587 specify the join as well.
1589 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1590 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1591 with an accessor type of 'single' or 'filter').
1597 =item Value: \@from_clause
1601 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1602 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1605 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1606 C<join> will usually do what you need and it is strongly recommended that you
1607 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1609 In simple terms, C<from> works as follows:
1612 { <alias> => <table>, -join_type => 'inner|left|right' }
1613 [] # nested JOIN (optional)
1614 { <table.column> => <foreign_table.foreign_key> }
1620 ON <table.column> = <foreign_table.foreign_key>
1622 An easy way to follow the examples below is to remember the following:
1624 Anything inside "[]" is a JOIN
1625 Anything inside "{}" is a condition for the enclosing JOIN
1627 The following examples utilize a "person" table in a family tree application.
1628 In order to express parent->child relationships, this table is self-joined:
1630 # Person->belongs_to('father' => 'Person');
1631 # Person->belongs_to('mother' => 'Person');
1633 C<from> can be used to nest joins. Here we return all children with a father,
1634 then search against all mothers of those children:
1636 $rs = $schema->resultset('Person')->search(
1639 alias => 'mother', # alias columns in accordance with "from"
1641 { mother => 'person' },
1644 { child => 'person' },
1646 { father => 'person' },
1647 { 'father.person_id' => 'child.father_id' }
1650 { 'mother.person_id' => 'child.mother_id' }
1657 # SELECT mother.* FROM person mother
1660 # JOIN person father
1661 # ON ( father.person_id = child.father_id )
1663 # ON ( mother.person_id = child.mother_id )
1665 The type of any join can be controlled manually. To search against only people
1666 with a father in the person table, we could explicitly use C<INNER JOIN>:
1668 $rs = $schema->resultset('Person')->search(
1671 alias => 'child', # alias columns in accordance with "from"
1673 { child => 'person' },
1675 { father => 'person', -join_type => 'inner' },
1676 { 'father.id' => 'child.father_id' }
1683 # SELECT child.* FROM person child
1684 # INNER JOIN person father ON child.father_id = father.id
1694 Makes the resultset paged and specifies the page to retrieve. Effectively
1695 identical to creating a non-pages resultset and then calling ->page($page)
1706 Specifes the maximum number of rows for direct retrieval or the number of
1707 rows per page if the page attribute or method is used.
1713 =item Value: \@columns
1717 A arrayref of columns to group by. Can include columns of joined tables.
1719 group_by => [qw/ column1 column2 ... /]
1725 =item Value: $condition
1729 HAVING is a select statement attribute that is applied between GROUP BY and
1730 ORDER BY. It is applied to the after the grouping calculations have been
1733 having => { 'count(employee)' => { '>=', 100 } }
1739 =item Value: (0 | 1)
1743 Set to 1 to group by all columns.
1747 Set to 1 to cache search results. This prevents extra SQL queries if you
1748 revisit rows in your ResultSet:
1750 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1752 while( my $artist = $resultset->next ) {
1756 $rs->first; # without cache, this would issue a query
1758 By default, searches are not cached.
1760 For more examples of using these attributes, see
1761 L<DBIx::Class::Manual::Cookbook>.