1 package DBIx::Class::ResultSet;
12 use base qw/DBIx::Class/;
13 __PACKAGE__->load_components(qw/AccessorGroup/);
14 __PACKAGE__->mk_group_accessors('simple' => qw/result_source result_class/);
18 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
22 my $rs = $schema->resultset('User')->search(registered => 1);
23 my @rows = $schema->resultset('Foo')->search(bar => 'baz');
27 The resultset is also known as an iterator. It is responsible for handling
28 queries that may return an arbitrary number of rows, e.g. via L</search>
29 or a C<has_many> relationship.
31 In the examples below, the following table classes are used:
33 package MyApp::Schema::Artist;
34 use base qw/DBIx::Class/;
35 __PACKAGE__->load_components(qw/Core/);
36 __PACKAGE__->table('artist');
37 __PACKAGE__->add_columns(qw/artistid name/);
38 __PACKAGE__->set_primary_key('artistid');
39 __PACKAGE__->has_many(cds => 'MyApp::Schema::CD');
42 package MyApp::Schema::CD;
43 use base qw/DBIx::Class/;
44 __PACKAGE__->load_components(qw/Core/);
45 __PACKAGE__->table('cd');
46 __PACKAGE__->add_columns(qw/cdid artist title year/);
47 __PACKAGE__->set_primary_key('cdid');
48 __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
55 =head3 Arguments: ($source, \%$attrs)
57 The resultset constructor. Takes a source object (usually a
58 L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see L</ATTRIBUTES>
59 below). Does not perform any queries -- these are executed as needed by the
62 Generally you won't need to construct a resultset manually. You'll
63 automatically get one from e.g. a L</search> called in scalar context:
65 my $rs = $schema->resultset('CD')->search({ title => '100th Window' });
71 return $class->new_result(@_) if ref $class;
72 my ($source, $attrs) = @_;
73 #use Data::Dumper; warn Dumper($attrs);
74 $attrs = Storable::dclone($attrs || {}); # { %{ $attrs || {} } };
76 my $alias = ($attrs->{alias} ||= 'me');
77 if ($attrs->{cols} || !$attrs->{select}) {
78 delete $attrs->{as} if $attrs->{cols};
79 my @cols = ($attrs->{cols}
80 ? @{delete $attrs->{cols}}
82 $attrs->{select} = [ map { m/\./ ? $_ : "${alias}.$_" } @cols ];
84 $attrs->{as} ||= [ map { m/^$alias\.(.*)$/ ? $1 : $_ } @{$attrs->{select}} ];
85 if (my $include = delete $attrs->{include_columns}) {
86 push(@{$attrs->{select}}, @$include);
87 push(@{$attrs->{as}}, map { m/([^\.]+)$/; $1; } @$include);
89 #use Data::Dumper; warn Dumper(@{$attrs}{qw/select as/});
90 $attrs->{from} ||= [ { $alias => $source->from } ];
91 $attrs->{seen_join} ||= {};
92 if (my $join = delete $attrs->{join}) {
93 foreach my $j (ref $join eq 'ARRAY'
94 ? (@{$join}) : ($join)) {
95 if (ref $j eq 'HASH') {
96 $seen{$_} = 1 foreach keys %$j;
101 push(@{$attrs->{from}}, $source->resolve_join($join, $attrs->{alias}, $attrs->{seen_join}));
103 $attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
105 $attrs->{order_by} = [ $attrs->{order_by} ]
106 if $attrs->{order_by} && !ref($attrs->{order_by});
107 $attrs->{order_by} ||= [];
111 if (my $prefetch = delete $attrs->{prefetch}) {
113 foreach my $p (ref $prefetch eq 'ARRAY'
114 ? (@{$prefetch}) : ($prefetch)) {
115 if( ref $p eq 'HASH' ) {
116 foreach my $key (keys %$p) {
117 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
122 push(@{$attrs->{from}}, $source->resolve_join($p, $attrs->{alias}))
125 my @prefetch = $source->resolve_prefetch(
126 $p, $attrs->{alias}, {}, \@pre_order, $collapse);
128 push(@{$attrs->{select}}, map { $_->[0] } @prefetch);
129 push(@{$attrs->{as}}, map { $_->[1] } @prefetch);
131 push(@{$attrs->{order_by}}, @pre_order);
134 if ($attrs->{page}) {
135 $attrs->{rows} ||= 10;
136 $attrs->{offset} ||= 0;
137 $attrs->{offset} += ($attrs->{rows} * ($attrs->{page} - 1));
140 #if (keys %{$collapse}) {
141 # use Data::Dumper; warn Dumper($collapse);
145 result_source => $source,
146 result_class => $attrs->{result_class} || $source->result_class,
147 cond => $attrs->{where},
148 from => $attrs->{from},
149 collapse => $collapse,
151 page => delete $attrs->{page},
154 bless ($new, $class);
160 my @obj = $rs->search({ foo => 3 }); # "... WHERE foo = 3"
161 my $new_rs = $rs->search({ foo => 3 });
163 If you need to pass in additional attributes but no additional condition,
164 call it as C<search({}, \%attrs);>.
166 # "SELECT foo, bar FROM $class_table"
167 my @all = $class->search({}, { cols => [qw/foo bar/] });
177 my $attrs = { %{$self->{attrs}} };
178 my $having = delete $attrs->{having};
179 if (@_ > 1 && ref $_[$#_] eq 'HASH') {
180 $attrs = { %$attrs, %{ pop(@_) } };
184 ? ((@_ == 1 || ref $_[0] eq "HASH")
187 ? $self->throw_exception(
188 "Odd number of arguments to search")
191 if (defined $where) {
192 $where = (defined $attrs->{where}
194 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
195 $where, $attrs->{where} ] }
197 $attrs->{where} = $where;
200 if (defined $having) {
201 $having = (defined $attrs->{having}
203 [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
204 $having, $attrs->{having} ] }
206 $attrs->{having} = $having;
209 $rs = (ref $self)->new($self->result_source, $attrs);
215 return (wantarray ? $rs->all : $rs);
218 =head2 search_literal
220 my @obj = $rs->search_literal($literal_where_cond, @bind);
221 my $new_rs = $rs->search_literal($literal_where_cond, @bind);
223 Pass a literal chunk of SQL to be added to the conditional part of the
229 my ($self, $cond, @vals) = @_;
230 my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
231 $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
232 return $self->search(\$cond, $attrs);
237 =head3 Arguments: (@colvalues) | (\%cols, \%attrs?)
239 Finds a row based on its primary key or unique constraint. For example:
241 my $cd = $schema->resultset('CD')->find(5);
243 Also takes an optional C<key> attribute, to search by a specific key or unique
244 constraint. For example:
246 my $cd = $schema->resultset('CD')->find(
248 artist => 'Massive Attack',
249 title => 'Mezzanine',
251 { key => 'artist_title' }
254 See also L</find_or_create> and L</update_or_create>.
259 my ($self, @vals) = @_;
260 my $attrs = (@vals > 1 && ref $vals[$#vals] eq 'HASH' ? pop(@vals) : {});
262 my @cols = $self->result_source->primary_columns;
263 if (exists $attrs->{key}) {
264 my %uniq = $self->result_source->unique_constraints;
265 $self->( "Unknown key " . $attrs->{key} . " on " . $self->name )
266 unless exists $uniq{$attrs->{key}};
267 @cols = @{ $uniq{$attrs->{key}} };
269 #use Data::Dumper; warn Dumper($attrs, @vals, @cols);
270 $self->throw_exception( "Can't find unless a primary key or unique constraint is defined" )
274 if (ref $vals[0] eq 'HASH') {
275 $query = { %{$vals[0]} };
276 } elsif (@cols == @vals) {
278 @{$query}{@cols} = @vals;
282 foreach (keys %$query) {
284 $query->{$self->{attrs}{alias}.'.'.$_} = delete $query->{$_};
286 #warn Dumper($query);
288 ? $self->search($query,$attrs)->single
289 : $self->single($query));
292 =head2 search_related
294 $rs->search_related('relname', $cond?, $attrs?);
296 Search the specified relationship. Optionally specify a condition for matching
302 return shift->related_resultset(shift)->search(@_);
307 Returns a storage-driven cursor to the given resultset.
313 my ($attrs) = $self->{attrs};
314 $attrs = { %$attrs };
315 return $self->{cursor}
316 ||= $self->result_source->storage->select($self->{from}, $attrs->{select},
317 $attrs->{where},$attrs);
322 Inflates the first result without creating a cursor
327 my ($self, $extra) = @_;
328 my ($attrs) = $self->{attrs};
329 $attrs = { %$attrs };
331 if (defined $attrs->{where}) {
334 => [ map { ref $_ eq 'ARRAY' ? [ -or => $_ ] : $_ }
335 delete $attrs->{where}, $extra ]
338 $attrs->{where} = $extra;
341 my @data = $self->result_source->storage->select_single(
342 $self->{from}, $attrs->{select},
343 $attrs->{where},$attrs);
344 return (@data ? $self->_construct_object(@data) : ());
350 Perform a search, but use C<LIKE> instead of equality as the condition. Note
351 that this is simply a convenience method; you most likely want to use
352 L</search> with specific operators.
354 For more information, see L<DBIx::Class::Manual::Cookbook>.
361 if (@_ > 1 && ref $_[$#_] eq 'HASH') {
364 my $query = ref $_[0] eq "HASH" ? { %{shift()} }: {@_};
365 $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
366 return $class->search($query, { %$attrs });
371 =head3 Arguments: ($first, $last)
373 Returns a subset of elements from the resultset.
378 my ($self, $min, $max) = @_;
379 my $attrs = { %{ $self->{attrs} || {} } };
380 $attrs->{offset} ||= 0;
381 $attrs->{offset} += $min;
382 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
383 my $slice = (ref $self)->new($self->result_source, $attrs);
384 return (wantarray ? $slice->all : $slice);
389 Returns the next element in the resultset (C<undef> is there is none).
391 Can be used to efficiently iterate over records in the resultset:
393 my $rs = $schema->resultset('CD')->search({});
394 while (my $cd = $rs->next) {
403 if( @{$cache = $self->{all_cache} || []}) {
404 $self->{all_cache_position} ||= 0;
405 my $obj = $cache->[$self->{all_cache_position}];
406 $self->{all_cache_position}++;
409 if ($self->{attrs}{cache}) {
410 $self->{all_cache_position} = 1;
411 return ($self->all)[0];
413 my @row = (exists $self->{stashed_row}
414 ? @{delete $self->{stashed_row}}
415 : $self->cursor->next);
416 # warn Dumper(\@row); use Data::Dumper;
417 return unless (@row);
418 return $self->_construct_object(@row);
421 sub _construct_object {
422 my ($self, @row) = @_;
423 my @as = @{ $self->{attrs}{as} };
425 my $info = $self->_collapse_result(\@as, \@row);
427 #use Data::Dumper; warn Dumper(\@as, $info);
428 my $new = $self->result_class->inflate_result($self->result_source, @$info);
430 $new = $self->{attrs}{record_filter}->($new)
431 if exists $self->{attrs}{record_filter};
436 sub _collapse_result {
437 my ($self, $as, $row, $prefix) = @_;
442 foreach my $as (@$as) {
443 if (defined $prefix && !($as =~ s/\Q${prefix}\E\.//)) {
447 $as =~ /^(?:(.*)\.)?([^\.]+)$/;
448 $const{$1||''}{$2} = shift @copy;
451 #warn "@cols -> @row";
452 my $info = [ {}, {} ];
453 foreach my $key (keys %const) {
456 my @parts = split(/\./, $key);
457 foreach my $p (@parts) {
458 $target = $target->[1]->{$p} ||= [];
460 $target->[0] = $const{$key};
462 $info->[0] = $const{$key};
466 if (!defined($prefix) && keys %{$self->{collapse}}) {
467 my ($c) = sort { length $a <=> length $b } keys %{$self->{collapse}};
468 #warn "Collapsing ${c}";
470 #warn Data::Dumper::Dumper($target);
471 foreach my $p (split(/\./, $c)) {
472 $target = $target->[1]->{$p};
474 my @co_key = @{$self->{collapse}{$c}};
475 my %co_check = map { ($_, $target->[0]->{$_}); } @co_key;
476 my $tree = $self->_collapse_result($as, $row, $c);
477 #warn Data::Dumper::Dumper($target);
479 while ( !(grep { $co_check{$_} ne $tree->[0]->{$_} } @co_key) ) {
481 last unless (@raw = $self->cursor->next);
482 $row = $self->{stashed_row} = \@raw;
483 $tree = $self->_collapse_result($as, $row, $c);
486 #warn Data::Dumper::Dumper($target);
496 Returns a reference to the result source for this recordset.
503 Performs an SQL C<COUNT> with the same query as the resultset was built
504 with to find the number of elements. If passed arguments, does a search
505 on the resultset and counts the results of that.
507 Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
508 using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
509 not support C<DISTINCT> with multiple columns. If you are using such a
510 database, you should only use columns from the main table in your C<group_by>
517 return $self->search(@_)->count if @_ && defined $_[0];
518 unless (defined $self->{count}) {
519 return scalar @{ $self->get_cache }
520 if @{ $self->get_cache };
522 my $select = { 'count' => '*' };
523 my $attrs = { %{ $self->{attrs} } };
524 if( $group_by = delete $attrs->{group_by} ) {
525 delete $attrs->{having};
526 my @distinct = (ref $group_by ? @$group_by : ($group_by));
527 # todo: try CONCAT for multi-column pk
528 my @pk = $self->result_source->primary_columns;
529 if( scalar(@pk) == 1 ) {
531 my $alias = $attrs->{alias};
532 my $re = qr/^($alias\.)?$pk$/;
533 foreach my $column ( @distinct) {
534 if( $column =~ $re ) {
535 @distinct = ( $column );
541 $select = { count => { 'distinct' => \@distinct } };
542 #use Data::Dumper; die Dumper $select;
545 $attrs->{select} = $select;
546 $attrs->{as} = [ 'count' ];
547 # offset, order by and page are not needed to count. record_filter is cdbi
548 delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
550 ($self->{count}) = (ref $self)->new($self->result_source, $attrs)->cursor->next;
552 return 0 unless $self->{count};
553 my $count = $self->{count};
554 $count -= $self->{attrs}{offset} if $self->{attrs}{offset};
555 $count = $self->{attrs}{rows} if
556 ($self->{attrs}{rows} && $self->{attrs}{rows} < $count);
562 Calls L</search_literal> with the passed arguments, then L</count>.
566 sub count_literal { shift->search_literal(@_)->count; }
570 Returns all elements in the resultset. Called implictly if the resultset
571 is returned in list context.
577 return @{ $self->get_cache }
578 if @{ $self->get_cache };
579 if( $self->{attrs}->{cache} ) {
580 my @obj = map { $self->_construct_object(@$_); }
582 $self->set_cache( \@obj );
585 return map { $self->_construct_object(@$_); }
591 Resets the resultset's cursor, so you can iterate through the elements again.
597 $self->{all_cache_position} = 0;
598 $self->cursor->reset;
604 Resets the resultset and returns the first element.
609 return $_[0]->reset->next;
614 =head3 Arguments: (\%values)
616 Sets the specified columns in the resultset to the supplied values.
621 my ($self, $values) = @_;
622 $self->throw_exception("Values for update must be a hash") unless ref $values eq 'HASH';
623 return $self->result_source->storage->update(
624 $self->result_source->from, $values, $self->{cond});
629 =head3 Arguments: (\%values)
631 Fetches all objects and updates them one at a time. Note that C<update_all>
632 will run cascade triggers while L</update> will not.
637 my ($self, $values) = @_;
638 $self->throw_exception("Values for update must be a hash") unless ref $values eq 'HASH';
639 foreach my $obj ($self->all) {
640 $obj->set_columns($values)->update;
647 Deletes the contents of the resultset from its result source.
654 $self->throw_exception("Can't delete on resultset with condition unless hash or array")
655 unless (ref($self->{cond}) eq 'HASH' || ref($self->{cond}) eq 'ARRAY');
656 if (ref $self->{cond} eq 'ARRAY') {
657 $del = [ map { my %hash;
658 foreach my $key (keys %{$_}) {
660 $hash{$1} = $_->{$key};
661 }; \%hash; } @{$self->{cond}} ];
662 } elsif ((keys %{$self->{cond}})[0] eq '-and') {
663 $del->{-and} = [ map { my %hash;
664 foreach my $key (keys %{$_}) {
666 $hash{$1} = $_->{$key};
667 }; \%hash; } @{$self->{cond}{-and}} ];
669 foreach my $key (keys %{$self->{cond}}) {
671 $del->{$1} = $self->{cond}{$key};
674 $self->result_source->storage->delete($self->result_source->from, $del);
680 Fetches all objects and deletes them one at a time. Note that C<delete_all>
681 will run cascade triggers while L</delete> will not.
687 $_->delete for $self->all;
693 Returns a L<Data::Page> object for the current resultset. Only makes
694 sense for queries with a C<page> attribute.
700 my $attrs = $self->{attrs};
701 $self->throw_exception("Can't create pager for non-paged rs") unless $self->{page};
702 $attrs->{rows} ||= 10;
704 return $self->{pager} ||= Data::Page->new(
705 $self->{count}, $attrs->{rows}, $self->{page});
710 =head3 Arguments: ($page_num)
712 Returns a new resultset for the specified page.
717 my ($self, $page) = @_;
718 my $attrs = { %{$self->{attrs}} };
719 $attrs->{page} = $page;
720 return (ref $self)->new($self->result_source, $attrs);
725 =head3 Arguments: (\%vals)
727 Creates a result in the resultset's result class.
732 my ($self, $values) = @_;
733 $self->throw_exception( "new_result needs a hash" )
734 unless (ref $values eq 'HASH');
735 $self->throw_exception( "Can't abstract implicit construct, condition not a hash" )
736 if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
738 my $alias = $self->{attrs}{alias};
739 foreach my $key (keys %{$self->{cond}||{}}) {
740 $new{$1} = $self->{cond}{$key} if ($key =~ m/^(?:$alias\.)?([^\.]+)$/);
742 my $obj = $self->result_class->new(\%new);
743 $obj->result_source($self->result_source) if $obj->can('result_source');
749 =head3 Arguments: (\%vals)
751 Inserts a record into the resultset and returns the object.
753 Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
758 my ($self, $attrs) = @_;
759 $self->throw_exception( "create needs a hashref" ) unless ref $attrs eq 'HASH';
760 return $self->new_result($attrs)->insert;
763 =head2 find_or_create
765 =head3 Arguments: (\%vals, \%attrs?)
767 $class->find_or_create({ key => $val, ... });
769 Searches for a record matching the search condition; if it doesn't find one,
770 creates one and returns that instead.
772 my $cd = $schema->resultset('CD')->find_or_create({
774 artist => 'Massive Attack',
775 title => 'Mezzanine',
779 Also takes an optional C<key> attribute, to search by a specific key or unique
780 constraint. For example:
782 my $cd = $schema->resultset('CD')->find_or_create(
784 artist => 'Massive Attack',
785 title => 'Mezzanine',
787 { key => 'artist_title' }
790 See also L</find> and L</update_or_create>.
796 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
797 my $hash = ref $_[0] eq "HASH" ? shift : {@_};
798 my $exists = $self->find($hash, $attrs);
799 return defined($exists) ? $exists : $self->create($hash);
802 =head2 update_or_create
804 $class->update_or_create({ key => $val, ... });
806 First, search for an existing row matching one of the unique constraints
807 (including the primary key) on the source of this resultset. If a row is
808 found, update it with the other given column values. Otherwise, create a new
811 Takes an optional C<key> attribute to search on a specific unique constraint.
814 # In your application
815 my $cd = $schema->resultset('CD')->update_or_create(
817 artist => 'Massive Attack',
818 title => 'Mezzanine',
821 { key => 'artist_title' }
824 If no C<key> is specified, it searches on all unique constraints defined on the
825 source, including the primary key.
827 If the C<key> is specified as C<primary>, search only on the primary key.
829 See also L</find> and L</find_or_create>.
833 sub update_or_create {
836 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
837 my $hash = ref $_[0] eq "HASH" ? shift : {@_};
839 my %unique_constraints = $self->result_source->unique_constraints;
840 my @constraint_names = (exists $attrs->{key}
842 : keys %unique_constraints);
845 foreach my $name (@constraint_names) {
846 my @unique_cols = @{ $unique_constraints{$name} };
848 map { $_ => $hash->{$_} }
849 grep { exists $hash->{$_} }
852 push @unique_hashes, \%unique_hash
853 if (scalar keys %unique_hash == scalar @unique_cols);
857 if (@unique_hashes) {
858 $row = $self->search(\@unique_hashes, { rows => 1 })->first;
860 $row->set_columns($hash);
866 $row = $self->create($hash);
874 Gets the contents of the cache for the resultset.
880 return $self->{all_cache} || [];
885 Sets the contents of the cache for the resultset. Expects an arrayref of objects of the same class as those produced by the resultset.
890 my ( $self, $data ) = @_;
891 $self->throw_exception("set_cache requires an arrayref")
892 if ref $data ne 'ARRAY';
893 my $result_class = $self->result_class;
895 $self->throw_exception("cannot cache object of type '$_', expected '$result_class'")
896 if ref $_ ne $result_class;
898 $self->{all_cache} = $data;
903 Clears the cache for the resultset.
909 $self->set_cache([]);
912 =head2 related_resultset
914 Returns a related resultset for the supplied relationship name.
916 $rs = $rs->related_resultset('foo');
920 sub related_resultset {
921 my ( $self, $rel, @rest ) = @_;
922 $self->{related_resultsets} ||= {};
923 my $resultsets = $self->{related_resultsets};
924 if( !exists $resultsets->{$rel} ) {
925 #warn "fetching related resultset for rel '$rel'";
926 my $rel_obj = $self->result_source->relationship_info($rel);
927 $self->throw_exception(
928 "search_related: result source '" . $self->result_source->name .
929 "' has no such relationship ${rel}")
930 unless $rel_obj; #die Dumper $self->{attrs};
931 my $rs = $self->search(undef, { join => $rel });
932 #if( $self->{attrs}->{cache} ) {
933 # $rs = $self->search(undef);
937 #use Data::Dumper; die Dumper $rs->{attrs};#$rs = $self->search( undef );
938 #use Data::Dumper; warn Dumper $self->{attrs}, Dumper $rs->{attrs};
939 my $alias = (defined $rs->{attrs}{seen_join}{$rel}
940 && $rs->{attrs}{seen_join}{$rel} > 1
941 ? join('_', $rel, $rs->{attrs}{seen_join}{$rel})
943 $resultsets->{$rel} =
944 $self->result_source->schema->resultset($rel_obj->{class}
952 return $resultsets->{$rel};
955 =head2 throw_exception
957 See Schema's throw_exception
961 sub throw_exception {
963 $self->result_source->schema->throw_exception(@_);
968 The resultset takes various attributes that modify its behavior. Here's an
973 Which column(s) to order the results by. This is currently passed through
974 directly to SQL, so you can give e.g. C<foo DESC> for a descending order.
978 =head3 Arguments: (arrayref)
980 Shortcut to request a particular set of columns to be retrieved. Adds
981 C<me.> onto the start of any column without a C<.> in it and sets C<select>
982 from that, then auto-populates C<as> from C<select> as normal.
984 =head2 include_columns
986 =head3 Arguments: (arrayref)
988 Shortcut to include additional columns in the returned results - for example
990 { include_columns => ['foo.name'], join => ['foo'] }
992 would add a 'name' column to the information passed to object inflation
996 =head3 Arguments: (arrayref)
998 Indicates which columns should be selected from the storage. You can use
999 column names, or in the case of RDBMS back ends, function or stored procedure
1002 $rs = $schema->resultset('Foo')->search(
1007 { count => 'column_to_count' },
1008 { sum => 'column_to_sum' }
1013 When you use function/stored procedure names and do not supply an C<as>
1014 attribute, the column names returned are storage-dependent. E.g. MySQL would
1015 return a column named C<count(column_to_count)> in the above example.
1019 =head3 Arguments: (arrayref)
1021 Indicates column names for object inflation. This is used in conjunction with
1022 C<select>, usually when C<select> contains one or more function or stored
1025 $rs = $schema->resultset('Foo')->search(
1030 { count => 'column2' }
1032 as => [qw/ column1 column2_count /]
1036 my $foo = $rs->first(); # get the first Foo
1038 If the object against which the search is performed already has an accessor
1039 matching a column name specified in C<as>, the value can be retrieved using
1040 the accessor as normal:
1042 my $column1 = $foo->column1();
1044 If on the other hand an accessor does not exist in the object, you need to
1045 use C<get_column> instead:
1047 my $column2_count = $foo->get_column('column2_count');
1049 You can create your own accessors if required - see
1050 L<DBIx::Class::Manual::Cookbook> for details.
1054 Contains a list of relationships that should be joined for this query. For
1057 # Get CDs by Nine Inch Nails
1058 my $rs = $schema->resultset('CD')->search(
1059 { 'artist.name' => 'Nine Inch Nails' },
1060 { join => 'artist' }
1063 Can also contain a hash reference to refer to the other relation's relations.
1066 package MyApp::Schema::Track;
1067 use base qw/DBIx::Class/;
1068 __PACKAGE__->table('track');
1069 __PACKAGE__->add_columns(qw/trackid cd position title/);
1070 __PACKAGE__->set_primary_key('trackid');
1071 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
1074 # In your application
1075 my $rs = $schema->resultset('Artist')->search(
1076 { 'track.title' => 'Teardrop' },
1078 join => { cd => 'track' },
1079 order_by => 'artist.name',
1083 If the same join is supplied twice, it will be aliased to <rel>_2 (and
1084 similarly for a third time). For e.g.
1086 my $rs = $schema->resultset('Artist')->search(
1087 { 'cds.title' => 'Foo',
1088 'cds_2.title' => 'Bar' },
1089 { join => [ qw/cds cds/ ] });
1091 will return a set of all artists that have both a cd with title Foo and a cd
1094 If you want to fetch related objects from other tables as well, see C<prefetch>
1099 =head3 Arguments: arrayref/hashref
1101 Contains one or more relationships that should be fetched along with the main
1102 query (when they are accessed afterwards they will have already been
1103 "prefetched"). This is useful for when you know you will need the related
1104 objects, because it saves at least one query:
1106 my $rs = $schema->resultset('Tag')->search(
1115 The initial search results in SQL like the following:
1117 SELECT tag.*, cd.*, artist.* FROM tag
1118 JOIN cd ON tag.cd = cd.cdid
1119 JOIN artist ON cd.artist = artist.artistid
1121 L<DBIx::Class> has no need to go back to the database when we access the
1122 C<cd> or C<artist> relationships, which saves us two SQL statements in this
1125 Simple prefetches will be joined automatically, so there is no need
1126 for a C<join> attribute in the above search. If you're prefetching to
1127 depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
1128 specify the join as well.
1130 C<prefetch> can be used with the following relationship types: C<belongs_to>,
1131 C<has_one> (or if you're using C<add_relationship>, any relationship declared
1132 with an accessor type of 'single' or 'filter').
1136 =head3 Arguments: (arrayref)
1138 The C<from> attribute gives you manual control over the C<FROM> clause of SQL
1139 statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
1142 NOTE: Use this on your own risk. This allows you to shoot off your foot!
1143 C<join> will usually do what you need and it is strongly recommended that you
1144 avoid using C<from> unless you cannot achieve the desired result using C<join>.
1146 In simple terms, C<from> works as follows:
1149 { <alias> => <table>, -join-type => 'inner|left|right' }
1150 [] # nested JOIN (optional)
1151 { <table.column> = <foreign_table.foreign_key> }
1157 ON <table.column> = <foreign_table.foreign_key>
1159 An easy way to follow the examples below is to remember the following:
1161 Anything inside "[]" is a JOIN
1162 Anything inside "{}" is a condition for the enclosing JOIN
1164 The following examples utilize a "person" table in a family tree application.
1165 In order to express parent->child relationships, this table is self-joined:
1167 # Person->belongs_to('father' => 'Person');
1168 # Person->belongs_to('mother' => 'Person');
1170 C<from> can be used to nest joins. Here we return all children with a father,
1171 then search against all mothers of those children:
1173 $rs = $schema->resultset('Person')->search(
1176 alias => 'mother', # alias columns in accordance with "from"
1178 { mother => 'person' },
1181 { child => 'person' },
1183 { father => 'person' },
1184 { 'father.person_id' => 'child.father_id' }
1187 { 'mother.person_id' => 'child.mother_id' }
1194 # SELECT mother.* FROM person mother
1197 # JOIN person father
1198 # ON ( father.person_id = child.father_id )
1200 # ON ( mother.person_id = child.mother_id )
1202 The type of any join can be controlled manually. To search against only people
1203 with a father in the person table, we could explicitly use C<INNER JOIN>:
1205 $rs = $schema->resultset('Person')->search(
1208 alias => 'child', # alias columns in accordance with "from"
1210 { child => 'person' },
1212 { father => 'person', -join-type => 'inner' },
1213 { 'father.id' => 'child.father_id' }
1220 # SELECT child.* FROM person child
1221 # INNER JOIN person father ON child.father_id = father.id
1225 For a paged resultset, specifies which page to retrieve. Leave unset
1226 for an unpaged resultset.
1230 For a paged resultset, how many rows per page:
1234 Can also be used to simulate an SQL C<LIMIT>.
1238 =head3 Arguments: (arrayref)
1240 A arrayref of columns to group by. Can include columns of joined tables.
1242 group_by => [qw/ column1 column2 ... /]
1246 Set to 1 to group by all columns.
1248 For more examples of using these attributes, see
1249 L<DBIx::Class::Manual::Cookbook>.