1 package DBIx::Class::ResultSet;
12 use Scalar::Util qw/weaken/;
14 use DBIx::Class::ResultSetColumn;
15 use base qw/DBIx::Class/;
16 __PACKAGE__->load_components(qw/AccessorGroup/);
17 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
21 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
25 my $rs = $schema->resultset('User')->search(registered => 1);
26 my @rows = $schema->resultset('CD')->search(year => 2005);
30 The resultset is also known as an iterator. It is responsible for handling
31 queries that may return an arbitrary number of rows, e.g. via L</search>
32 or a C<has_many> relationship.
34 In the examples below, the following table classes are used:
36 package MyApp::Schema::Artist;
37 use base qw/DBIx::Class/;
38 __PACKAGE__->load_components(qw/Core/);
39 __PACKAGE__->table('artist');
40 __PACKAGE__->add_columns(qw/artistid name/);
41 __PACKAGE__->set_primary_key('artistid');
42 __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
45 package MyApp::Schema::CD;
46 use base qw/DBIx::Class/;
47 __PACKAGE__->load_components(qw/Core/);
48 __PACKAGE__->table('cd');
49 __PACKAGE__->add_columns(qw/cdid artist title year/);
50 __PACKAGE__->set_primary_key('cdid');
51 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
60 =item Arguments: $source, \%$attrs
62 =item Return Value: $rs
66 The resultset constructor. Takes a source object (usually a
67 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
68 L</ATTRIBUTES> below). Does not perform any queries -- these are
69 executed as needed by the other methods.
71 Generally you won't need to construct a resultset manually. You'll
72 automatically get one from e.g. a L</search> called in scalar context:
74 my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
76 IMPORTANT: If called on an object, proxies to new_result instead so
78 my $cd = $schema->resultset('CD')->new({ title => 'Spoon' });
80 will return a CD object, not a ResultSet.
86 return $class->new_result(@_) if ref $class;
88 my ($source, $attrs) = @_;
92 $attrs->{rows} ||= 10;
93 $attrs->{offset} ||= 0;
94 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
97 $attrs->{alias} ||= 'me';
100 result_source => $source,
101 result_class => $attrs->{result_class} || $source->result_class,
102 cond => $attrs->{where},
103 # from => $attrs->{from},
104 # collapse => $collapse,
106 page => delete $attrs->{page},
116 =item Arguments: $cond, \%attrs?
118 =item Return Value: $resultset (scalar context), @row_objs (list context)
122 my @cds = $cd_rs->search({ year => 2001 }); # "... WHERE year = 2001"
123 my $new_rs = $cd_rs->search({ year => 2005 });
125 my $new_rs = $cd_rs->search([ { year => 2005 }, { year => 2004 } ]);
126 # year = 2005 OR year = 2004
128 If you need to pass in additional attributes but no additional condition,
129 call it as C<search(undef, \%attrs)>.
131 # "SELECT name, artistid FROM $artist_table"
132 my @all_artists = $schema->resultset('Artist')->search(undef, {
133 columns => [qw/name artistid/],
140 my $rs = $self->search_rs( @_ );
141 return (wantarray ? $rs->all : $rs);
148 =item Arguments: $cond, \%attrs?
150 =item Return Value: $resultset
154 This method does the same exact thing as search() except it will
155 always return a resultset, even in list context.
162 my $our_attrs = { %{$self->{attrs}} };
163 my $having = delete $our_attrs->{having};
165 $attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
167 # merge new attrs into old
168 foreach my $key (qw/join prefetch/) {
169 next unless (exists $attrs->{$key});
170 if (exists $our_attrs->{$key}) {
171 $our_attrs->{$key} = $self->_merge_attr($our_attrs->{$key}, $attrs->{$key});
173 $our_attrs->{$key} = $attrs->{$key};
175 delete $attrs->{$key};
178 if (exists $our_attrs->{prefetch}) {
179 $our_attrs->{join} = $self->_merge_attr($our_attrs->{join}, $our_attrs->{prefetch}, 1);
182 my $new_attrs = { %{$our_attrs}, %{$attrs} };
184 # merge new where and having into old
186 ? ((@_ == 1 || ref $_[0] eq "HASH")
189 ? $self->throw_exception(
190 "Odd number of arguments to search")
193 if (defined $where) {
194 $new_attrs->{where} = (defined $new_attrs->{where}
196 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
197 $where, $new_attrs->{where} ] }
201 if (defined $having) {
202 $new_attrs->{having} = (defined $new_attrs->{having}
204 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
205 $having, $new_attrs->{having} ] }
209 my $rs = (ref $self)->new($self->result_source, $new_attrs);
210 $rs->{_parent_rs} = $self->{_parent_rs} if ($self->{_parent_rs}); #XXX - hack to pass through parent of related resultsets
212 unless (@_) { # no search, effectively just a clone
213 my $rows = $self->get_cache;
215 $rs->set_cache($rows);
222 =head2 search_literal
226 =item Arguments: $sql_fragment, @bind_values
228 =item Return Value: $resultset (scalar context), @row_objs (list context)
232 my @cds = $cd_rs->search_literal('year = ? AND title = ?', qw/2001 Reload/);
233 my $newrs = $artist_rs->search_literal('name = ?', 'Metallica');
235 Pass a literal chunk of SQL to be added to the conditional part of the
241 my ($self, $cond, @vals) = @_;
242 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
243 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
244 return $self->search(\$cond, $attrs);
251 =item Arguments: @values | \%cols, \%attrs?
253 =item Return Value: $row_object
257 Finds a row based on its primary key or unique constraint. For example, to find
258 a row by its primary key:
260 my $cd = $schema->resultset('CD')->find(5);
262 You can also find a row by a specific unique constraint using the C<key>
263 attribute. For example:
265 my $cd = $schema->resultset('CD')->find('Massive Attack', 'Mezzanine', { key => 'artist_title' });
267 Additionally, you can specify the columns explicitly by name:
269 my $cd = $schema->resultset('CD')->find(
271 artist => 'Massive Attack',
272 title => 'Mezzanine',
274 { key => 'artist_title' }
277 If no C<key> is specified and you explicitly name columns, it searches on all
278 unique constraints defined on the source, including the primary key.
280 If the C<key> is specified as C<primary>, it searches only on the primary key.
282 See also L</find_or_create> and L</update_or_create>. For information on how to
283 declare unique constraints, see
284 L<DBIx::Class::ResultSource/add_unique_constraint>.
290 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
292 # Parse out a hash from input
293 my @cols = exists $attrs->{key}
294 ? $self->result_source->unique_constraint_columns($attrs->{key})
295 : $self->result_source->primary_columns;
298 if (ref $_[0] eq 'HASH') {
299 $hash = { %{$_[0]} };
301 elsif (@_ == @cols) {
303 @{$hash}{@cols} = @_;
306 # For backwards compatibility
310 $self->throw_exception(
311 "Arguments to find must be a hashref or match the number of columns in the "
312 . (exists $attrs->{key} ? "$attrs->{key} unique constraint" : "primary key")
316 # Check the hash we just parsed against our source's unique constraints
317 my @constraint_names = exists $attrs->{key}
319 : $self->result_source->unique_constraint_names;
320 $self->throw_exception(
321 "Can't find unless a primary key or unique constraint is defined"
322 ) unless @constraint_names;
325 foreach my $name (@constraint_names) {
326 my @unique_cols = $self->result_source->unique_constraint_columns($name);
327 my $unique_query = $self->_build_unique_query($hash, \@unique_cols);
329 # Add the ResultSet's alias
330 foreach my $key (grep { ! m/\./ } keys %$unique_query) {
331 my $alias = $self->{attrs}->{alias};
332 $unique_query->{"$alias.$key"} = delete $unique_query->{$key};
335 push @unique_queries, $unique_query if %$unique_query;
338 # Handle cases where the ResultSet already defines the query
339 my $query = @unique_queries ? \@unique_queries : undef;
343 my $rs = $self->search($query, $attrs);
345 return keys %{$rs->{_attrs}->{collapse}} ? $rs->next : $rs->single;
349 return (keys %{$self->{_attrs}->{collapse}})
350 ? $self->search($query)->next
351 : $self->single($query);
355 # _build_unique_query
357 # Constrain the specified query hash based on the specified column names.
359 sub _build_unique_query {
360 my ($self, $query, $unique_cols) = @_;
363 map { $_ => $query->{$_} }
364 grep { exists $query->{$_} }
367 return \%unique_query;
370 =head2 search_related
374 =item Arguments: $cond, \%attrs?
376 =item Return Value: $new_resultset
380 $new_rs = $cd_rs->search_related('artist', {
384 Searches the specified relationship, optionally specifying a condition and
385 attributes for matching records. See L</ATTRIBUTES> for more information.
390 return shift->related_resultset(shift)->search(@_);
397 =item Arguments: none
399 =item Return Value: $cursor
403 Returns a storage-driven cursor to the given resultset. See
404 L<DBIx::Class::Cursor> for more information.
412 my $attrs = { %{$self->{_attrs}} };
413 return $self->{cursor}
414 ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select},
415 $attrs->{where},$attrs);
422 =item Arguments: $cond?
424 =item Return Value: $row_object?
428 my $cd = $schema->resultset('CD')->single({ year => 2001 });
430 Inflates the first result without creating a cursor if the resultset has
431 any records in it; if not returns nothing. Used by L</find> as an optimisation.
433 Can optionally take an additional condition *only* - this is a fast-code-path
434 method; if you need to add extra joins or similar call ->search and then
435 ->single without a condition on the $rs returned from that.
440 my ($self, $where) = @_;
442 my $attrs = { %{$self->{_attrs}} };
444 if (defined $attrs->{where}) {
447 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
448 $where, delete $attrs->{where} ]
451 $attrs->{where} = $where;
455 my @data = $self->result_source->storage->select_single(
456 $attrs->{from}, $attrs->{select},
457 $attrs->{where},$attrs);
458 return (@data ? $self->_construct_object(@data) : ());
465 =item Arguments: $cond?
467 =item Return Value: $resultsetcolumn
471 my $max_length = $rs->get_column('length')->max;
473 Returns a ResultSetColumn instance for $column based on $self
478 my ($self, $column) = @_;
480 my $new = DBIx::Class::ResultSetColumn->new($self, $column);
488 =item Arguments: $cond, \%attrs?
490 =item Return Value: $resultset (scalar context), @row_objs (list context)
494 # WHERE title LIKE '%blue%'
495 $cd_rs = $rs->search_like({ title => '%blue%'});
497 Performs a search, but uses C<LIKE> instead of C<=> as the condition. Note
498 that this is simply a convenience method. You most likely want to use
499 L</search> with specific operators.
501 For more information, see L<DBIx::Class::Manual::Cookbook>.
507 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
508 my $query = ref $_[0] eq 'HASH' ? { %{shift()} }: {@_};
509 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
510 return $class->search($query, { %$attrs });
517 =item Arguments: $first, $last
519 =item Return Value: $resultset (scalar context), @row_objs (list context)
523 Returns a resultset or object list representing a subset of elements from the
524 resultset slice is called on. Indexes are from 0, i.e., to get the first
527 my ($one, $two, $three) = $rs->slice(0, 2);
532 my ($self, $min, $max) = @_;
533 my $attrs = {}; # = { %{ $self->{attrs} || {} } };
534 $attrs->{offset} = $self->{attrs}{offset} || 0;
535 $attrs->{offset} += $min;
536 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
537 return $self->search(undef(), $attrs);
538 #my $slice = (ref $self)->new($self->result_source, $attrs);
539 #return (wantarray ? $slice->all : $slice);
546 =item Arguments: none
548 =item Return Value: $result?
552 Returns the next element in the resultset (C<undef> is there is none).
554 Can be used to efficiently iterate over records in the resultset:
556 my $rs = $schema->resultset('CD')->search;
557 while (my $cd = $rs->next) {
561 Note that you need to store the resultset object, and call C<next> on it.
562 Calling C<< resultset('Table')->next >> repeatedly will always return the
563 first record from the resultset.
569 if (my $cache = $self->get_cache) {
570 $self->{all_cache_position} ||= 0;
571 return $cache->[$self->{all_cache_position}++];
573 if ($self->{attrs}{cache}) {
574 $self->{all_cache_position} = 1;
575 return ($self->all)[0];
577 my @row = (exists $self->{stashed_row} ?
578 @{delete $self->{stashed_row}} :
581 return unless (@row);
582 return $self->_construct_object(@row);
588 return if(exists $self->{_attrs}); #return if _resolve has already been called
590 my $attrs = $self->{attrs};
591 my $source = ($self->{_parent_rs}) ? $self->{_parent_rs} : $self->{result_source};
593 # XXX - lose storable dclone
594 my $record_filter = delete $attrs->{record_filter} if (defined $attrs->{record_filter});
595 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
596 $attrs->{record_filter} = $record_filter if ($record_filter);
597 $self->{attrs}->{record_filter} = $record_filter if ($record_filter);
599 my $alias = $attrs->{alias};
601 $attrs->{columns} ||= delete $attrs->{cols} if $attrs->{cols};
602 delete $attrs->{as} if $attrs->{columns};
603 $attrs->{columns} ||= [ $self->{result_source}->columns ] unless $attrs->{select};
604 my $select_alias = ($self->{_parent_rs}) ? $self->{attrs}->{_live_join} : $alias;
606 map { m/\./ ? $_ : "${select_alias}.$_" } @{delete $attrs->{columns}}
607 ] if $attrs->{columns};
609 map { m/^\Q$alias.\E(.+)$/ ? $1 : $_ } @{$attrs->{select}}
611 if (my $include = delete $attrs->{include_columns}) {
612 push(@{$attrs->{select}}, @$include);
613 push(@{$attrs->{as}}, map { m/([^.]+)$/; $1; } @$include);
616 $attrs->{from} ||= [ { $alias => $source->from } ];
617 $attrs->{seen_join} ||= {};
619 if (my $join = delete $attrs->{join}) {
620 foreach my $j (ref $join eq 'ARRAY' ? @$join : ($join)) {
621 if (ref $j eq 'HASH') {
622 $seen{$_} = 1 foreach keys %$j;
628 push(@{$attrs->{from}}, $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join}));
630 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
631 $attrs->{order_by} = [ $attrs->{order_by} ] if
632 $attrs->{order_by} and !ref($attrs->{order_by});
633 $attrs->{order_by} ||= [];
635 my $collapse = $attrs->{collapse} || {};
636 if (my $prefetch = delete $attrs->{prefetch}) {
638 foreach my $p (ref $prefetch eq 'ARRAY' ? @$prefetch : ($prefetch)) {
639 if ( ref $p eq 'HASH' ) {
640 foreach my $key (keys %$p) {
641 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
645 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
648 my @prefetch = $source->resolve_prefetch(
649 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
650 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
651 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
653 push(@{$attrs->{order_by}}, @pre_order);
655 $attrs->{collapse} = $collapse;
656 $self->{_attrs} = $attrs;
660 my ($self, $a, $b, $is_prefetch) = @_;
663 if (ref $b eq 'HASH' && ref $a eq 'HASH') {
664 foreach my $key (keys %{$b}) {
665 if (exists $a->{$key}) {
666 $a->{$key} = $self->_merge_attr($a->{$key}, $b->{$key}, $is_prefetch);
668 $a->{$key} = delete $b->{$key};
673 $a = [$a] unless (ref $a eq 'ARRAY');
674 $b = [$b] unless (ref $b eq 'ARRAY');
679 foreach my $element (@{$_}) {
680 if (ref $element eq 'HASH') {
681 $hash = $self->_merge_attr($hash, $element, $is_prefetch);
682 } elsif (ref $element eq 'ARRAY') {
683 $array = [@{$array}, @{$element}];
685 if (($b == $_) && $is_prefetch) {
686 $self->_merge_array($array, $element, $is_prefetch);
688 push(@{$array}, $element);
694 if ((keys %{$hash}) && (scalar(@{$array} > 0))) {
695 return [$hash, @{$array}];
697 return (keys %{$hash}) ? $hash : $array;
703 my ($self, $a, $b) = @_;
705 $b = [$b] unless (ref $b eq 'ARRAY');
706 # add elements from @{$b} to @{$a} which aren't already in @{$a}
707 foreach my $b_element (@{$b}) {
708 push(@{$a}, $b_element) unless grep {$b_element eq $_} @{$a};
712 sub _construct_object {
713 my ($self, @row) = @_;
714 my @as = @{ $self->{_attrs}{as} };
716 my $info = $self->_collapse_result(\@as, \@row);
717 my $new = $self->result_class->inflate_result($self->result_source, @$info);
718 $new = $self->{_attrs}{record_filter}->($new)
719 if exists $self->{_attrs}{record_filter};
723 sub _collapse_result {
724 my ($self, $as, $row, $prefix) = @_;
726 my $live_join = $self->{attrs}->{_live_join} ||="";
730 foreach my $this_as (@$as) {
731 my $val = shift @copy;
732 if (defined $prefix) {
733 if ($this_as =~ m/^\Q${prefix}.\E(.+)$/) {
735 $remain =~ /^(?:(.*)\.)?([^.]+)$/;
736 $const{$1||''}{$2} = $val;
739 $this_as =~ /^(?:(.*)\.)?([^.]+)$/;
740 $const{$1||''}{$2} = $val;
744 my $info = [ {}, {} ];
745 foreach my $key (keys %const) {
746 if (length $key && $key ne $live_join) {
748 my @parts = split(/\./, $key);
749 foreach my $p (@parts) {
750 $target = $target->[1]->{$p} ||= [];
752 $target->[0] = $const{$key};
754 $info->[0] = $const{$key};
759 if (defined $prefix) {
761 m/^\Q${prefix}.\E(.+)$/ ? ($1) : ()
762 } keys %{$self->{_attrs}->{collapse}}
764 @collapse = keys %{$self->{_attrs}->{collapse}};
768 my ($c) = sort { length $a <=> length $b } @collapse;
770 foreach my $p (split(/\./, $c)) {
771 $target = $target->[1]->{$p} ||= [];
773 my $c_prefix = (defined($prefix) ? "${prefix}.${c}" : $c);
774 my @co_key = @{$self->{_attrs}->{collapse}{$c_prefix}};
775 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
776 my $tree = $self->_collapse_result($as, $row, $c_prefix);
779 !defined($tree->[0]->{$_}) ||
780 $co_check{$_} ne $tree->[0]->{$_}
783 last unless (@raw = $self->cursor->next);
784 $row = $self->{stashed_row} = \@raw;
785 $tree = $self->_collapse_result($as, $row, $c_prefix);
787 @$target = (@final ? @final : [ {}, {} ]);
788 # single empty result to indicate an empty prefetched has_many
797 =item Arguments: $result_source?
799 =item Return Value: $result_source
803 An accessor for the primary ResultSource object from which this ResultSet
813 =item Arguments: $cond, \%attrs??
815 =item Return Value: $count
819 Performs an SQL C<COUNT> with the same query as the resultset was built
820 with to find the number of elements. If passed arguments, does a search
821 on the resultset and counts the results of that.
823 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
824 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
825 not support C<DISTINCT> with multiple columns. If you are using such a
826 database, you should only use columns from the main table in your C<group_by>
833 return $self->search(@_)->count if @_ and defined $_[0];
834 return scalar @{ $self->get_cache } if $self->get_cache;
836 my $count = $self->_count;
837 return 0 unless $count;
839 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
840 $count = $self->{attrs}{rows} if
841 $self->{attrs}{rows} and $self->{attrs}{rows} < $count;
845 sub _count { # Separated out so pager can get the full count
847 my $select = { count => '*' };
850 my $attrs = { %{ $self->{_attrs} } };
851 if (my $group_by = delete $attrs->{group_by}) {
852 delete $attrs->{having};
853 my @distinct = (ref $group_by ? @$group_by : ($group_by));
854 # todo: try CONCAT for multi-column pk
855 my @pk = $self->result_source->primary_columns;
857 foreach my $column (@distinct) {
858 if ($column =~ qr/^(?:\Q$attrs->{alias}.\E)?$pk[0]$/) {
859 @distinct = ($column);
865 $select = { count => { distinct => \@distinct } };
868 $attrs->{select} = $select;
869 $attrs->{as} = [qw/count/];
871 # offset, order by and page are not needed to count. record_filter is cdbi
872 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
873 my ($count) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
881 =item Arguments: $sql_fragment, @bind_values
883 =item Return Value: $count
887 Counts the results in a literal query. Equivalent to calling L</search_literal>
888 with the passed arguments, then L</count>.
892 sub count_literal { shift->search_literal(@_)->count; }
898 =item Arguments: none
900 =item Return Value: @objects
904 Returns all elements in the resultset. Called implicitly if the resultset
905 is returned in list context.
911 return @{ $self->get_cache } if $self->get_cache;
915 # TODO: don't call resolve here
917 if (keys %{$self->{_attrs}->{collapse}}) {
918 # if ($self->{attrs}->{prefetch}) {
919 # Using $self->cursor->all is really just an optimisation.
920 # If we're collapsing has_many prefetches it probably makes
921 # very little difference, and this is cleaner than hacking
922 # _construct_object to survive the approach
923 my @row = $self->cursor->next;
925 push(@obj, $self->_construct_object(@row));
926 @row = (exists $self->{stashed_row}
927 ? @{delete $self->{stashed_row}}
928 : $self->cursor->next);
931 @obj = map { $self->_construct_object(@$_) } $self->cursor->all;
934 $self->set_cache(\@obj) if $self->{attrs}{cache};
942 =item Arguments: none
944 =item Return Value: $self
948 Resets the resultset's cursor, so you can iterate through the elements again.
954 delete $self->{_attrs} if (exists $self->{_attrs});
956 $self->{all_cache_position} = 0;
957 $self->cursor->reset;
965 =item Arguments: none
967 =item Return Value: $object?
971 Resets the resultset and returns an object for the first result (if the
972 resultset returns anything).
977 return $_[0]->reset->next;
980 # _cond_for_update_delete
982 # update/delete require the condition to be modified to handle
983 # the differing SQL syntax available. This transforms the $self->{cond}
984 # appropriately, returning the new condition.
986 sub _cond_for_update_delete {
990 if (!ref($self->{cond})) {
991 # No-op. No condition, we're updating/deleting everything
993 elsif (ref $self->{cond} eq 'ARRAY') {
997 foreach my $key (keys %{$_}) {
999 $hash{$1} = $_->{$key};
1005 elsif (ref $self->{cond} eq 'HASH') {
1006 if ((keys %{$self->{cond}})[0] eq '-and') {
1009 my @cond = @{$self->{cond}{-and}};
1010 for (my $i = 0; $i <= @cond - 1; $i++) {
1011 my $entry = $cond[$i];
1014 if (ref $entry eq 'HASH') {
1015 foreach my $key (keys %{$entry}) {
1017 $hash{$1} = $entry->{$key};
1021 $entry =~ /([^.]+)$/;
1022 $hash{$1} = $cond[++$i];
1025 push @{$cond->{-and}}, \%hash;
1029 foreach my $key (keys %{$self->{cond}}) {
1031 $cond->{$1} = $self->{cond}{$key};
1036 $self->throw_exception(
1037 "Can't update/delete on resultset with condition unless hash or array"
1049 =item Arguments: \%values
1051 =item Return Value: $storage_rv
1055 Sets the specified columns in the resultset to the supplied values in a
1056 single query. Return value will be true if the update succeeded or false
1057 if no records were updated; exact type of success value is storage-dependent.
1062 my ($self, $values) = @_;
1063 $self->throw_exception("Values for update must be a hash")
1064 unless ref $values eq 'HASH';
1066 my $cond = $self->_cond_for_update_delete;
1068 return $self->result_source->storage->update(
1069 $self->result_source->from, $values, $cond
1077 =item Arguments: \%values
1079 =item Return Value: 1
1083 Fetches all objects and updates them one at a time. Note that C<update_all>
1084 will run DBIC cascade triggers, while L</update> will not.
1089 my ($self, $values) = @_;
1090 $self->throw_exception("Values for update must be a hash")
1091 unless ref $values eq 'HASH';
1092 foreach my $obj ($self->all) {
1093 $obj->set_columns($values)->update;
1102 =item Arguments: none
1104 =item Return Value: 1
1108 Deletes the contents of the resultset from its result source. Note that this
1109 will not run DBIC cascade triggers. See L</delete_all> if you need triggers
1118 my $cond = $self->_cond_for_update_delete;
1120 $self->result_source->storage->delete($self->result_source->from, $cond);
1128 =item Arguments: none
1130 =item Return Value: 1
1134 Fetches all objects and deletes them one at a time. Note that C<delete_all>
1135 will run DBIC cascade triggers, while L</delete> will not.
1141 $_->delete for $self->all;
1149 =item Arguments: none
1151 =item Return Value: $pager
1155 Return Value a L<Data::Page> object for the current resultset. Only makes
1156 sense for queries with a C<page> attribute.
1162 my $attrs = $self->{attrs};
1163 $self->throw_exception("Can't create pager for non-paged rs")
1164 unless $self->{page};
1165 $attrs->{rows} ||= 10;
1166 return $self->{pager} ||= Data::Page->new(
1167 $self->_count, $attrs->{rows}, $self->{page});
1174 =item Arguments: $page_number
1176 =item Return Value: $rs
1180 Returns a resultset for the $page_number page of the resultset on which page
1181 is called, where each page contains a number of rows equal to the 'rows'
1182 attribute set on the resultset (10 by default).
1187 my ($self, $page) = @_;
1188 my $attrs = { %{$self->{attrs}} };
1189 $attrs->{page} = $page;
1190 return (ref $self)->new($self->result_source, $attrs);
1197 =item Arguments: \%vals
1199 =item Return Value: $object
1203 Creates an object in the resultset's result class and returns it.
1208 my ($self, $values) = @_;
1209 $self->throw_exception( "new_result needs a hash" )
1210 unless (ref $values eq 'HASH');
1211 $self->throw_exception(
1212 "Can't abstract implicit construct, condition not a hash"
1213 ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
1215 my $alias = $self->{attrs}{alias};
1216 foreach my $key (keys %{$self->{cond}||{}}) {
1217 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:\Q${alias}.\E)?([^.]+)$/);
1219 my $obj = $self->result_class->new(\%new);
1220 $obj->result_source($self->result_source) if $obj->can('result_source');
1228 =item Arguments: \%vals, \%attrs?
1230 =item Return Value: $object
1234 Find an existing record from this resultset. If none exists, instantiate a new
1235 result object and return it. The object will not be saved into your storage
1236 until you call L<DBIx::Class::Row/insert> on it.
1238 If you want objects to be saved immediately, use L</find_or_create> instead.
1244 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1245 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1246 my $exists = $self->find($hash, $attrs);
1247 return defined $exists ? $exists : $self->new_result($hash);
1254 =item Arguments: \%vals
1256 =item Return Value: $object
1260 Inserts a record into the resultset and returns the object representing it.
1262 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
1267 my ($self, $attrs) = @_;
1268 $self->throw_exception( "create needs a hashref" )
1269 unless ref $attrs eq 'HASH';
1270 return $self->new_result($attrs)->insert;
1273 =head2 find_or_create
1277 =item Arguments: \%vals, \%attrs?
1279 =item Return Value: $object
1283 $class->find_or_create({ key => $val, ... });
1285 Searches for a record matching the search condition; if it doesn't find one,
1286 creates one and returns that instead.
1288 my $cd = $schema->resultset('CD')->find_or_create({
1290 artist => 'Massive Attack',
1291 title => 'Mezzanine',
1295 Also takes an optional C<key> attribute, to search by a specific key or unique
1296 constraint. For example:
1298 my $cd = $schema->resultset('CD')->find_or_create(
1300 artist => 'Massive Attack',
1301 title => 'Mezzanine',
1303 { key => 'artist_title' }
1306 See also L</find> and L</update_or_create>. For information on how to declare
1307 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1311 sub find_or_create {
1313 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1314 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1315 my $exists = $self->find($hash, $attrs);
1316 return defined $exists ? $exists : $self->create($hash);
1319 =head2 update_or_create
1323 =item Arguments: \%col_values, { key => $unique_constraint }?
1325 =item Return Value: $object
1329 $class->update_or_create({ col => $val, ... });
1331 First, searches for an existing row matching one of the unique constraints
1332 (including the primary key) on the source of this resultset. If a row is
1333 found, updates it with the other given column values. Otherwise, creates a new
1336 Takes an optional C<key> attribute to search on a specific unique constraint.
1339 # In your application
1340 my $cd = $schema->resultset('CD')->update_or_create(
1342 artist => 'Massive Attack',
1343 title => 'Mezzanine',
1346 { key => 'artist_title' }
1349 If no C<key> is specified, it searches on all unique constraints defined on the
1350 source, including the primary key.
1352 If the C<key> is specified as C<primary>, it searches only on the primary key.
1354 See also L</find> and L</find_or_create>. For information on how to declare
1355 unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
1359 sub update_or_create {
1361 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
1362 my $hash = ref $_[0] eq 'HASH' ? shift : {@_};
1364 my $row = $self->find($hash, $attrs);
1366 $row->update($hash);
1370 return $self->create($hash);
1377 =item Arguments: none
1379 =item Return Value: \@cache_objects?
1383 Gets the contents of the cache for the resultset, if the cache is set.
1395 =item Arguments: \@cache_objects
1397 =item Return Value: \@cache_objects
1401 Sets the contents of the cache for the resultset. Expects an arrayref
1402 of objects of the same class as those produced by the resultset. Note that
1403 if the cache is set the resultset will return the cached objects rather
1404 than re-querying the database even if the cache attr is not set.
1409 my ( $self, $data ) = @_;
1410 $self->throw_exception("set_cache requires an arrayref")
1411 if defined($data) && (ref $data ne 'ARRAY');
1412 $self->{all_cache} = $data;
1419 =item Arguments: none
1421 =item Return Value: []
1425 Clears the cache for the resultset.
1430 shift->set_cache(undef);
1433 =head2 related_resultset
1437 =item Arguments: $relationship_name
1439 =item Return Value: $resultset
1443 Returns a related resultset for the supplied relationship name.
1445 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');
1449 sub related_resultset {
1450 my ( $self, $rel ) = @_;
1452 $self->{related_resultsets} ||= {};
1453 return $self->{related_resultsets}{$rel} ||= do {
1454 #warn "fetching related resultset for rel '$rel' " . $self->result_source->{name};
1455 my $rel_obj = $self->result_source->relationship_info($rel);
1456 $self->throw_exception(
1457 "search_related: result source '" . $self->result_source->name .
1458 "' has no such relationship ${rel}")
1459 unless $rel_obj; #die Dumper $self->{attrs};
1461 my $rs = $self->result_source->schema->resultset($rel_obj->{class}
1463 { %{$self->{attrs}},
1467 _live_join => $rel }
1470 # keep reference of the original resultset
1471 $rs->{_parent_rs} = $self->result_source;
1476 =head2 throw_exception
1478 See L<DBIx::Class::Schema/throw_exception> for details.
1482 sub throw_exception {
1484 $self->result_source->schema->throw_exception(@_);
1487 # XXX: FIXME: Attributes docs need clearing up
1491 The resultset takes various attributes that modify its behavior. Here's an
1498 =item Value: ($order_by | \@order_by)
1502 Which column(s) to order the results by. This is currently passed
1503 through directly to SQL, so you can give e.g. C<year DESC> for a
1504 descending order on the column `year'.
1510 =item Value: \@columns
1514 Shortcut to request a particular set of columns to be retrieved. Adds
1515 C<me.> onto the start of any column without a C<.> in it and sets C<select>
1516 from that, then auto-populates C<as> from C<select> as normal. (You may also
1517 use the C<cols> attribute, as in earlier versions of DBIC.)
1519 =head2 include_columns
1523 =item Value: \@columns
1527 Shortcut to include additional columns in the returned results - for example
1529 $schema->resultset('CD')->search(undef, {
1530 include_columns => ['artist.name'],
1534 would return all CDs and include a 'name' column to the information
1535 passed to object inflation
1541 =item Value: \@select_columns
1545 Indicates which columns should be selected from the storage. You can use
1546 column names, or in the case of RDBMS back ends, function or stored procedure
1549 $rs = $schema->resultset('Employee')->search(undef, {
1552 { count => 'employeeid' },
1557 When you use function/stored procedure names and do not supply an C<as>
1558 attribute, the column names returned are storage-dependent. E.g. MySQL would
1559 return a column named C<count(employeeid)> in the above example.
1565 =item Value: \@inflation_names
1569 Indicates column names for object inflation. This is used in conjunction with
1570 C<select>, usually when C<select> contains one or more function or stored
1573 $rs = $schema->resultset('Employee')->search(undef, {
1576 { count => 'employeeid' }
1578 as => ['name', 'employee_count'],
1581 my $employee = $rs->first(); # get the first Employee
1583 If the object against which the search is performed already has an accessor
1584 matching a column name specified in C<as>, the value can be retrieved using
1585 the accessor as normal:
1587 my $name = $employee->name();
1589 If on the other hand an accessor does not exist in the object, you need to
1590 use C<get_column> instead:
1592 my $employee_count = $employee->get_column('employee_count');
1594 You can create your own accessors if required - see
1595 L<DBIx::Class::Manual::Cookbook> for details.
1597 Please note: This will NOT insert an C<AS employee_count> into the SQL statement
1598 produced, it is used for internal access only. Thus attempting to use the accessor
1599 in an C<order_by> clause or similar will fail misrably.
1605 =item Value: ($rel_name | \@rel_names | \%rel_names)
1609 Contains a list of relationships that should be joined for this query. For
1612 # Get CDs by Nine Inch Nails
1613 my $rs = $schema->resultset('CD')->search(
1614 { 'artist.name' => 'Nine Inch Nails' },
1615 { join => 'artist' }
1618 Can also contain a hash reference to refer to the other relation's relations.
1621 package MyApp::Schema::Track;
1622 use base qw/DBIx::Class/;
1623 __PACKAGE__->table('track');
1624 __PACKAGE__->add_columns(qw/trackid cd position title/);
1625 __PACKAGE__->set_primary_key('trackid');
1626 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1629 # In your application
1630 my $rs = $schema->resultset('Artist')->search(
1631 { 'track.title' => 'Teardrop' },
1633 join => { cd => 'track' },
1634 order_by => 'artist.name',
1638 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1639 similarly for a third time). For e.g.
1641 my $rs = $schema->resultset('Artist')->search({
1642 'cds.title' => 'Down to Earth',
1643 'cds_2.title' => 'Popular',
1645 join => [ qw/cds cds/ ],
1648 will return a set of all artists that have both a cd with title 'Down
1649 to Earth' and a cd with title 'Popular'.
1651 If you want to fetch related objects from other tables as well, see C<prefetch>
1658 =item Value: ($rel_name | \@rel_names | \%rel_names)
1662 Contains one or more relationships that should be fetched along with the main
1663 query (when they are accessed afterwards they will have already been
1664 "prefetched"). This is useful for when you know you will need the related
1665 objects, because it saves at least one query:
1667 my $rs = $schema->resultset('Tag')->search(
1676 The initial search results in SQL like the following:
1678 SELECT tag.*, cd.*, artist.* FROM tag
1679 JOIN cd ON tag.cd = cd.cdid
1680 JOIN artist ON cd.artist = artist.artistid
1682 L<DBIx::Class> has no need to go back to the database when we access the
1683 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1686 Simple prefetches will be joined automatically, so there is no need
1687 for a C<join> attribute in the above search. If you're prefetching to
1688 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1689 specify the join as well.
1691 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1692 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1693 with an accessor type of 'single' or 'filter').
1703 Makes the resultset paged and specifies the page to retrieve. Effectively
1704 identical to creating a non-pages resultset and then calling ->page($page)
1715 Specifes the maximum number of rows for direct retrieval or the number of
1716 rows per page if the page attribute or method is used.
1722 =item Value: \@columns
1726 A arrayref of columns to group by. Can include columns of joined tables.
1728 group_by => [qw/ column1 column2 ... /]
1734 =item Value: $condition
1738 HAVING is a select statement attribute that is applied between GROUP BY and
1739 ORDER BY. It is applied to the after the grouping calculations have been
1742 having => { 'count(employee)' => { '>=', 100 } }
1748 =item Value: (0 | 1)
1752 Set to 1 to group by all columns.
1756 Set to 1 to cache search results. This prevents extra SQL queries if you
1757 revisit rows in your ResultSet:
1759 my $resultset = $schema->resultset('Artist')->search( undef, { cache => 1 } );
1761 while( my $artist = $resultset->next ) {
1765 $rs->first; # without cache, this would issue a query
1767 By default, searches are not cached.
1769 For more examples of using these attributes, see
1770 L<DBIx::Class::Manual::Cookbook>.
1776 =item Value: \@from_clause
1780 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1781 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1784 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1786 C<join> will usually do what you need and it is strongly recommended that you
1787 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1788 And we really do mean "cannot", not just tried and failed. Attempting to use
1789 this because you're having problems with C<join> is like trying to use x86
1790 ASM because you've got a syntax error in your C. Trust us on this.
1792 Now, if you're still really, really sure you need to use this (and if you're
1793 not 100% sure, ask the mailing list first), here's an explanation of how this
1796 The syntax is as follows -
1799 { <alias1> => <table1> },
1801 { <alias2> => <table2>, -join_type => 'inner|left|right' },
1802 [], # nested JOIN (optional)
1803 { <table1.column1> => <table2.column2>, ... (more conditions) },
1805 # More of the above [ ] may follow for additional joins
1812 ON <table1.column1> = <table2.column2>
1813 <more joins may follow>
1815 An easy way to follow the examples below is to remember the following:
1817 Anything inside "[]" is a JOIN
1818 Anything inside "{}" is a condition for the enclosing JOIN
1820 The following examples utilize a "person" table in a family tree application.
1821 In order to express parent->child relationships, this table is self-joined:
1823 # Person->belongs_to('father' => 'Person');
1824 # Person->belongs_to('mother' => 'Person');
1826 C<from> can be used to nest joins. Here we return all children with a father,
1827 then search against all mothers of those children:
1829 $rs = $schema->resultset('Person')->search(
1832 alias => 'mother', # alias columns in accordance with "from"
1834 { mother => 'person' },
1837 { child => 'person' },
1839 { father => 'person' },
1840 { 'father.person_id' => 'child.father_id' }
1843 { 'mother.person_id' => 'child.mother_id' }
1850 # SELECT mother.* FROM person mother
1853 # JOIN person father
1854 # ON ( father.person_id = child.father_id )
1856 # ON ( mother.person_id = child.mother_id )
1858 The type of any join can be controlled manually. To search against only people
1859 with a father in the person table, we could explicitly use C<INNER JOIN>:
1861 $rs = $schema->resultset('Person')->search(
1864 alias => 'child', # alias columns in accordance with "from"
1866 { child => 'person' },
1868 { father => 'person', -join_type => 'inner' },
1869 { 'father.id' => 'child.father_id' }
1876 # SELECT child.* FROM person child
1877 # INNER JOIN person father ON child.father_id = father.id