.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::ResultSet 3pm"
.TH DBIx::Class::ResultSet 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::ResultSet \- Represents a query used for fetching a set of results.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  my $users_rs = $schema\->resultset(\*(AqUser\*(Aq);
\&  while( $user = $users_rs\->next) {
\&    print $user\->username;
\&  }
\&
\&  my $registered_users_rs = $schema\->resultset(\*(AqUser\*(Aq)\->search({ registered => 1 });
\&  my @cds_in_2005 = $schema\->resultset(\*(AqCD\*(Aq)\->search({ year => 2005 })\->all();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A ResultSet is an object which stores a set of conditions representing
a query. It is the backbone of DBIx::Class (i.e. the really
important/useful bit).
.PP
No \s-1SQL\s0 is executed on the database when a ResultSet is created, it
just stores all the conditions needed to create the query.
.PP
A basic ResultSet representing the data of an entire table is returned
by calling \f(CW\*(C`resultset\*(C'\fR on a DBIx::Class::Schema and passing in a
Source name.
.PP
.Vb 1
\&  my $users_rs = $schema\->resultset(\*(AqUser\*(Aq);
.Ve
.PP
A new ResultSet is returned from calling \*(L"search\*(R" on an existing
ResultSet. The new one will contain all the conditions of the
original, plus any new conditions added in the \f(CW\*(C`search\*(C'\fR call.
.PP
A ResultSet also incorporates an implicit iterator. \*(L"next\*(R" and \*(L"reset\*(R"
can be used to walk through all the DBIx::Class::Rows the ResultSet
represents.
.PP
The query that the ResultSet represents is \fBonly\fR executed against
the database when these methods are called:
\&\*(L"find\*(R", \*(L"next\*(R", \*(L"all\*(R", \*(L"first\*(R", \*(L"single\*(R", \*(L"count\*(R".
.PP
If a resultset is used in a numeric context it returns the \*(L"count\*(R".
However, if it is used in a boolean context it is \fBalways\fR true.  So if
you want to check if a resultset has any results, you must use \f(CW\*(C`if $rs
!= 0\*(C'\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Chaining resultsets"
.IX Subsection "Chaining resultsets"
Let's say you've got a query that needs to be run to return some data
to the user. But, you have an authorization system in place that
prevents certain users from seeing certain information. So, you want
to construct the basic query in one method, but add constraints to it in
another.
.PP
.Vb 4
\&  sub get_data {
\&    my $self = shift;
\&    my $request = $self\->get_request; # Get a request object somehow.
\&    my $schema = $self\->result_source\->schema;
\&
\&    my $cd_rs = $schema\->resultset(\*(AqCD\*(Aq)\->search({
\&      title => $request\->param(\*(Aqtitle\*(Aq),
\&      year => $request\->param(\*(Aqyear\*(Aq),
\&    });
\&
\&    $cd_rs = $self\->apply_security_policy( $cd_rs );
\&
\&    return $cd_rs\->all();
\&  }
\&
\&  sub apply_security_policy {
\&    my $self = shift;
\&    my ($rs) = @_;
\&
\&    return $rs\->search({
\&      subversive => 0,
\&    });
\&  }
.Ve
.PP
\fIResolving conditions and attributes\fR
.IX Subsection "Resolving conditions and attributes"
.PP
When a resultset is chained from another resultset (e.g.:
\&\f(CW\*(C`my $new_rs = $old_rs\->search(\e%extra_cond, \e%attrs)\*(C'\fR), conditions
and attributes with the same keys need resolving.
.PP
If any of \*(L"columns\*(R", \*(L"select\*(R", \*(L"as\*(R" are present, they reset the
original selection, and start the selection \*(L"clean\*(R".
.PP
The \*(L"join\*(R", \*(L"prefetch\*(R", \*(L"+columns\*(R", \*(L"+select\*(R", \*(L"+as\*(R" attributes
are merged into the existing ones from the original resultset.
.PP
The \*(L"where\*(R" and \*(L"having\*(R" attributes, and any search conditions, are
merged with an \s-1SQL\s0 \f(CW\*(C`AND\*(C'\fR to the existing condition from the original
resultset.
.PP
All other attributes are overridden by any new ones supplied in the
search attributes.
.SS "Multiple queries"
.IX Subsection "Multiple queries"
Since a resultset just defines a query, you can do all sorts of
things with it with the same object.
.PP
.Vb 5
\&  # Don\*(Aqt hit the DB yet.
\&  my $cd_rs = $schema\->resultset(\*(AqCD\*(Aq)\->search({
\&    title => \*(Aqsomething\*(Aq,
\&    year => 2009,
\&  });
\&
\&  # Each of these hits the DB individually.
\&  my $count = $cd_rs\->count;
\&  my $most_recent = $cd_rs\->get_column(\*(Aqdate_released\*(Aq)\->max();
\&  my @records = $cd_rs\->all;
.Ve
.PP
And it's not just limited to \s-1SELECT\s0 statements.
.PP
.Vb 1
\&  $cd_rs\->delete();
.Ve
.PP
This is even cooler:
.PP
.Vb 1
\&  $cd_rs\->create({ artist => \*(AqFred\*(Aq });
.Ve
.PP
Which is the same as:
.PP
.Vb 5
\&  $schema\->resultset(\*(AqCD\*(Aq)\->create({
\&    title => \*(Aqsomething\*(Aq,
\&    year => 2009,
\&    artist => \*(AqFred\*(Aq
\&  });
.Ve
.PP
See: \*(L"search\*(R", \*(L"count\*(R", \*(L"get_column\*(R", \*(L"all\*(R", \*(L"create\*(R".
.SS "Custom ResultSet classes"
.IX Subsection "Custom ResultSet classes"
To add methods to your resultsets, you can subclass DBIx::Class::ResultSet, similar to:
.PP
.Vb 1
\&  package MyApp::Schema::ResultSet::User;
\&
\&  use strict;
\&  use warnings;
\&
\&  use base \*(AqDBIx::Class::ResultSet\*(Aq;
\&
\&  sub active {
\&    my $self = shift;
\&    $self\->search({ $self\->current_source_alias . \*(Aq.active\*(Aq => 1 });
\&  }
\&
\&  sub unverified {
\&    my $self = shift;
\&    $self\->search({ $self\->current_source_alias . \*(Aq.verified\*(Aq => 0 });
\&  }
\&
\&  sub created_n_days_ago {
\&    my ($self, $days_ago) = @_;
\&    $self\->search({
\&      $self\->current_source_alias . \*(Aq.create_date\*(Aq => {
\&        \*(Aq<=\*(Aq,
\&      $self\->result_source\->schema\->storage\->datetime_parser\->format_datetime(
\&        DateTime\->now( time_zone => \*(AqUTC\*(Aq )\->subtract( days => $days_ago )
\&      )}
\&    });
\&  }
\&
\&  sub users_to_warn { shift\->active\->unverified\->created_n_days_ago(7) }
\&
\&  1;
.Ve
.PP
See \*(L"load_namespaces\*(R" in DBIx::Class::Schema on how \s-1DBIC\s0 can discover and
automatically attach Result\-specific
ResulSet classes.
.PP
\fIResultSet subclassing with Moose and similar constructor-providers\fR
.IX Subsection "ResultSet subclassing with Moose and similar constructor-providers"
.PP
Using Moose or Moo in your ResultSet classes is usually overkill, but
you may find it useful if your ResultSets contain a lot of business logic
(e.g. \f(CW\*(C`has xml_parser\*(C'\fR, \f(CW\*(C`has json\*(C'\fR, etc) or if you just prefer to organize
your code via roles.
.PP
In order to write custom ResultSet classes with Moo you need to use the
following template. The \s-1BUILDARGS\s0 is necessary due to the
unusual signature of the constructor provided by \s-1DBIC\s0
 \f(CW\*(C`\->new($source, \e%args)\*(C'\fR.
.PP
.Vb 3
\&  use Moo;
\&  extends \*(AqDBIx::Class::ResultSet\*(Aq;
\&  sub BUILDARGS { $_[2] || {} } # ::RS::new() expects my ($class, $rsrc, $args) = @_
\&
\&  ...your code...
\&
\&  1;
.Ve
.PP
If you want to build your custom ResultSet classes with Moose, you need
a similar, though a little more elaborate template in order to interface the
inlining of the Moose\-provided
object constructor,
with the \s-1DBIC\s0 one.
.PP
.Vb 1
\&  package MyApp::Schema::ResultSet::User;
\&
\&  use Moose;
\&  use MooseX::NonMoose;
\&  extends \*(AqDBIx::Class::ResultSet\*(Aq;
\&
\&  sub BUILDARGS { $_[2] || {} } # ::RS::new() expects my ($class, $rsrc, $args) = @_
\&
\&  ...your code...
\&
\&  _\|_PACKAGE_\|_\->meta\->make_immutable;
\&
\&  1;
.Ve
.PP
The MooseX::NonMoose is necessary so that the Moose constructor does not
entirely overwrite the \s-1DBIC\s0 one (in contrast Moo does this automatically).
Alternatively, you can skip MooseX::NonMoose and get by with just Moose
instead by doing:
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->meta\->make_immutable(inline_constructor => 0);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.ie n .IP "Arguments: $source, \e%attrs?" 4
.el .IP "Arguments: \f(CW$source\fR, \e%attrs?" 4
.IX Item "Arguments: $source, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
The resultset constructor. Takes a source object (usually a
DBIx::Class::ResultSourceProxy::Table) and an attribute hash (see
\&\*(L"\s-1ATTRIBUTES\*(R"\s0 below).  Does not perform any queries \*(-- these are
executed as needed by the other methods.
.PP
Generally you never construct a resultset manually. Instead you get one
from e.g. a
\&\f(CW\*(C`$schema\->resultset(\*(Aq$source_name\*(Aq)\*(C'\fR
or \f(CW\*(C`$another_resultset\->search(...)\*(C'\fR (the later called in
scalar context):
.PP
.Vb 1
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search({ title => \*(Aq100th Window\*(Aq });
.Ve
.IP "\s-1WARNING\s0" 4
.IX Item "WARNING"
If called on an object, proxies to \*(L"new_result\*(R" instead, so
.Sp
.Vb 1
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->new({ title => \*(AqSpoon\*(Aq });
.Ve
.Sp
will return a \s-1CD\s0 object, not a ResultSet, and is equivalent to:
.Sp
.Vb 1
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->new_result({ title => \*(AqSpoon\*(Aq });
.Ve
.Sp
Please also keep in mind that many internals call \*(L"new_result\*(R" directly,
so overloading this method with the idea of intercepting new result object
creation \fBwill not work\fR. See also warning pertaining to \*(L"create\*(R".
.SS "search"
.IX Subsection "search"
.ie n .IP "Arguments: $cond | undef, \e%attrs?" 4
.el .IP "Arguments: \f(CW$cond\fR | undef, \e%attrs?" 4
.IX Item "Arguments: $cond | undef, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
.Vb 2
\&  my @cds    = $cd_rs\->search({ year => 2001 }); # "... WHERE year = 2001"
\&  my $new_rs = $cd_rs\->search({ year => 2005 });
\&
\&  my $new_rs = $cd_rs\->search([ { year => 2005 }, { year => 2004 } ]);
\&                 # year = 2005 OR year = 2004
.Ve
.PP
In list context, \f(CW\*(C`\->all()\*(C'\fR is called implicitly on the resultset, thus
returning a list of result objects instead.
To avoid that, use \*(L"search_rs\*(R".
.PP
If you need to pass in additional attributes but no additional condition,
call it as \f(CW\*(C`search(undef, \e%attrs)\*(C'\fR.
.PP
.Vb 4
\&  # "SELECT name, artistid FROM $artist_table"
\&  my @all_artists = $schema\->resultset(\*(AqArtist\*(Aq)\->search(undef, {
\&    columns => [qw/name artistid/],
\&  });
.Ve
.PP
For a list of attributes that can be passed to \f(CW\*(C`search\*(C'\fR, see
\&\*(L"\s-1ATTRIBUTES\*(R"\s0. For more examples of using this function, see
Searching. For a complete
documentation for the first argument, see
\&\*(L"\s-1WHERE CLAUSES\*(R"\s0 in SQL::Abstract::Classic and its extension
DBIx::Class::SQLMaker.
.PP
For more help on using joins with search, see DBIx::Class::Manual::Joining.
.PP
\fI\s-1CAVEAT\s0\fR
.IX Subsection "CAVEAT"
.PP
Note that \*(L"search\*(R" does not process/deflate any of the values passed in the
SQL::Abstract::Classic\-compatible search condition structure. This is unlike
other condition-bound methods \*(L"new_result\*(R", \*(L"create\*(R" and \*(L"find\*(R". The user
must ensure manually that any value passed to this method will stringify to
something the \s-1RDBMS\s0 knows how to deal with. A notable example is the handling
of DateTime objects, for more info see:
\&\*(L"Formatting DateTime objects in queries\*(R" in DBIx::Class::Manual::Cookbook.
.SS "search_rs"
.IX Subsection "search_rs"
.ie n .IP "Arguments: $cond, \e%attrs?" 4
.el .IP "Arguments: \f(CW$cond\fR, \e%attrs?" 4
.IX Item "Arguments: $cond, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
This method does the same exact thing as \fBsearch()\fR except it will
always return a resultset, even in list context.
.SS "search_literal"
.IX Subsection "search_literal"
\&\fB\s-1CAVEAT\s0\fR: \f(CW\*(C`search_literal\*(C'\fR is provided for Class::DBI compatibility and
should only be used in that context. \f(CW\*(C`search_literal\*(C'\fR is a convenience
method. It is equivalent to calling \f(CW\*(C`$schema\->search(\e[])\*(C'\fR, but if you
want to ensure columns are bound correctly, use \*(L"search\*(R".
.PP
See \*(L"\s-1SEARCHING\*(R"\s0 in DBIx::Class::Manual::Cookbook and
\&\*(L"Searching\*(R" in DBIx::Class::Manual::FAQ for searching techniques that do not
require \f(CW\*(C`search_literal\*(C'\fR.
.ie n .IP "Arguments: $sql_fragment, @standalone_bind_values" 4
.el .IP "Arguments: \f(CW$sql_fragment\fR, \f(CW@standalone_bind_values\fR" 4
.IX Item "Arguments: $sql_fragment, @standalone_bind_values"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
.Vb 2
\&  my @cds   = $cd_rs\->search_literal(\*(Aqyear = ? AND title = ?\*(Aq, qw/2001 Reload/);
\&  my $newrs = $artist_rs\->search_literal(\*(Aqname = ?\*(Aq, \*(AqMetallica\*(Aq);
.Ve
.PP
Pass a literal chunk of \s-1SQL\s0 to be added to the conditional part of the
resultset query.
.PP
Example of how to use \f(CW\*(C`search\*(C'\fR instead of \f(CW\*(C`search_literal\*(C'\fR
.PP
.Vb 2
\&  my @cds = $cd_rs\->search_literal(\*(Aqcdid = ? AND (artist = ? OR artist = ?)\*(Aq, (2, 1, 2));
\&  my @cds = $cd_rs\->search(\e[ \*(Aqcdid = ? AND (artist = ? OR artist = ?)\*(Aq, [ \*(Aqcdid\*(Aq, 2 ], [ \*(Aqartist\*(Aq, 1 ], [ \*(Aqartist\*(Aq, 2 ] ]);
.Ve
.SS "find"
.IX Subsection "find"
.ie n .IP "Arguments: \e%columns_values | @pk_values, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \e%columns_values | \f(CW@pk_values\fR, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: %columns_values | @pk_values, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result | undef" 4
.el .IP "Return Value: \f(CW$result\fR | undef" 4
.IX Item "Return Value: $result | undef"
.PD
.PP
Finds and returns a single row based on supplied criteria. Takes either a
hashref with the same format as \*(L"create\*(R" (including inference of foreign
keys from related objects), or a list of primary key values in the same
order as the primary columns
declaration on the \*(L"result_source\*(R".
.PP
In either case an attempt is made to combine conditions already existing on
the resultset with the condition passed to this method.
.PP
To aid with preparing the correct query for the storage you may supply the
\&\f(CW\*(C`key\*(C'\fR attribute, which is the name of a
unique constraint (the
unique constraint corresponding to the
primary columns is always named
\&\f(CW\*(C`primary\*(C'\fR). If the \f(CW\*(C`key\*(C'\fR attribute has been supplied, and \s-1DBIC\s0 is unable
to construct a query that satisfies the named unique constraint fully (
non-NULL values for each column member of the constraint) an exception is
thrown.
.PP
If no \f(CW\*(C`key\*(C'\fR is specified, the search is carried over all unique constraints
which are fully defined by the available condition.
.PP
If no such constraint is found, \f(CW\*(C`find\*(C'\fR currently defaults to a simple
\&\f(CW\*(C`search\->(\e%column_values)\*(C'\fR which may or may not do what you expect.
Note that this fallback behavior may be deprecated in further versions. If
you need to search with arbitrary conditions \- use \*(L"search\*(R". If the query
resulting from this fallback produces more than one row, a warning to the
effect is issued, though only the first row is constructed and returned as
\&\f(CW$result_object\fR.
.PP
In addition to \f(CW\*(C`key\*(C'\fR, \*(L"find\*(R" recognizes and applies standard
resultset attributes in the same way as \*(L"search\*(R" does.
.PP
Note that if you have extra concerns about the correctness of the resulting
query you need to specify the \f(CW\*(C`key\*(C'\fR attribute and supply the entire condition
as an argument to find (since it is not always possible to perform the
combination of the resultset condition with the supplied one, especially if
the resultset condition contains literal sql).
.PP
For example, to find a row by its primary key:
.PP
.Vb 1
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->find(5);
.Ve
.PP
You can also find a row by a specific unique constraint:
.PP
.Vb 7
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->find(
\&    {
\&      artist => \*(AqMassive Attack\*(Aq,
\&      title  => \*(AqMezzanine\*(Aq,
\&    },
\&    { key => \*(Aqcd_artist_title\*(Aq }
\&  );
.Ve
.PP
See also \*(L"find_or_create\*(R" and \*(L"update_or_create\*(R".
.SS "search_related"
.IX Subsection "search_related"
.ie n .IP "Arguments: $rel_name, $cond?, \e%attrs?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$cond\fR?, \e%attrs?" 4
.IX Item "Arguments: $rel_name, $cond?, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
.Vb 3
\&  $new_rs = $cd_rs\->search_related(\*(Aqartist\*(Aq, {
\&    name => \*(AqEmo\-R\-Us\*(Aq,
\&  });
.Ve
.PP
Searches the specified relationship, optionally specifying a condition and
attributes for matching records. See \*(L"\s-1ATTRIBUTES\*(R"\s0 for more information.
.PP
In list context, \f(CW\*(C`\->all()\*(C'\fR is called implicitly on the resultset, thus
returning a list of result objects instead. To avoid that, use \*(L"search_related_rs\*(R".
.PP
See also \*(L"search_related_rs\*(R".
.SS "search_related_rs"
.IX Subsection "search_related_rs"
This method works exactly the same as search_related, except that
it guarantees a resultset, even in list context.
.SS "cursor"
.IX Subsection "cursor"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $cursor" 4
.el .IP "Return Value: \f(CW$cursor\fR" 4
.IX Item "Return Value: $cursor"
.PD
.PP
Returns a storage-driven cursor to the given resultset. See
DBIx::Class::Cursor for more information.
.SS "single"
.IX Subsection "single"
.ie n .IP "Arguments: $cond?" 4
.el .IP "Arguments: \f(CW$cond\fR?" 4
.IX Item "Arguments: $cond?"
.PD 0
.ie n .IP "Return Value: $result | undef" 4
.el .IP "Return Value: \f(CW$result\fR | undef" 4
.IX Item "Return Value: $result | undef"
.PD
.PP
.Vb 1
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->single({ year => 2001 });
.Ve
.PP
Inflates the first result without creating a cursor if the resultset has
any records in it; if not returns \f(CW\*(C`undef\*(C'\fR. Used by \*(L"find\*(R" as a lean version
of \*(L"search\*(R".
.PP
While this method can take an optional search condition (just like \*(L"search\*(R")
being a fast-code-path it does not recognize search attributes. If you need to
add extra joins or similar, call \*(L"search\*(R" and then chain-call \*(L"single\*(R" on the
DBIx::Class::ResultSet returned.
.IP "\fBNote\fR" 4
.IX Item "Note"
As of 0.08100, this method enforces the assumption that the preceding
query returns only one row. If more than one row is returned, you will receive
a warning:
.Sp
.Vb 1
\&  Query returned more than one row
.Ve
.Sp
In this case, you should be using \*(L"next\*(R" or \*(L"find\*(R" instead, or if you really
know what you are doing, use the \*(L"rows\*(R" attribute to explicitly limit the size
of the resultset.
.Sp
This method will also throw an exception if it is called on a resultset prefetching
has_many, as such a prefetch implies fetching multiple rows from the database in
order to assemble the resulting object.
.SS "get_column"
.IX Subsection "get_column"
.ie n .IP "Arguments: $cond?" 4
.el .IP "Arguments: \f(CW$cond\fR?" 4
.IX Item "Arguments: $cond?"
.PD 0
.ie n .IP "Return Value: $resultsetcolumn" 4
.el .IP "Return Value: \f(CW$resultsetcolumn\fR" 4
.IX Item "Return Value: $resultsetcolumn"
.PD
.PP
.Vb 1
\&  my $max_length = $rs\->get_column(\*(Aqlength\*(Aq)\->max;
.Ve
.PP
Returns a DBIx::Class::ResultSetColumn instance for a column of the ResultSet.
.SS "search_like"
.IX Subsection "search_like"
.ie n .IP "Arguments: $cond, \e%attrs?" 4
.el .IP "Arguments: \f(CW$cond\fR, \e%attrs?" 4
.IX Item "Arguments: $cond, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
.Vb 2
\&  # WHERE title LIKE \*(Aq%blue%\*(Aq
\&  $cd_rs = $rs\->search_like({ title => \*(Aq%blue%\*(Aq});
.Ve
.PP
Performs a search, but uses \f(CW\*(C`LIKE\*(C'\fR instead of \f(CW\*(C`=\*(C'\fR as the condition. Note
that this is simply a convenience method retained for ex Class::DBI users.
You most likely want to use \*(L"search\*(R" with specific operators.
.PP
For more information, see DBIx::Class::Manual::Cookbook.
.PP
This method is deprecated and will be removed in 0.09. Use \fBsearch()\fR
instead. An example conversion is:
.PP
.Vb 1
\&  \->search_like({ foo => \*(Aqbar\*(Aq });
\&
\&  # Becomes
\&
\&  \->search({ foo => { like => \*(Aqbar\*(Aq } });
.Ve
.SS "slice"
.IX Subsection "slice"
.ie n .IP "Arguments: $first, $last" 4
.el .IP "Arguments: \f(CW$first\fR, \f(CW$last\fR" 4
.IX Item "Arguments: $first, $last"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
Returns a resultset or object list representing a subset of elements from the
resultset slice is called on. Indexes are from 0, i.e., to get the first
three records, call:
.PP
.Vb 1
\&  my ($one, $two, $three) = $rs\->slice(0, 2);
.Ve
.SS "next"
.IX Subsection "next"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $result | undef" 4
.el .IP "Return Value: \f(CW$result\fR | undef" 4
.IX Item "Return Value: $result | undef"
.PD
.PP
Returns the next element in the resultset (\f(CW\*(C`undef\*(C'\fR is there is none).
.PP
Can be used to efficiently iterate over records in the resultset:
.PP
.Vb 4
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search;
\&  while (my $cd = $rs\->next) {
\&    print $cd\->title;
\&  }
.Ve
.PP
Note that you need to store the resultset object, and call \f(CW\*(C`next\*(C'\fR on it.
Calling \f(CW\*(C`resultset(\*(AqTable\*(Aq)\->next\*(C'\fR repeatedly will always return the
first record from the resultset.
.SS "result_source"
.IX Subsection "result_source"
.ie n .IP "Arguments: $result_source?" 4
.el .IP "Arguments: \f(CW$result_source\fR?" 4
.IX Item "Arguments: $result_source?"
.PD 0
.ie n .IP "Return Value: $result_source" 4
.el .IP "Return Value: \f(CW$result_source\fR" 4
.IX Item "Return Value: $result_source"
.PD
.PP
An accessor for the primary ResultSource object from which this ResultSet
is derived.
.SS "result_class"
.IX Subsection "result_class"
.ie n .IP "Arguments: $result_class?" 4
.el .IP "Arguments: \f(CW$result_class\fR?" 4
.IX Item "Arguments: $result_class?"
.PD 0
.ie n .IP "Return Value: $result_class" 4
.el .IP "Return Value: \f(CW$result_class\fR" 4
.IX Item "Return Value: $result_class"
.PD
.PP
An accessor for the class to use when creating result objects. Defaults to
\&\f(CW\*(C`result_source\->result_class\*(C'\fR \- which in most cases is the name of the
\&\*(L"table\*(R" class.
.PP
Note that changing the result_class will also remove any components
that were originally loaded in the source class via
load_components.
Any overloaded methods in the original source class will not run.
.SS "count"
.IX Subsection "count"
.ie n .IP "Arguments: $cond, \e%attrs?" 4
.el .IP "Arguments: \f(CW$cond\fR, \e%attrs?" 4
.IX Item "Arguments: $cond, %attrs?"
.PD 0
.ie n .IP "Return Value: $count" 4
.el .IP "Return Value: \f(CW$count\fR" 4
.IX Item "Return Value: $count"
.PD
.PP
Performs an \s-1SQL\s0 \f(CW\*(C`COUNT\*(C'\fR with the same query as the resultset was built
with to find the number of elements. Passing arguments is equivalent to
\&\f(CW\*(C`$rs\->search ($cond, \e%attrs)\->count\*(C'\fR
.SS "count_rs"
.IX Subsection "count_rs"
.ie n .IP "Arguments: $cond, \e%attrs?" 4
.el .IP "Arguments: \f(CW$cond\fR, \e%attrs?" 4
.IX Item "Arguments: $cond, %attrs?"
.PD 0
.ie n .IP "Return Value: $count_rs" 4
.el .IP "Return Value: \f(CW$count_rs\fR" 4
.IX Item "Return Value: $count_rs"
.PD
.PP
Same as \*(L"count\*(R" but returns a DBIx::Class::ResultSetColumn object.
This can be very handy for subqueries:
.PP
.Vb 1
\&  \->search( { amount => $some_rs\->count_rs\->as_query } )
.Ve
.PP
As with regular resultsets the \s-1SQL\s0 query will be executed only after
the resultset is accessed via \*(L"next\*(R" or \*(L"all\*(R". That would return
the same single value obtainable via \*(L"count\*(R".
.SS "count_literal"
.IX Subsection "count_literal"
\&\fB\s-1CAVEAT\s0\fR: \f(CW\*(C`count_literal\*(C'\fR is provided for Class::DBI compatibility and
should only be used in that context. See \*(L"search_literal\*(R" for further info.
.ie n .IP "Arguments: $sql_fragment, @standalone_bind_values" 4
.el .IP "Arguments: \f(CW$sql_fragment\fR, \f(CW@standalone_bind_values\fR" 4
.IX Item "Arguments: $sql_fragment, @standalone_bind_values"
.PD 0
.ie n .IP "Return Value: $count" 4
.el .IP "Return Value: \f(CW$count\fR" 4
.IX Item "Return Value: $count"
.PD
.PP
Counts the results in a literal query. Equivalent to calling \*(L"search_literal\*(R"
with the passed arguments, then \*(L"count\*(R".
.SS "all"
.IX Subsection "all"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: @result_objs" 4
.el .IP "Return Value: \f(CW@result_objs\fR" 4
.IX Item "Return Value: @result_objs"
.PD
.PP
Returns all elements in the resultset.
.SS "reset"
.IX Subsection "reset"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $self" 4
.el .IP "Return Value: \f(CW$self\fR" 4
.IX Item "Return Value: $self"
.PD
.PP
Resets the resultset's cursor, so you can iterate through the elements again.
Implicitly resets the storage cursor, so a subsequent \*(L"next\*(R" will trigger
another query.
.SS "first"
.IX Subsection "first"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $result | undef" 4
.el .IP "Return Value: \f(CW$result\fR | undef" 4
.IX Item "Return Value: $result | undef"
.PD
.PP
Resets the resultset (causing a fresh query to storage) and returns
an object for the first result (or \f(CW\*(C`undef\*(C'\fR if the resultset is empty).
.SS "update"
.IX Subsection "update"
.IP "Arguments: \e%values" 4
.IX Item "Arguments: %values"
.PD 0
.ie n .IP "Return Value: $underlying_storage_rv" 4
.el .IP "Return Value: \f(CW$underlying_storage_rv\fR" 4
.IX Item "Return Value: $underlying_storage_rv"
.PD
.PP
Sets the specified columns in the resultset to the supplied values in a
single query. Note that this will not run any accessor/set_column/update
triggers, nor will it update any result object instances derived from this
resultset (this includes the contents of the resultset cache
if any). See \*(L"update_all\*(R" if you need to execute any on-update
triggers or cascades defined either by you or a
result component.
.PP
The return value is a pass through of what the underlying
storage backend returned, and may vary. See \*(L"execute\*(R" in \s-1DBI\s0 for the most
common case.
.PP
\fI\s-1CAVEAT\s0\fR
.IX Subsection "CAVEAT"
.PP
Note that \*(L"update\*(R" does not process/deflate any of the values passed in.
This is unlike the corresponding \*(L"update\*(R" in DBIx::Class::Row. The user must
ensure manually that any value passed to this method will stringify to
something the \s-1RDBMS\s0 knows how to deal with. A notable example is the
handling of DateTime objects, for more info see:
\&\*(L"Formatting DateTime objects in queries\*(R" in DBIx::Class::Manual::Cookbook.
.SS "update_all"
.IX Subsection "update_all"
.IP "Arguments: \e%values" 4
.IX Item "Arguments: %values"
.PD 0
.IP "Return Value: 1" 4
.IX Item "Return Value: 1"
.PD
.PP
Fetches all objects and updates them one at a time via
\&\*(L"update\*(R" in DBIx::Class::Row. Note that \f(CW\*(C`update_all\*(C'\fR will run \s-1DBIC\s0 defined
triggers, while \*(L"update\*(R" will not.
.SS "delete"
.IX Subsection "delete"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $underlying_storage_rv" 4
.el .IP "Return Value: \f(CW$underlying_storage_rv\fR" 4
.IX Item "Return Value: $underlying_storage_rv"
.PD
.PP
Deletes the rows matching this resultset in a single query. Note that this
will not run any delete triggers, nor will it alter the
in_storage status of any result object instances
derived from this resultset (this includes the contents of the
resultset cache if any). See \*(L"delete_all\*(R" if you need to
execute any on-delete triggers or cascades defined either by you or a
result component.
.PP
The return value is a pass through of what the underlying storage backend
returned, and may vary. See \*(L"execute\*(R" in \s-1DBI\s0 for the most common case.
.SS "delete_all"
.IX Subsection "delete_all"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: 1" 4
.IX Item "Return Value: 1"
.PD
.PP
Fetches all objects and deletes them one at a time via
\&\*(L"delete\*(R" in DBIx::Class::Row. Note that \f(CW\*(C`delete_all\*(C'\fR will run \s-1DBIC\s0 defined
triggers, while \*(L"delete\*(R" will not.
.SS "populate"
.IX Subsection "populate"
.IP "Arguments: [ \e@column_list, \e@row_values+ ] | [ \e%col_data+ ]" 4
.IX Item "Arguments: [ @column_list, @row_values+ ] | [ %col_data+ ]"
.PD 0
.ie n .IP "Return Value: \e@result_objects (scalar context) | @result_objects (list context)" 4
.el .IP "Return Value: \e@result_objects (scalar context) | \f(CW@result_objects\fR (list context)" 4
.IX Item "Return Value: @result_objects (scalar context) | @result_objects (list context)"
.PD
.PP
Accepts either an arrayref of hashrefs or alternatively an arrayref of
arrayrefs.
.IP "\s-1NOTE\s0" 4
.IX Item "NOTE"
The context of this method call has an important effect on what is
submitted to storage. In void context data is fed directly to fastpath
insertion routines provided by the underlying storage (most often
\&\*(L"execute_for_fetch\*(R" in \s-1DBI\s0), bypassing the new and
insert calls on the
Result class, including any
augmentation of these methods provided by components. For example if you
are using something like DBIx::Class::UUIDColumns to create primary
keys for you, you will find that your PKs are empty.  In this case you
will have to explicitly force scalar or list context in order to create
those values.
.PP
In non-void (scalar or list) context, this method is simply a wrapper
for \*(L"create\*(R". Depending on list or scalar context either a list of
Result objects or an arrayref
containing these objects is returned.
.PP
When supplying data in \*(L"arrayref of arrayrefs\*(R" invocation style, the
first element should be a list of column names and each subsequent
element should be a data value in the earlier specified column order.
For example:
.PP
.Vb 6
\&  $schema\->resultset("Artist")\->populate([
\&    [ qw( artistid name ) ],
\&    [ 100, \*(AqA Formally Unknown Singer\*(Aq ],
\&    [ 101, \*(AqA singer that jumped the shark two albums ago\*(Aq ],
\&    [ 102, \*(AqAn actually cool singer\*(Aq ],
\&  ]);
.Ve
.PP
For the arrayref of hashrefs style each hashref should be a structure
suitable for passing to \*(L"create\*(R". Multi-create is also permitted with
this syntax.
.PP
.Vb 10
\&  $schema\->resultset("Artist")\->populate([
\&     { artistid => 4, name => \*(AqManufactured Crap\*(Aq, cds => [
\&        { title => \*(AqMy First CD\*(Aq, year => 2006 },
\&        { title => \*(AqYet More Tweeny\-Pop crap\*(Aq, year => 2007 },
\&      ],
\&     },
\&     { artistid => 5, name => \*(AqAngsty\-Whiny Girl\*(Aq, cds => [
\&        { title => \*(AqMy parents sold me to a record company\*(Aq, year => 2005 },
\&        { title => \*(AqWhy Am I So Ugly?\*(Aq, year => 2006 },
\&        { title => \*(AqI Got Surgery and am now Popular\*(Aq, year => 2007 }
\&      ],
\&     },
\&  ]);
.Ve
.PP
If you attempt a void-context multi-create as in the example above (each
Artist also has the related list of CDs), and \fBdo not\fR supply the
necessary autoinc foreign key information, this method will proxy to the
less efficient \*(L"create\*(R", and then throw the Result objects away. In this
case there are obviously no benefits to using this method over \*(L"create\*(R".
.SS "pager"
.IX Subsection "pager"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $pager" 4
.el .IP "Return Value: \f(CW$pager\fR" 4
.IX Item "Return Value: $pager"
.PD
.PP
Returns a DBIx::Class::ResultSet::Pager object tied to the current
resultset. Requires the \f(CW\*(C`page\*(C'\fR attribute to have been previously set on
the resultset object, usually via a call to \*(L"page\*(R".
.PP
To get the full count of entries for a paged resultset, call
total_entries on the pager
object.
.SS "page"
.IX Subsection "page"
.ie n .IP "Arguments: $page_number" 4
.el .IP "Arguments: \f(CW$page_number\fR" 4
.IX Item "Arguments: $page_number"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
Returns a resultset for the \f(CW$page_number\fR page of the resultset on which page
is called, where each page contains a number of rows equal to the 'rows'
attribute set on the resultset (10 by default).
.SS "new_result"
.IX Subsection "new_result"
.IP "Arguments: \e%col_data" 4
.IX Item "Arguments: %col_data"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Creates a new result object in the resultset's result class and returns
it. The row is not inserted into the database at this point, call
\&\*(L"insert\*(R" in DBIx::Class::Row to do that. Calling \*(L"in_storage\*(R" in DBIx::Class::Row
will tell you whether the result object has been inserted or not.
.PP
Passes the hashref of input on to \*(L"new\*(R" in DBIx::Class::Row.
.SS "as_query"
.IX Subsection "as_query"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: \e[ $sql, @bind_values ]" 4
.el .IP "Return Value: \e[ \f(CW$sql\fR, \f(CW@bind_values\fR ]" 4
.IX Item "Return Value: [ $sql, @bind_values ]"
.PD
.PP
Returns the \s-1SQL\s0 query and bind vars associated with the invocant.
.PP
This is generally used as the \s-1RHS\s0 for a subquery.
.SS "find_or_new"
.IX Subsection "find_or_new"
.ie n .IP "Arguments: \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 2
\&  my $artist = $schema\->resultset(\*(AqArtist\*(Aq)\->find_or_new(
\&    { artist => \*(Aqfred\*(Aq }, { key => \*(Aqartists\*(Aq });
\&
\&  $cd\->cd_to_producer\->find_or_new({ producer => $producer },
\&                                   { key => \*(Aqprimary\*(Aq });
.Ve
.PP
Find an existing record from this resultset using \*(L"find\*(R". if none exists,
instantiate a new result object and return it. The object will not be saved
into your storage until you call \*(L"insert\*(R" in DBIx::Class::Row on it.
.PP
You most likely want this method when looking for existing rows using a unique
constraint that is not the primary key, or looking for related rows.
.PP
If you want objects to be saved immediately, use \*(L"find_or_create\*(R" instead.
.PP
\&\fBNote\fR: Make sure to read the documentation of \*(L"find\*(R" and understand the
significance of the \f(CW\*(C`key\*(C'\fR attribute, as its lack may skew your search, and
subsequently result in spurious new objects.
.PP
\&\fBNote\fR: Take care when using \f(CW\*(C`find_or_new\*(C'\fR with a table having
columns with default values that you intend to be automatically
supplied by the database (e.g. an auto_increment primary key column).
In normal usage, the value of such columns should \s-1NOT\s0 be included at
all in the call to \f(CW\*(C`find_or_new\*(C'\fR, even when set to \f(CW\*(C`undef\*(C'\fR.
.SS "create"
.IX Subsection "create"
.IP "Arguments: \e%col_data" 4
.IX Item "Arguments: %col_data"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Attempt to create a single new row or a row with multiple related rows
in the table represented by the resultset (and related tables). This
will not check for duplicate rows before inserting, use
\&\*(L"find_or_create\*(R" to do that.
.PP
To create one row for this resultset, pass a hashref of key/value
pairs representing the columns of the table and the values you wish to
store. If the appropriate relationships are set up, foreign key fields
can also be passed an object representing the foreign row, and the
value will be set to its primary key.
.PP
To create related objects, pass a hashref of related-object column values
\&\fBkeyed on the relationship name\fR. If the relationship is of type \f(CW\*(C`multi\*(C'\fR
(\*(L"has_many\*(R" in DBIx::Class::Relationship) \- pass an arrayref of hashrefs.
The process will correctly identify columns holding foreign keys, and will
transparently populate them from the keys of the corresponding relation.
This can be applied recursively, and will work correctly for a structure
with an arbitrary depth and width, as long as the relationships actually
exists and the correct column data has been supplied.
.PP
Instead of hashrefs of plain related data (key/value pairs), you may
also pass new or inserted objects. New objects (not inserted yet, see
\&\*(L"new_result\*(R"), will be inserted into their appropriate tables.
.PP
Effectively a shortcut for \f(CW\*(C`\->new_result(\e%col_data)\->insert\*(C'\fR.
.PP
Example of creating a new row.
.PP
.Vb 4
\&  $person_rs\->create({
\&    name=>"Some Person",
\&    email=>"somebody@someplace.com"
\&  });
.Ve
.PP
Example of creating a new row and also creating rows in a related \f(CW\*(C`has_many\*(C'\fR
or \f(CW\*(C`has_one\*(C'\fR resultset.  Note Arrayref.
.PP
.Vb 7
\&  $artist_rs\->create(
\&     { artistid => 4, name => \*(AqManufactured Crap\*(Aq, cds => [
\&        { title => \*(AqMy First CD\*(Aq, year => 2006 },
\&        { title => \*(AqYet More Tweeny\-Pop crap\*(Aq, year => 2007 },
\&      ],
\&     },
\&  );
.Ve
.PP
Example of creating a new row and also creating a row in a related
\&\f(CW\*(C`belongs_to\*(C'\fR resultset. Note Hashref.
.PP
.Vb 7
\&  $cd_rs\->create({
\&    title=>"Music for Silly Walks",
\&    year=>2000,
\&    artist => {
\&      name=>"Silly Musician",
\&    }
\&  });
.Ve
.IP "\s-1WARNING\s0" 4
.IX Item "WARNING"
When subclassing ResultSet never attempt to override this method. Since
it is a simple shortcut for \f(CW\*(C`$self\->new_result($attrs)\->insert\*(C'\fR, a
lot of the internals simply never call it, so your override will be
bypassed more often than not. Override either \*(L"new\*(R" in DBIx::Class::Row
or \*(L"insert\*(R" in DBIx::Class::Row depending on how early in the
\&\*(L"create\*(R" process you need to intervene. See also warning pertaining to
\&\*(L"new\*(R".
.SS "find_or_create"
.IX Subsection "find_or_create"
.ie n .IP "Arguments: \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 2
\&  $cd\->cd_to_producer\->find_or_create({ producer => $producer },
\&                                      { key => \*(Aqprimary\*(Aq });
.Ve
.PP
Tries to find a record based on its primary key or unique constraints; if none
is found, creates one and returns that instead.
.PP
.Vb 6
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->find_or_create({
\&    cdid   => 5,
\&    artist => \*(AqMassive Attack\*(Aq,
\&    title  => \*(AqMezzanine\*(Aq,
\&    year   => 2005,
\&  });
.Ve
.PP
Also takes an optional \f(CW\*(C`key\*(C'\fR attribute, to search by a specific key or unique
constraint. For example:
.PP
.Vb 7
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->find_or_create(
\&    {
\&      artist => \*(AqMassive Attack\*(Aq,
\&      title  => \*(AqMezzanine\*(Aq,
\&    },
\&    { key => \*(Aqcd_artist_title\*(Aq }
\&  );
.Ve
.PP
\&\fBNote\fR: Make sure to read the documentation of \*(L"find\*(R" and understand the
significance of the \f(CW\*(C`key\*(C'\fR attribute, as its lack may skew your search, and
subsequently result in spurious row creation.
.PP
\&\fBNote\fR: Because \fBfind_or_create()\fR reads from the database and then
possibly inserts based on the result, this method is subject to a race
condition. Another process could create a record in the table after
the find has completed and before the create has started. To avoid
this problem, use \fBfind_or_create()\fR inside a transaction.
.PP
\&\fBNote\fR: Take care when using \f(CW\*(C`find_or_create\*(C'\fR with a table having
columns with default values that you intend to be automatically
supplied by the database (e.g. an auto_increment primary key column).
In normal usage, the value of such columns should \s-1NOT\s0 be included at
all in the call to \f(CW\*(C`find_or_create\*(C'\fR, even when set to \f(CW\*(C`undef\*(C'\fR.
.PP
See also \*(L"find\*(R" and \*(L"update_or_create\*(R". For information on how to declare
unique constraints, see \*(L"add_unique_constraint\*(R" in DBIx::Class::ResultSource.
.PP
If you need to know if an existing row was found or a new one created use
\&\*(L"find_or_new\*(R" and \*(L"in_storage\*(R" in DBIx::Class::Row instead. Don't forget
to call \*(L"insert\*(R" in DBIx::Class::Row to save the newly created row to the
database!
.PP
.Vb 6
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->find_or_new({
\&    cdid   => 5,
\&    artist => \*(AqMassive Attack\*(Aq,
\&    title  => \*(AqMezzanine\*(Aq,
\&    year   => 2005,
\&  });
\&
\&  if( !$cd\->in_storage ) {
\&      # do some stuff
\&      $cd\->insert;
\&  }
.Ve
.SS "update_or_create"
.IX Subsection "update_or_create"
.ie n .IP "Arguments: \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 1
\&  $resultset\->update_or_create({ col => $val, ... });
.Ve
.PP
Like \*(L"find_or_create\*(R", but if a row is found it is immediately updated via
\&\f(CW\*(C`$found_row\->update (\e%col_data)\*(C'\fR.
.PP
Takes an optional \f(CW\*(C`key\*(C'\fR attribute to search on a specific unique constraint.
For example:
.PP
.Vb 9
\&  # In your application
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->update_or_create(
\&    {
\&      artist => \*(AqMassive Attack\*(Aq,
\&      title  => \*(AqMezzanine\*(Aq,
\&      year   => 1998,
\&    },
\&    { key => \*(Aqcd_artist_title\*(Aq }
\&  );
\&
\&  $cd\->cd_to_producer\->update_or_create({
\&    producer => $producer,
\&    name => \*(Aqharry\*(Aq,
\&  }, {
\&    key => \*(Aqprimary\*(Aq,
\&  });
.Ve
.PP
\&\fBNote\fR: Make sure to read the documentation of \*(L"find\*(R" and understand the
significance of the \f(CW\*(C`key\*(C'\fR attribute, as its lack may skew your search, and
subsequently result in spurious row creation.
.PP
\&\fBNote\fR: Take care when using \f(CW\*(C`update_or_create\*(C'\fR with a table having
columns with default values that you intend to be automatically
supplied by the database (e.g. an auto_increment primary key column).
In normal usage, the value of such columns should \s-1NOT\s0 be included at
all in the call to \f(CW\*(C`update_or_create\*(C'\fR, even when set to \f(CW\*(C`undef\*(C'\fR.
.PP
See also \*(L"find\*(R" and \*(L"find_or_create\*(R". For information on how to declare
unique constraints, see \*(L"add_unique_constraint\*(R" in DBIx::Class::ResultSource.
.PP
If you need to know if an existing row was updated or a new one created use
\&\*(L"update_or_new\*(R" and \*(L"in_storage\*(R" in DBIx::Class::Row instead. Don't forget
to call \*(L"insert\*(R" in DBIx::Class::Row to save the newly created row to the
database!
.SS "update_or_new"
.IX Subsection "update_or_new"
.ie n .IP "Arguments: \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 1
\&  $resultset\->update_or_new({ col => $val, ... });
.Ve
.PP
Like \*(L"find_or_new\*(R" but if a row is found it is immediately updated via
\&\f(CW\*(C`$found_row\->update (\e%col_data)\*(C'\fR.
.PP
For example:
.PP
.Vb 9
\&  # In your application
\&  my $cd = $schema\->resultset(\*(AqCD\*(Aq)\->update_or_new(
\&    {
\&      artist => \*(AqMassive Attack\*(Aq,
\&      title  => \*(AqMezzanine\*(Aq,
\&      year   => 1998,
\&    },
\&    { key => \*(Aqcd_artist_title\*(Aq }
\&  );
\&
\&  if ($cd\->in_storage) {
\&      # the cd was updated
\&  }
\&  else {
\&      # the cd is not yet in the database, let\*(Aqs insert it
\&      $cd\->insert;
\&  }
.Ve
.PP
\&\fBNote\fR: Make sure to read the documentation of \*(L"find\*(R" and understand the
significance of the \f(CW\*(C`key\*(C'\fR attribute, as its lack may skew your search, and
subsequently result in spurious new objects.
.PP
\&\fBNote\fR: Take care when using \f(CW\*(C`update_or_new\*(C'\fR with a table having
columns with default values that you intend to be automatically
supplied by the database (e.g. an auto_increment primary key column).
In normal usage, the value of such columns should \s-1NOT\s0 be included at
all in the call to \f(CW\*(C`update_or_new\*(C'\fR, even when set to \f(CW\*(C`undef\*(C'\fR.
.PP
See also \*(L"find\*(R", \*(L"find_or_create\*(R" and \*(L"find_or_new\*(R".
.SS "get_cache"
.IX Subsection "get_cache"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: \e@result_objs | undef" 4
.IX Item "Return Value: @result_objs | undef"
.PD
.PP
Gets the contents of the cache for the resultset, if the cache is set.
.PP
The cache is populated either by using the \*(L"prefetch\*(R" attribute to
\&\*(L"search\*(R" or by calling \*(L"set_cache\*(R".
.SS "set_cache"
.IX Subsection "set_cache"
.IP "Arguments: \e@result_objs" 4
.IX Item "Arguments: @result_objs"
.PD 0
.IP "Return Value: \e@result_objs" 4
.IX Item "Return Value: @result_objs"
.PD
.PP
Sets the contents of the cache for the resultset. Expects an arrayref
of objects of the same class as those produced by the resultset. Note that
if the cache is set, the resultset will return the cached objects rather
than re-querying the database even if the cache attr is not set.
.PP
The contents of the cache can also be populated by using the
\&\*(L"prefetch\*(R" attribute to \*(L"search\*(R".
.SS "clear_cache"
.IX Subsection "clear_cache"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: undef" 4
.IX Item "Return Value: undef"
.PD
.PP
Clears the cache for the resultset.
.SS "is_paged"
.IX Subsection "is_paged"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: true, if the resultset has been paginated" 4
.IX Item "Return Value: true, if the resultset has been paginated"
.PD
.SS "is_ordered"
.IX Subsection "is_ordered"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: true, if the resultset has been ordered with ""order_by""." 4
.el .IP "Return Value: true, if the resultset has been ordered with \f(CWorder_by\fR." 4
.IX Item "Return Value: true, if the resultset has been ordered with order_by."
.PD
.SS "related_resultset"
.IX Subsection "related_resultset"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
Returns a related resultset for the supplied relationship name.
.PP
.Vb 1
\&  $artist_rs = $schema\->resultset(\*(AqCD\*(Aq)\->related_resultset(\*(AqArtist\*(Aq);
.Ve
.SS "current_source_alias"
.IX Subsection "current_source_alias"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $source_alias" 4
.el .IP "Return Value: \f(CW$source_alias\fR" 4
.IX Item "Return Value: $source_alias"
.PD
.PP
Returns the current table alias for the result source this resultset is built
on, that will be used in the \s-1SQL\s0 query. Usually it is \f(CW\*(C`me\*(C'\fR.
.PP
Currently the source alias that refers to the result set returned by a
\&\*(L"search\*(R"/\*(L"find\*(R" family method depends on how you got to the resultset: it's
\&\f(CW\*(C`me\*(C'\fR by default, but eg. \*(L"search_related\*(R" aliases it to the related result
source name (and keeps \f(CW\*(C`me\*(C'\fR referring to the original result set). The long
term goal is to make DBIx::Class always alias the current resultset as \f(CW\*(C`me\*(C'\fR
(and make this method unnecessary).
.PP
Thus it's currently necessary to use this method in predefined queries (see
\&\*(L"Predefined searches\*(R" in DBIx::Class::Manual::Cookbook) when referring to the
source alias of the current result set:
.PP
.Vb 3
\&  # in a result set class
\&  sub modified_by {
\&    my ($self, $user) = @_;
\&
\&    my $me = $self\->current_source_alias;
\&
\&    return $self\->search({
\&      "$me.modified" => $user\->id,
\&    });
\&  }
.Ve
.PP
The alias of newly created resultsets can be altered by the
alias attribute.
.SS "as_subselect_rs"
.IX Subsection "as_subselect_rs"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
Act as a barrier to \s-1SQL\s0 symbols.  The resultset provided will be made into a
\&\*(L"virtual view\*(R" by including it as a subquery within the from clause.  From this
point on, any joined tables are inaccessible to \->search on the resultset (as if
it were simply where-filtered without joins).  For example:
.PP
.Vb 1
\& my $rs = $schema\->resultset(\*(AqBar\*(Aq)\->search({\*(Aqx.name\*(Aq => \*(Aqabc\*(Aq},{ join => \*(Aqx\*(Aq });
\&
\& # \*(Aqx\*(Aq now pollutes the query namespace
\&
\& # So the following works as expected
\& my $ok_rs = $rs\->search({\*(Aqx.other\*(Aq => 1});
\&
\& # But this doesn\*(Aqt: instead of finding a \*(AqBar\*(Aq related to two x rows (abc and
\& # def) we look for one row with contradictory terms and join in another table
\& # (aliased \*(Aqx_2\*(Aq) which we never use
\& my $broken_rs = $rs\->search({\*(Aqx.name\*(Aq => \*(Aqdef\*(Aq});
\&
\& my $rs2 = $rs\->as_subselect_rs;
\&
\& # doesn\*(Aqt work \- \*(Aqx\*(Aq is no longer accessible in $rs2, having been sealed away
\& my $not_joined_rs = $rs2\->search({\*(Aqx.other\*(Aq => 1});
\&
\& # works as expected: finds a \*(Aqtable\*(Aq row related to two x rows (abc and def)
\& my $correctly_joined_rs = $rs2\->search({\*(Aqx.name\*(Aq => \*(Aqdef\*(Aq});
.Ve
.PP
Another example of when one might use this would be to select a subset of
columns in a group by clause:
.PP
.Vb 5
\& my $rs = $schema\->resultset(\*(AqBar\*(Aq)\->search(undef, {
\&   group_by => [qw{ id foo_id baz_id }],
\& })\->as_subselect_rs\->search(undef, {
\&   columns => [qw{ id foo_id }]
\& });
.Ve
.PP
In the above example normally columns would have to be equal to the group by,
but because we isolated the group by into a subselect the above works.
.SS "throw_exception"
.IX Subsection "throw_exception"
See \*(L"throw_exception\*(R" in DBIx::Class::Schema for details.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Attributes are used to refine a ResultSet in various ways when
searching for data. They can be passed to any method which takes an
\&\f(CW\*(C`\e%attrs\*(C'\fR argument. See \*(L"search\*(R", \*(L"search_rs\*(R", \*(L"find\*(R",
\&\*(L"count\*(R".
.PP
Default attributes can be set on the result class using
\&\*(L"resultset_attributes\*(R" in DBIx::Class::ResultSource.  (Please read
the \s-1CAVEATS\s0 on that feature before using it!)
.PP
These are in no particular order:
.SS "order_by"
.IX Subsection "order_by"
.ie n .IP "Value: ( $order_by | \e@order_by | \e%order_by )" 4
.el .IP "Value: ( \f(CW$order_by\fR | \e@order_by | \e%order_by )" 4
.IX Item "Value: ( $order_by | @order_by | %order_by )"
.PP
Which column(s) to order the results by.
.PP
[The full list of suitable values is documented in
\&\*(L"\s-1ORDER BY CLAUSES\*(R"\s0 in SQL::Abstract::Classic; the following is a summary of
common options.]
.PP
If a single column name, or an arrayref of names is supplied, the
argument is passed through directly to \s-1SQL.\s0 The hashref syntax allows
for connection-agnostic specification of ordering direction:
.PP
.Vb 1
\& For descending order:
\&
\&  order_by => { \-desc => [qw/col1 col2 col3/] }
\&
\& For explicit ascending order:
\&
\&  order_by => { \-asc => \*(Aqcol\*(Aq }
.Ve
.PP
The old scalarref syntax (i.e. order_by => \e'year \s-1DESC\s0') is still
supported, although you are strongly encouraged to use the hashref
syntax as outlined above.
.SS "columns"
.IX Subsection "columns"
.ie n .IP "Value: \e@columns | \e%columns | $column" 4
.el .IP "Value: \e@columns | \e%columns | \f(CW$column\fR" 4
.IX Item "Value: @columns | %columns | $column"
.PP
Shortcut to request a particular set of columns to be retrieved. Each
column spec may be a string (a table column name), or a hash (in which
case the key is the \f(CW\*(C`as\*(C'\fR value, and the value is used as the \f(CW\*(C`select\*(C'\fR
expression). Adds the \*(L"current_source_alias\*(R" onto the start of any column without a \f(CW\*(C`.\*(C'\fR in
it and sets \f(CW\*(C`select\*(C'\fR from that, then auto-populates \f(CW\*(C`as\*(C'\fR from
\&\f(CW\*(C`select\*(C'\fR as normal. (You may also use the \f(CW\*(C`cols\*(C'\fR attribute, as in
earlier versions of \s-1DBIC,\s0 but this is deprecated)
.PP
Essentially \f(CW\*(C`columns\*(C'\fR does the same as \*(L"select\*(R" and \*(L"as\*(R".
.PP
.Vb 1
\&    columns => [ \*(Aqsome_column\*(Aq, { dbic_slot => \*(Aqanother_column\*(Aq } ]
.Ve
.PP
is the same as
.PP
.Vb 2
\&    select => [qw(some_column another_column)],
\&    as     => [qw(some_column dbic_slot)]
.Ve
.PP
If you want to individually retrieve related columns (in essence perform
manual \*(L"prefetch\*(R") you have to make sure to specify the correct inflation slot
chain such that it matches existing relationships:
.PP
.Vb 9
\&    my $rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search({}, {
\&        # required to tell DBIC to collapse has_many relationships
\&        collapse => 1,
\&        join     => { cds => \*(Aqtracks\*(Aq },
\&        \*(Aq+columns\*(Aq  => {
\&          \*(Aqcds.cdid\*(Aq         => \*(Aqcds.cdid\*(Aq,
\&          \*(Aqcds.tracks.title\*(Aq => \*(Aqtracks.title\*(Aq,
\&        },
\&    });
.Ve
.PP
Like elsewhere, literal \s-1SQL\s0 or literal values can be included by using a
scalar reference or a literal bind value, and these values will be available
in the result with \f(CW\*(C`get_column\*(C'\fR (see also
SQL::Abstract::Classic/Literal \s-1SQL\s0 and value type operators>):
.PP
.Vb 9
\&    # equivalent SQL: SELECT 1, \*(Aqa string\*(Aq, IF(my_column,?,?) ...
\&    # bind values: $true_value, $false_value
\&    columns => [
\&        {
\&            foo => \e1,
\&            bar => \eq{\*(Aqa string\*(Aq},
\&            baz => \e[ \*(AqIF(my_column,?,?)\*(Aq, $true_value, $false_value ],
\&        }
\&    ]
.Ve
.SS "+columns"
.IX Subsection "+columns"
\&\fB\s-1NOTE:\s0\fR You \fB\s-1MUST\s0\fR explicitly quote \f(CW\*(Aq+columns\*(Aq\fR when using this attribute.
Not doing so causes Perl to incorrectly interpret \f(CW\*(C`+columns\*(C'\fR as a bareword
with a unary plus operator before it, which is the same as simply \f(CW\*(C`columns\*(C'\fR.
.IP "Value: \e@extra_columns" 4
.IX Item "Value: @extra_columns"
.PP
Indicates additional columns to be selected from storage. Works the same as
\&\*(L"columns\*(R" but adds columns to the current selection. (You may also use the
\&\f(CW\*(C`include_columns\*(C'\fR attribute, as in earlier versions of \s-1DBIC,\s0 but this is
deprecated)
.PP
.Vb 4
\&  $schema\->resultset(\*(AqCD\*(Aq)\->search(undef, {
\&    \*(Aq+columns\*(Aq => [\*(Aqartist.name\*(Aq],
\&    join => [\*(Aqartist\*(Aq]
\&  });
.Ve
.PP
would return all CDs and include a 'name' column to the information
passed to object inflation. Note that the 'artist' is the name of the
column (or relationship) accessor, and 'name' is the name of the column
accessor in the related table.
.SS "select"
.IX Subsection "select"
.IP "Value: \e@select_columns" 4
.IX Item "Value: @select_columns"
.PP
Indicates which columns should be selected from the storage. You can use
column names, or in the case of \s-1RDBMS\s0 back ends, function or stored procedure
names:
.PP
.Vb 7
\&  $rs = $schema\->resultset(\*(AqEmployee\*(Aq)\->search(undef, {
\&    select => [
\&      \*(Aqname\*(Aq,
\&      { count => \*(Aqemployeeid\*(Aq },
\&      { max => { length => \*(Aqname\*(Aq }, \-as => \*(Aqlongest_name\*(Aq }
\&    ]
\&  });
\&
\&  # Equivalent SQL
\&  SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR You will almost always need a corresponding \*(L"as\*(R" attribute when you
use \*(L"select\*(R", to instruct DBIx::Class how to store the result of the column.
.PP
Also note that the \*(L"as\*(R" attribute has \fBnothing to do\fR with the SQL-side
\&\f(CW\*(C`AS\*(C'\fR identifier aliasing. You \fBcan\fR alias a function (so you can use it e.g.
in an \f(CW\*(C`ORDER BY\*(C'\fR clause), however this is done via the \f(CW\*(C`\-as\*(C'\fR \fBselect
function attribute\fR supplied as shown in the example above.
.SS "+select"
.IX Subsection "+select"
\&\fB\s-1NOTE:\s0\fR You \fB\s-1MUST\s0\fR explicitly quote \f(CW\*(Aq+select\*(Aq\fR when using this attribute.
Not doing so causes Perl to incorrectly interpret \f(CW\*(C`+select\*(C'\fR as a bareword
with a unary plus operator before it, which is the same as simply \f(CW\*(C`select\*(C'\fR.
.IP "Value: \e@extra_select_columns" 4
.IX Item "Value: @extra_select_columns"
.PP
Indicates additional columns to be selected from storage.  Works the same as
\&\*(L"select\*(R" but adds columns to the current selection, instead of specifying
a new explicit list.
.SS "as"
.IX Subsection "as"
.IP "Value: \e@inflation_names" 4
.IX Item "Value: @inflation_names"
.PP
Indicates DBIC-side names for object inflation. That is \*(L"as\*(R" indicates the
slot name in which the column value will be stored within the
Row object. The value will then be accessible via this
identifier by the \f(CW\*(C`get_column\*(C'\fR method (or via the object accessor \fBif one
with the same name already exists\fR) as shown below.
.PP
The \*(L"as\*(R" attribute has \fBnothing to do\fR with the SQL-side identifier
aliasing \f(CW\*(C`AS\*(C'\fR. See \*(L"select\*(R" for details.
.PP
.Vb 12
\&  $rs = $schema\->resultset(\*(AqEmployee\*(Aq)\->search(undef, {
\&    select => [
\&      \*(Aqname\*(Aq,
\&      { count => \*(Aqemployeeid\*(Aq },
\&      { max => { length => \*(Aqname\*(Aq }, \-as => \*(Aqlongest_name\*(Aq }
\&    ],
\&    as => [qw/
\&      name
\&      employee_count
\&      max_name_length
\&    /],
\&  });
.Ve
.PP
If the object against which the search is performed already has an accessor
matching a column name specified in \f(CW\*(C`as\*(C'\fR, the value can be retrieved using
the accessor as normal:
.PP
.Vb 1
\&  my $name = $employee\->name();
.Ve
.PP
If on the other hand an accessor does not exist in the object, you need to
use \f(CW\*(C`get_column\*(C'\fR instead:
.PP
.Vb 1
\&  my $employee_count = $employee\->get_column(\*(Aqemployee_count\*(Aq);
.Ve
.PP
You can create your own accessors if required \- see
DBIx::Class::Manual::Cookbook for details.
.SS "+as"
.IX Subsection "+as"
\&\fB\s-1NOTE:\s0\fR You \fB\s-1MUST\s0\fR explicitly quote \f(CW\*(Aq+as\*(Aq\fR when using this attribute.
Not doing so causes Perl to incorrectly interpret \f(CW\*(C`+as\*(C'\fR as a bareword
with a unary plus operator before it, which is the same as simply \f(CW\*(C`as\*(C'\fR.
.IP "Value: \e@extra_inflation_names" 4
.IX Item "Value: @extra_inflation_names"
.PP
Indicates additional inflation names for selectors added via \*(L"+select\*(R". See \*(L"as\*(R".
.SS "join"
.IX Subsection "join"
.IP "Value: ($rel_name | \e@rel_names | \e%rel_names)" 4
.IX Item "Value: ($rel_name | @rel_names | %rel_names)"
.PP
Contains a list of relationships that should be joined for this query.  For
example:
.PP
.Vb 5
\&  # Get CDs by Nine Inch Nails
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search(
\&    { \*(Aqartist.name\*(Aq => \*(AqNine Inch Nails\*(Aq },
\&    { join => \*(Aqartist\*(Aq }
\&  );
.Ve
.PP
Can also contain a hash reference to refer to the other relation's relations.
For example:
.PP
.Vb 7
\&  package MyApp::Schema::Track;
\&  use base qw/DBIx::Class/;
\&  _\|_PACKAGE_\|_\->table(\*(Aqtrack\*(Aq);
\&  _\|_PACKAGE_\|_\->add_columns(qw/trackid cd position title/);
\&  _\|_PACKAGE_\|_\->set_primary_key(\*(Aqtrackid\*(Aq);
\&  _\|_PACKAGE_\|_\->belongs_to(cd => \*(AqMyApp::Schema::CD\*(Aq);
\&  1;
\&
\&  # In your application
\&  my $rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search(
\&    { \*(Aqtrack.title\*(Aq => \*(AqTeardrop\*(Aq },
\&    {
\&      join     => { cd => \*(Aqtrack\*(Aq },
\&      order_by => \*(Aqartist.name\*(Aq,
\&    }
\&  );
.Ve
.PP
You need to use the relationship (not the table) name in  conditions,
because they are aliased as such. The current table is aliased as \*(L"me\*(R", so
you need to use me.column_name in order to avoid ambiguity. For example:
.PP
.Vb 8
\&  # Get CDs from 1984 with a \*(AqFoo\*(Aq track
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search(
\&    {
\&      \*(Aqme.year\*(Aq => 1984,
\&      \*(Aqtracks.name\*(Aq => \*(AqFoo\*(Aq
\&    },
\&    { join => \*(Aqtracks\*(Aq }
\&  );
.Ve
.PP
If the same join is supplied twice, it will be aliased to <rel>_2 (and
similarly for a third time). For e.g.
.PP
.Vb 6
\&  my $rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search({
\&    \*(Aqcds.title\*(Aq   => \*(AqDown to Earth\*(Aq,
\&    \*(Aqcds_2.title\*(Aq => \*(AqPopular\*(Aq,
\&  }, {
\&    join => [ qw/cds cds/ ],
\&  });
.Ve
.PP
will return a set of all artists that have both a cd with title 'Down
to Earth' and a cd with title 'Popular'.
.PP
If you want to fetch related objects from other tables as well, see \*(L"prefetch\*(R"
below.
.PP
.Vb 5
\& NOTE: An internal join\-chain pruner will discard certain joins while
\& constructing the actual SQL query, as long as the joins in question do not
\& affect the retrieved result. This for example includes 1:1 left joins
\& that are not part of the restriction specification (WHERE/HAVING) nor are
\& a part of the query selection.
.Ve
.PP
For more help on using joins with search, see DBIx::Class::Manual::Joining.
.SS "collapse"
.IX Subsection "collapse"
.IP "Value: (0 | 1)" 4
.IX Item "Value: (0 | 1)"
.PP
When set to a true value, indicates that any rows fetched from joined has_many
relationships are to be aggregated into the corresponding \*(L"parent\*(R" object. For
example, the resultset:
.PP
.Vb 5
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search({}, {
\&    \*(Aq+columns\*(Aq => [ qw/ tracks.title tracks.position / ],
\&    join => \*(Aqtracks\*(Aq,
\&    collapse => 1,
\&  });
.Ve
.PP
While executing the following query:
.PP
.Vb 4
\&  SELECT me.*, tracks.title, tracks.position
\&    FROM cd me
\&    LEFT JOIN track tracks
\&      ON tracks.cdid = me.cdid
.Ve
.PP
Will return only as many objects as there are rows in the \s-1CD\s0 source, even
though the result of the query may span many rows. Each of these \s-1CD\s0 objects
will in turn have multiple \*(L"Track\*(R" objects hidden behind the has_many
generated accessor \f(CW\*(C`tracks\*(C'\fR. Without \f(CW\*(C`collapse => 1\*(C'\fR, the return values
of this resultset would be as many \s-1CD\s0 objects as there are tracks (a \*(L"Cartesian
product\*(R"), with each \s-1CD\s0 object containing exactly one of all fetched Track data.
.PP
When a collapse is requested on a non-ordered resultset, an order by some
unique part of the main source (the left-most table) is inserted automatically.
This is done so that the resultset is allowed to be \*(L"lazy\*(R" \- calling
\&\f(CW$rs\fR\->next will fetch only as many rows as it needs to build the next
object with all of its related data.
.PP
If an \*(L"order_by\*(R" is already declared, and orders the resultset in a way that
makes collapsing as described above impossible (e.g. \f(CW\*(C`ORDER BY
has_many_rel.column\*(C'\fR or \f(CW\*(C`ORDER BY RANDOM()\*(C'\fR), \s-1DBIC\s0 will automatically
switch to \*(L"eager\*(R" mode and slurp the entire resultset before constructing the
first object returned by \*(L"next\*(R".
.PP
Setting this attribute on a resultset that does not join any has_many
relations is a no-op.
.PP
For a more in-depth discussion, see \*(L"\s-1PREFETCHING\*(R"\s0.
.SS "prefetch"
.IX Subsection "prefetch"
.IP "Value: ($rel_name | \e@rel_names | \e%rel_names)" 4
.IX Item "Value: ($rel_name | @rel_names | %rel_names)"
.PP
This attribute is a shorthand for specifying a \*(L"join\*(R" spec, adding all
columns from the joined related sources as \*(L"+columns\*(R" and setting
\&\*(L"collapse\*(R" to a true value. It can be thought of as a rough \fBsuperset\fR
of the \*(L"join\*(R" attribute.
.PP
For example, the following two queries are equivalent:
.PP
.Vb 3
\&  my $rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search({}, {
\&    prefetch => { cds => [\*(Aqgenre\*(Aq, \*(Aqtracks\*(Aq ] },
\&  });
.Ve
.PP
and
.PP
.Vb 10
\&  my $rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search({}, {
\&    join => { cds => [\*(Aqgenre\*(Aq, \*(Aqtracks\*(Aq ] },
\&    collapse => 1,
\&    \*(Aq+columns\*(Aq => [
\&      (map
\&        { +{ "cds.$_" => "cds.$_" } }
\&        $schema\->source(\*(AqArtist\*(Aq)\->related_source(\*(Aqcds\*(Aq)\->columns
\&      ),
\&      (map
\&        { +{ "cds.genre.$_" => "genre.$_" } }
\&        $schema\->source(\*(AqArtist\*(Aq)\->related_source(\*(Aqcds\*(Aq)\->related_source(\*(Aqgenre\*(Aq)\->columns
\&      ),
\&      (map
\&        { +{ "cds.tracks.$_" => "tracks.$_" } }
\&        $schema\->source(\*(AqArtist\*(Aq)\->related_source(\*(Aqcds\*(Aq)\->related_source(\*(Aqtracks\*(Aq)\->columns
\&      ),
\&    ],
\&  });
.Ve
.PP
Both producing the following \s-1SQL:\s0
.PP
.Vb 12
\&  SELECT  me.artistid, me.name, me.rank, me.charfield,
\&          cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track,
\&          genre.genreid, genre.name,
\&          tracks.trackid, tracks.cd, tracks.position, tracks.title, tracks.last_updated_on, tracks.last_updated_at
\&    FROM artist me
\&    LEFT JOIN cd cds
\&      ON cds.artist = me.artistid
\&    LEFT JOIN genre genre
\&      ON genre.genreid = cds.genreid
\&    LEFT JOIN track tracks
\&      ON tracks.cd = cds.cdid
\&  ORDER BY me.artistid
.Ve
.PP
While \*(L"prefetch\*(R" implies a \*(L"join\*(R", it is ok to mix the two together, as
the arguments are properly merged and generally do the right thing. For
example, you may want to do the following:
.PP
.Vb 7
\&  my $artists_and_cds_without_genre = $schema\->resultset(\*(AqArtist\*(Aq)\->search(
\&    { \*(Aqgenre.genreid\*(Aq => undef },
\&    {
\&      join => { cds => \*(Aqgenre\*(Aq },
\&      prefetch => \*(Aqcds\*(Aq,
\&    }
\&  );
.Ve
.PP
Which generates the following \s-1SQL:\s0
.PP
.Vb 9
\&  SELECT  me.artistid, me.name, me.rank, me.charfield,
\&          cds.cdid, cds.artist, cds.title, cds.year, cds.genreid, cds.single_track
\&    FROM artist me
\&    LEFT JOIN cd cds
\&      ON cds.artist = me.artistid
\&    LEFT JOIN genre genre
\&      ON genre.genreid = cds.genreid
\&  WHERE genre.genreid IS NULL
\&  ORDER BY me.artistid
.Ve
.PP
For a more in-depth discussion, see \*(L"\s-1PREFETCHING\*(R"\s0.
.SS "alias"
.IX Subsection "alias"
.ie n .IP "Value: $source_alias" 4
.el .IP "Value: \f(CW$source_alias\fR" 4
.IX Item "Value: $source_alias"
.PP
Sets the source alias for the query.  Normally, this defaults to \f(CW\*(C`me\*(C'\fR, but
nested search queries (sub-SELECTs) might need specific aliases set to
reference inner queries.  For example:
.PP
.Vb 7
\&   my $q = $rs
\&      \->related_resultset(\*(AqCDs\*(Aq)
\&      \->related_resultset(\*(AqTracks\*(Aq)
\&      \->search({
\&         \*(Aqtrack.id\*(Aq => { \-ident => \*(Aqnone_search.id\*(Aq },
\&      })
\&      \->as_query;
\&
\&   my $ids = $self\->search({
\&      \-not_exists => $q,
\&   }, {
\&      alias    => \*(Aqnone_search\*(Aq,
\&      group_by => \*(Aqnone_search.id\*(Aq,
\&   })\->get_column(\*(Aqid\*(Aq)\->as_query;
\&
\&   $self\->search({ id => { \-in => $ids } })
.Ve
.PP
This attribute is directly tied to \*(L"current_source_alias\*(R".
.SS "page"
.IX Subsection "page"
.ie n .IP "Value: $page" 4
.el .IP "Value: \f(CW$page\fR" 4
.IX Item "Value: $page"
.PP
Makes the resultset paged and specifies the page to retrieve. Effectively
identical to creating a non-pages resultset and then calling \->page($page)
on it.
.PP
If \*(L"rows\*(R" attribute is not specified it defaults to 10 rows per page.
.PP
When you have a paged resultset, \*(L"count\*(R" will only return the number
of rows in the page. To get the total, use the \*(L"pager\*(R" and call
\&\f(CW\*(C`total_entries\*(C'\fR on it.
.SS "rows"
.IX Subsection "rows"
.ie n .IP "Value: $rows" 4
.el .IP "Value: \f(CW$rows\fR" 4
.IX Item "Value: $rows"
.PP
Specifies the maximum number of rows for direct retrieval or the number of
rows per page if the page attribute or method is used.
.SS "offset"
.IX Subsection "offset"
.ie n .IP "Value: $offset" 4
.el .IP "Value: \f(CW$offset\fR" 4
.IX Item "Value: $offset"
.PP
Specifies the (zero-based) row number for the  first row to be returned, or the
of the first row of the first page if paging is used.
.SS "software_limit"
.IX Subsection "software_limit"
.IP "Value: (0 | 1)" 4
.IX Item "Value: (0 | 1)"
.PP
When combined with \*(L"rows\*(R" and/or \*(L"offset\*(R" the generated \s-1SQL\s0 will not
include any limit dialect stanzas. Instead the entire result will be selected
as if no limits were specified, and \s-1DBIC\s0 will perform the limit locally, by
artificially advancing and finishing the resulting \*(L"cursor\*(R".
.PP
This is the recommended way of performing resultset limiting when no sane \s-1RDBMS\s0
implementation is available (e.g.
Sybase \s-1ASE\s0 using the
Generic Sub Query hack)
.SS "group_by"
.IX Subsection "group_by"
.IP "Value: \e@columns" 4
.IX Item "Value: @columns"
.PP
A arrayref of columns to group by. Can include columns of joined tables.
.PP
.Vb 1
\&  group_by => [qw/ column1 column2 ... /]
.Ve
.SS "having"
.IX Subsection "having"
.ie n .IP "Value: $condition" 4
.el .IP "Value: \f(CW$condition\fR" 4
.IX Item "Value: $condition"
.PP
The \s-1HAVING\s0 operator specifies a \fBsecondary\fR condition applied to the set
after the grouping calculations have been done. In other words it is a
constraint just like \*(L"where\*(R" (and accepting the same
SQL::Abstract::Classic syntax) applied
to the data as it exists after \s-1GROUP BY\s0 has taken place. Specifying \*(L"having\*(R"
without \*(L"group_by\*(R" is a logical mistake, and a fatal error on most \s-1RDBMS\s0
engines.
.PP
E.g.
.PP
.Vb 1
\&  having => { \*(Aqcount_employee\*(Aq => { \*(Aq>=\*(Aq, 100 } }
.Ve
.PP
or with an in-place function in which case literal \s-1SQL\s0 is required:
.PP
.Vb 1
\&  having => \e[ \*(Aqcount(employee) >= ?\*(Aq, 100 ]
.Ve
.SS "distinct"
.IX Subsection "distinct"
.IP "Value: (0 | 1)" 4
.IX Item "Value: (0 | 1)"
.PP
Set to 1 to automatically generate a \*(L"group_by\*(R" clause based on the selection
(including intelligent handling of \*(L"order_by\*(R" contents). Note that the group
criteria calculation takes place over the \fBfinal\fR selection. This includes
any \*(L"+columns\*(R", \*(L"+select\*(R" or \*(L"order_by\*(R" additions in subsequent
\&\*(L"search\*(R" calls, and standalone columns selected via
DBIx::Class::ResultSetColumn (\*(L"get_column\*(R"). A notable exception are the
extra selections specified via \*(L"prefetch\*(R" \- such selections are explicitly
excluded from group criteria calculations.
.PP
If the final ResultSet also explicitly defines a \*(L"group_by\*(R" attribute, this
setting is ignored and an appropriate warning is issued.
.SS "where"
.IX Subsection "where"
.RS 4
Adds to the \s-1WHERE\s0 clause.
.Sp
.Vb 2
\&  # only return rows WHERE deleted IS NULL for all searches
\&  _\|_PACKAGE_\|_\->resultset_attributes({ where => { deleted => undef } });
.Ve
.Sp
Can be overridden by passing \f(CW\*(C`{ where => undef }\*(C'\fR as an attribute
to a resultset.
.Sp
For more complicated where clauses see \*(L"\s-1WHERE CLAUSES\*(R"\s0 in SQL::Abstract::Classic.
.RE
.SS "cache"
.IX Subsection "cache"
Set to 1 to cache search results. This prevents extra \s-1SQL\s0 queries if you
revisit rows in your ResultSet:
.PP
.Vb 1
\&  my $resultset = $schema\->resultset(\*(AqArtist\*(Aq)\->search( undef, { cache => 1 } );
\&
\&  while( my $artist = $resultset\->next ) {
\&    ... do stuff ...
\&  }
\&
\&  $rs\->first; # without cache, this would issue a query
.Ve
.PP
By default, searches are not cached.
.PP
For more examples of using these attributes, see
DBIx::Class::Manual::Cookbook.
.SS "for"
.IX Subsection "for"
.IP "Value: ( 'update' | 'shared' | \e$scalar )" 4
.IX Item "Value: ( 'update' | 'shared' | $scalar )"
.PP
Set to 'update' for a \s-1SELECT ... FOR UPDATE\s0 or 'shared' for a \s-1SELECT
\&... FOR SHARED.\s0 If \e$scalar is passed, this is taken directly and embedded in the
query.
.SH "PREFETCHING"
.IX Header "PREFETCHING"
DBIx::Class supports arbitrary related data prefetching from multiple related
sources. Any combination of relationship types and column sets are supported.
If collapsing is requested, there is an additional requirement of
selecting enough data to make every individual object uniquely identifiable.
.PP
Here are some more involved examples, based on the following relationship map:
.PP
.Vb 4
\&  # Assuming:
\&  My::Schema::CD\->belongs_to( artist      => \*(AqMy::Schema::Artist\*(Aq     );
\&  My::Schema::CD\->might_have( liner_note  => \*(AqMy::Schema::LinerNotes\*(Aq );
\&  My::Schema::CD\->has_many(   tracks      => \*(AqMy::Schema::Track\*(Aq      );
\&
\&  My::Schema::Artist\->belongs_to( record_label => \*(AqMy::Schema::RecordLabel\*(Aq );
\&
\&  My::Schema::Track\->has_many( guests => \*(AqMy::Schema::Guest\*(Aq );
\&
\&
\&
\&  my $rs = $schema\->resultset(\*(AqTag\*(Aq)\->search(
\&    undef,
\&    {
\&      prefetch => {
\&        cd => \*(Aqartist\*(Aq
\&      }
\&    }
\&  );
.Ve
.PP
The initial search results in \s-1SQL\s0 like the following:
.PP
.Vb 3
\&  SELECT tag.*, cd.*, artist.* FROM tag
\&  JOIN cd ON tag.cd = cd.cdid
\&  JOIN artist ON cd.artist = artist.artistid
.Ve
.PP
DBIx::Class has no need to go back to the database when we access the
\&\f(CW\*(C`cd\*(C'\fR or \f(CW\*(C`artist\*(C'\fR relationships, which saves us two \s-1SQL\s0 statements in this
case.
.PP
Simple prefetches will be joined automatically, so there is no need
for a \f(CW\*(C`join\*(C'\fR attribute in the above search.
.PP
The \*(L"prefetch\*(R" attribute can be used with any of the relationship types
and multiple prefetches can be specified together. Below is a more complex
example that prefetches a \s-1CD\s0's artist, its liner notes (if present),
the cover image, the tracks on that \s-1CD,\s0 and the guests on those
tracks.
.PP
.Vb 11
\&  my $rs = $schema\->resultset(\*(AqCD\*(Aq)\->search(
\&    undef,
\&    {
\&      prefetch => [
\&        { artist => \*(Aqrecord_label\*(Aq},  # belongs_to => belongs_to
\&        \*(Aqliner_note\*(Aq,                 # might_have
\&        \*(Aqcover_image\*(Aq,                # has_one
\&        { tracks => \*(Aqguests\*(Aq },       # has_many => has_many
\&      ]
\&    }
\&  );
.Ve
.PP
This will produce \s-1SQL\s0 like the following:
.PP
.Vb 10
\&  SELECT cd.*, artist.*, record_label.*, liner_note.*, cover_image.*,
\&         tracks.*, guests.*
\&    FROM cd me
\&    JOIN artist artist
\&      ON artist.artistid = me.artistid
\&    JOIN record_label record_label
\&      ON record_label.labelid = artist.labelid
\&    LEFT JOIN track tracks
\&      ON tracks.cdid = me.cdid
\&    LEFT JOIN guest guests
\&      ON guests.trackid = track.trackid
\&    LEFT JOIN liner_notes liner_note
\&      ON liner_note.cdid = me.cdid
\&    JOIN cd_artwork cover_image
\&      ON cover_image.cdid = me.cdid
\&  ORDER BY tracks.cd
.Ve
.PP
Now the \f(CW\*(C`artist\*(C'\fR, \f(CW\*(C`record_label\*(C'\fR, \f(CW\*(C`liner_note\*(C'\fR, \f(CW\*(C`cover_image\*(C'\fR,
\&\f(CW\*(C`tracks\*(C'\fR, and \f(CW\*(C`guests\*(C'\fR of the \s-1CD\s0 will all be available through the
relationship accessors without the need for additional queries to the
database.
.PP
\fI\s-1CAVEATS\s0\fR
.IX Subsection "CAVEATS"
.PP
Prefetch does a lot of deep magic. As such, it may not behave exactly
as you might expect.
.IP "\(bu" 4
Prefetch uses the \*(L"cache\*(R" to populate the prefetched relationships. This
may or may not be what you want.
.IP "\(bu" 4
If you specify a condition on a prefetched relationship, \s-1ONLY\s0 those
rows that match the prefetched condition will be fetched into that relationship.
This means that adding prefetch to a \fBsearch()\fR \fBmay alter\fR what is returned by
traversing a relationship. So, if you have \f(CW\*(C`Artist\->has_many(CDs)\*(C'\fR and you do
.Sp
.Vb 5
\&  my $artist_rs = $schema\->resultset(\*(AqArtist\*(Aq)\->search({
\&      \*(Aqcds.year\*(Aq => 2008,
\&  }, {
\&      join => \*(Aqcds\*(Aq,
\&  });
\&
\&  my $count = $artist_rs\->first\->cds\->count;
\&
\&  my $artist_rs_prefetch = $artist_rs\->search( {}, { prefetch => \*(Aqcds\*(Aq } );
\&
\&  my $prefetch_count = $artist_rs_prefetch\->first\->cds\->count;
\&
\&  cmp_ok( $count, \*(Aq==\*(Aq, $prefetch_count, "Counts should be the same" );
.Ve
.Sp
That \fBcmp_ok()\fR may or may not pass depending on the datasets involved. In other
words the \f(CW\*(C`WHERE\*(C'\fR condition would apply to the entire dataset, just like
it would in regular \s-1SQL.\s0 If you want to add a condition only to the \*(L"right side\*(R"
of a \f(CW\*(C`LEFT JOIN\*(C'\fR \- consider declaring and using a relationship with a custom
condition
.SH "DBIC BIND VALUES"
.IX Header "DBIC BIND VALUES"
Because \s-1DBIC\s0 may need more information to bind values than just the column name
and value itself, it uses a special format for both passing and receiving bind
values.  Each bind value should be composed of an arrayref of
\&\f(CW\*(C`[ \e%args => $val ]\*(C'\fR.  The format of \f(CW\*(C`\e%args\*(C'\fR is currently:
.IP "dbd_attrs" 4
.IX Item "dbd_attrs"
If present (in any form), this is what is being passed directly to bind_param.
Note that different \s-1DBD\s0's expect different bind args.  (e.g. DBD::SQLite takes
a single numerical type, while DBD::Pg takes a hashref if bind options.)
.Sp
If this is specified, all other bind options described below are ignored.
.IP "sqlt_datatype" 4
.IX Item "sqlt_datatype"
If present, this is used to infer the actual bind attribute by passing to
\&\f(CW\*(C`$resolved_storage\->bind_attribute_by_data_type()\*(C'\fR.  Defaults to the
\&\*(L"data_type\*(R" from the add_columns column info.
.Sp
Note that the data type is somewhat freeform (hence the sqlt_ prefix);
currently drivers are expected to \*(L"Do the Right Thing\*(R" when given a common
datatype name.  (Not ideal, but that's what we got at this point.)
.IP "sqlt_size" 4
.IX Item "sqlt_size"
Currently used to correctly allocate buffers for \fBbind_param_inout()\fR.
Defaults to \*(L"size\*(R" from the add_columns column info,
or to a sensible value based on the \*(L"data_type\*(R".
.IP "dbic_colname" 4
.IX Item "dbic_colname"
Used to fill in missing sqlt_datatype and sqlt_size attributes (if they are
explicitly specified they are never overridden).  Also used by some weird DBDs,
where the column name should be available at bind_param time (e.g. Oracle).
.PP
For backwards compatibility and convenience, the following shortcuts are
supported:
.PP
.Vb 4
\&  [ $name => $val ] === [ { dbic_colname => $name }, $val ]
\&  [ \e$dt  => $val ] === [ { sqlt_datatype => $dt }, $val ]
\&  [ undef,   $val ] === [ {}, $val ]
\&  $val              === [ {}, $val ]
.Ve
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.