1 package DBIx::Class::ResultSet;
12 DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
16 my $rs = MyApp::DB::Class->search(registered => 1);
17 my @rows = MyApp::DB::Class->search(foo => 'bar');
21 The resultset is also known as an iterator. It is responsible for handling
22 queries that may return an arbitrary number of rows, e.g. via C<search>
23 or a C<has_many> relationship.
27 =head2 new($db_class, \%$attrs)
29 The resultset constructor. Takes a table class and an attribute hash
30 (see below for more information on attributes). Does not perform
31 any queries -- these are executed as needed by the other methods.
36 my ($it_class, $db_class, $attrs) = @_;
37 #use Data::Dumper; warn Dumper(@_);
38 $it_class = ref $it_class if ref $it_class;
39 $attrs = { %{ $attrs || {} } };
41 $attrs->{cols} ||= [ map { "me.$_" } $db_class->_select_columns ];
42 $attrs->{from} ||= [ { 'me' => $db_class->_table_name } ];
44 foreach my $j (ref $attrs->{join} eq 'ARRAY'
45 ? (@{$attrs->{join}}) : ($attrs->{join})) {
46 if (ref $j eq 'HASH') {
47 $seen{$_} = 1 foreach keys %$j;
52 push(@{$attrs->{from}}, $db_class->_resolve_join($attrs->{join}, 'me'));
54 foreach my $pre (@{$attrs->{prefetch} || []}) {
55 push(@{$attrs->{from}}, $db_class->_resolve_join($pre, 'me'))
57 push(@{$attrs->{cols}},
59 $db_class->_relationships->{$pre}->{class}->_select_columns);
63 cols => $attrs->{cols} || [ $db_class->_select_columns ],
64 cond => $attrs->{where},
65 from => $attrs->{from} || $db_class->_table_name,
69 bless ($new, $it_class);
70 $new->pager if ($attrs->{page});
76 Return a storage-driven cursor to the given resultset.
82 my ($db_class, $attrs) = @{$self}{qw/class attrs/};
84 $attrs->{rows} = $self->pager->entries_per_page;
85 $attrs->{offset} = $self->pager->skipped;
87 return $self->{cursor}
88 ||= $db_class->storage->select($self->{from}, $self->{cols},
89 $attrs->{where},$attrs);
92 =head2 slice($first, $last)
94 Returns a subset of elements from the resultset.
99 my ($self, $min, $max) = @_;
100 my $attrs = { %{ $self->{attrs} || {} } };
101 $self->{class}->throw("Can't slice without where") unless $attrs->{where};
102 $attrs->{offset} = $min;
103 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
104 my $slice = $self->new($self->{class}, $attrs);
105 return (wantarray ? $slice->all : $slice);
110 Returns the next element in the resultset (undef is there is none).
116 my @row = $self->cursor->next;
117 return unless (@row);
118 return $self->_construct_object(@row);
121 sub _construct_object {
122 my ($self, @row) = @_;
123 my @cols = @{ $self->{attrs}{cols} };
125 @cols = grep { /\(/ or ! /\./ } @cols;
127 unless ($self->{attrs}{prefetch}) {
128 $new = $self->{class}->_row_to_object(\@cols, \@row);
130 my @main = splice(@row, 0, scalar @cols);
131 $new = $self->{class}->_row_to_object(\@cols, \@main);
132 PRE: foreach my $pre (@{$self->{attrs}{prefetch}}) {
133 my $rel_obj = $self->{class}->_relationships->{$pre};
134 my $pre_class = $self->{class}->resolve_class($rel_obj->{class});
135 my @pre_cols = $pre_class->_select_columns;
136 my @vals = splice(@row, 0, scalar @pre_cols);
137 my $fetched = $pre_class->_row_to_object(\@pre_cols, \@vals);
138 $self->{class}->throw("No accessor for prefetched $pre")
139 unless defined $rel_obj->{attrs}{accessor};
140 if ($rel_obj->{attrs}{accessor} eq 'single') {
141 foreach my $pri ($rel_obj->{class}->primary_columns) {
142 unless (defined $fetched->get_column($pri)) {
147 $new->{_relationship_data}{$pre} = $fetched;
148 } elsif ($rel_obj->{attrs}{accessor} eq 'filter') {
149 $new->{_inflated_column}{$pre} = $fetched;
151 $self->{class}->throw("Don't know how to store prefetched $pre");
155 $new = $self->{attrs}{record_filter}->($new)
156 if exists $self->{attrs}{record_filter};
162 Performs an SQL C<COUNT> with the same query as the resultset was built
163 with to find the number of elements.
169 my $db_class = $self->{class};
170 my $attrs = { %{ $self->{attrs} } };
171 unless ($self->{count}) {
172 # offset and order by are not needed to count
173 delete $attrs->{$_} for qw/offset order_by/;
175 my @cols = 'COUNT(*)';
176 $self->{count} = $db_class->storage->select_single($self->{from}, \@cols,
177 $self->{cond}, $attrs);
179 return 0 unless $self->{count};
180 return $self->{pager}->entries_on_this_page if ($self->{pager});
181 return ( $attrs->{rows} && $attrs->{rows} < $self->{count} )
188 Returns all elements in the resultset. Called implictly if the resultset
189 is returned in list context.
195 return map { $self->_construct_object(@$_); }
201 Resets the resultset's cursor, so you can iterate through the elements again.
207 $self->cursor->reset;
213 Resets the resultset and returns the first element.
218 return $_[0]->reset->next;
223 Deletes all elements in the resultset.
229 $_->delete for $self->all;
233 *delete_all = \&delete; # Yeah, yeah, yeah ...
237 Returns a L<Data::Page> object for the current resultset. Only makes
238 sense for queries with page turned on.
244 my $attrs = $self->{attrs};
245 delete $attrs->{offset};
246 my $rows_per_page = delete $attrs->{rows} || 10;
247 $self->{pager} ||= Data::Page->new(
248 $self->count, $rows_per_page, $attrs->{page} || 1);
249 $attrs->{rows} = $rows_per_page;
250 return $self->{pager};
253 =head2 page($page_num)
255 Returns a new resultset for the specified page.
260 my ($self, $page) = @_;
261 my $attrs = $self->{attrs};
262 $attrs->{page} = $page;
263 return $self->new($self->{class}, $attrs);
268 The resultset takes various attributes that modify its behavior.
269 Here's an overview of them:
273 Which column(s) to order the results by. This is currently passed
274 through directly to SQL, so you can give e.g. C<foo DESC> for a
279 Which columns should be retrieved.
283 Contains a list of relations that should be joined for this query. Can also
284 contain a hash reference to refer to that relation's relations. So, if one column
285 in your class C<belongs_to> foo and another C<belongs_to> bar, you can do
286 C<< join => [qw/ foo bar /] >> to join both (and e.g. use them for C<order_by>).
287 If a foo contains many margles and you want to join those too, you can do
288 C<< join => { foo => 'margle' } >>. If you want to fetch the columns from the
289 related table as well, see C<prefetch> below.
293 This attribute can contain a arrayref of elements. Each element can be another
294 arrayref, to nest joins, or it can be a hash which represents the two sides
297 NOTE: Use this on your own risk. This allows you to shoot your foot off!
301 For a paged resultset, specifies which page to retrieve. Leave unset
302 for an unpaged resultset.
306 For a paged resultset, how many rows per page