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 relationships 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 Contains a list of relationships that should be fetched along with the main
294 query (when they are accessed afterwards they will have already been
295 "prefetched"). This is useful for when you know you will need the related
296 object(s), because it saves a query. Currently limited to prefetching
297 one relationship deep, so unlike C<join>, prefetch must be an arrayref.
301 This attribute can contain a arrayref of elements. Each element can be another
302 arrayref, to nest joins, or it can be a hash which represents the two sides
305 NOTE: Use this on your own risk. This allows you to shoot your foot off!
309 For a paged resultset, specifies which page to retrieve. Leave unset
310 for an unpaged resultset.
314 For a paged resultset, how many rows per page