NAME
DBIx::Class::ResultSet - Responsible for fetching and creating resultset.
SYNOPSIS
my $rs = MyApp::DB::Class->search(registered => 1); my @rows = MyApp::DB::Class->search(foo => 'bar');
DESCRIPTION
The resultset is also known as an iterator. It is responsible for handling queries that may return an arbitrary number of rows, e.g. via search or a has_many relationship.
METHODS
new($source, \%$attrs)
The resultset constructor. Takes a source object (usually a DBIx::Class::Table) and an attribute hash (see below for more information on attributes). Does not perform any queries -- these are executed as needed by the other methods.
search
my @obj = $rs->search({ foo => 3 }); # "... WHERE foo = 3"
my $new_rs = $rs->search({ foo => 3 });
If you need to pass in additional attributes but no additional condition, call it as ->search(undef, \%attrs);
my @all = $class->search({}, { cols => [qw/foo bar/] }); # "SELECT foo, bar FROM $class_table"search_literal my @obj = $rs->search_literal($literal_where_cond, @bind); my $new_rs = $rs->search_literal($literal_where_cond, @bind);
Pass a literal chunk of SQL to be added to the conditional part of the resultset
find(@colvalues), find(\%cols)
Finds a row based on its primary key(s).
search_related
$rs->search_related('relname', $cond?, $attrs?);cursor
Returns a storage-driven cursor to the given resultset.
search_like
Identical to search except defaults to 'LIKE' instead of '=' in condition
slice($first, $last)
Returns a subset of elements from the resultset.
next
Returns the next element in the resultset (undef is there is none).
count
Performs an SQL COUNT with the same query as the resultset was built with to find the number of elements. If passed arguments, does a search on the resultset and counts the results of that.
count_literal
Calls search_literal with the passed arguments, then count.
all
Returns all elements in the resultset. Called implictly if the resultset is returned in list context.
reset
Resets the resultset's cursor, so you can iterate through the elements again.
first
Resets the resultset and returns the first element.
update(\%values)
Sets the specified columns in the resultset to the supplied values
update_all(\%values)
Fetches all objects and updates them one at a time. ->update_all will run cascade triggers, ->update will not.
delete
Deletes the contents of the resultset from its result source.
delete_all
Fetches all objects and deletes them one at a time. ->delete_all will run cascade triggers, ->delete will not.
pager
Returns a Data::Page object for the current resultset. Only makes sense for queries with page turned on.
page($page_num)
Returns a new resultset for the specified page.
new_result(\%vals)
Creates a result in the resultset's result class
create(\%vals)
Inserts a record into the resultset and returns the object
Effectively a shortcut for ->new_result(\%vals)->insert
find_or_create(\%vals)
$class->find_or_create({ key => $val, ... });
Searches for a record matching the search condition; if it doesn't find one, creates one and returns that instead.
ATTRIBUTES
The resultset takes various attributes that modify its behavior. Here's an overview of them:
order_by
Which column(s) to order the results by. This is currently passed through directly to SQL, so you can give e.g. foo DESC for a descending order.
cols (arrayref)
Shortcut to request a particular set of columns to be retrieved - adds 'me.' onto the start of any column without a '.' in it and sets 'select' from that, then auto-populates 'as' from 'select' as normal
select (arrayref)
Indicates which columns should be selected from the storage
as (arrayref)
Indicates column names for object inflation
join
Contains a list of relationships that should be joined for this query. Can also contain a hash reference to refer to that relation's relations. So, if one column in your class belongs_to foo and another belongs_to bar, you can do join => [qw/ foo bar /] to join both (and e.g. use them for order_by). If a foo contains many margles and you want to join those too, you can do join => { foo => 'margle' }. If you want to fetch the columns from the related table as well, see prefetch below.
prefetch
Contains a list of relationships that should be fetched along with the main query (when they are accessed afterwards they will have already been "prefetched"). This is useful for when you know you will need the related object(s), because it saves a query. Currently limited to prefetching one relationship deep, so unlike join, prefetch must be an arrayref.
from
This attribute can contain a arrayref of elements. Each element can be another arrayref, to nest joins, or it can be a hash which represents the two sides of the join.
NOTE: Use this on your own risk. This allows you to shoot your foot off!
page
For a paged resultset, specifies which page to retrieve. Leave unset for an unpaged resultset.
rows
For a paged resultset, how many rows per page
group_by
A list of columns to group by (note that 'count' doesn't work on grouped resultsets)
distinct
Set to 1 to group by all columns