Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::ResultSetUser Contributed Perl DocumentaDBIx::Class::ResultSet(3)

NAME
       DBIx::Class::ResultSet -	Represents a query used	for fetching a set of
       results.

SYNOPSIS
	 my $users_rs =	$schema->resultset('User');
	 while(	$user =	$users_rs->next) {
	   print $user->username;
	 }

	 my $registered_users_rs = $schema->resultset('User')->search({	registered => 1	});
	 my @cds_in_2005 = $schema->resultset('CD')->search({ year => 2005 })->all();

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).

       No SQL is executed on the database when a ResultSet is created, it just
       stores all the conditions needed	to create the query.

       A basic ResultSet representing the data of an entire table is returned
       by calling "resultset" on a DBIx::Class::Schema and passing in a	Source
       name.

	 my $users_rs =	$schema->resultset('User');

       A new ResultSet is returned from	calling	"search" on an existing
       ResultSet. The new one will contain all the conditions of the original,
       plus any	new conditions added in	the "search" call.

       A ResultSet also	incorporates an	implicit iterator. "next" and "reset"
       can be used to walk through all the DBIx::Class::Rows the ResultSet
       represents.

       The query that the ResultSet represents is only executed	against	the
       database	when these methods are called: "find", "next", "all", "first",
       "single", "count".

       If a resultset is used in a numeric context it returns the "count".
       However,	if it is used in a boolean context it is always	true.  So if
       you want	to check if a resultset	has any	results, you must use "if $rs
       != 0".

EXAMPLES
   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.

	 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('CD')->search({
	     title => $request->param('title'),
	     year => $request->param('year'),
	   });

	   $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,
	   });
	 }

       Resolving conditions and	attributes

       When a resultset	is chained from	another	resultset (e.g.: "my $new_rs =
       $old_rs->search(\%extra_cond, \%attrs)"), conditions and	attributes
       with the	same keys need resolving.

       If any of "columns", "select", "as" are present,	they reset the
       original	selection, and start the selection "clean".

       The "join", "prefetch", "+columns", "+select", "+as" attributes are
       merged into the existing	ones from the original resultset.

       The "where" and "having"	attributes, and	any search conditions, are
       merged with an SQL "AND"	to the existing	condition from the original
       resultset.

       All other attributes are	overridden by any new ones supplied in the
       search attributes.

   Multiple queries
       Since a resultset just defines a	query, you can do all sorts of things
       with it with the	same object.

	 # Don't hit the DB yet.
	 my $cd_rs = $schema->resultset('CD')->search({
	   title => 'something',
	   year	=> 2009,
	 });

	 # Each	of these hits the DB individually.
	 my $count = $cd_rs->count;
	 my $most_recent = $cd_rs->get_column('date_released')->max();
	 my @records = $cd_rs->all;

       And it's	not just limited to SELECT statements.

	 $cd_rs->delete();

       This is even cooler:

	 $cd_rs->create({ artist => 'Fred' });

       Which is	the same as:

	 $schema->resultset('CD')->create({
	   title => 'something',
	   year	=> 2009,
	   artist => 'Fred'
	 });

       See: "search", "count", "get_column", "all", "create".

   Custom ResultSet classes
       To add methods to your resultsets, you can subclass
       DBIx::Class::ResultSet, similar to:

	 package MyApp::Schema::ResultSet::User;

	 use strict;
	 use warnings;

	 use base 'DBIx::Class::ResultSet';

	 sub active {
	   my $self = shift;
	   $self->search({ $self->current_source_alias . '.active' => 1	});
	 }

	 sub unverified	{
	   my $self = shift;
	   $self->search({ $self->current_source_alias . '.verified' =>	0 });
	 }

	 sub created_n_days_ago	{
	   my ($self, $days_ago) = @_;
	   $self->search({
	     $self->current_source_alias . '.create_date' => {
	       '<=',
	     $self->result_source->schema->storage->datetime_parser->format_datetime(
	       DateTime->now( time_zone	=> 'UTC' )->subtract( days => $days_ago	)
	     )}
	   });
	 }

	 sub users_to_warn { shift->active->unverified->created_n_days_ago(7) }

	 1;

       See "load_namespaces" in	DBIx::Class::Schema on how DBIC	can discover
       and automatically attach	Result-specific	ResulSet classes.

       ResultSet subclassing with Moose	and similar constructor-providers

       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. "has	xml_parser", "has json", etc) or if you	just prefer to
       organize	your code via roles.

       In order	to write custom	ResultSet classes with Moo you need to use the
       following template. The BUILDARGS is necessary due to the unusual
       signature of the	constructor provided by	DBIC  "->new($source,
       \%args)".

	 use Moo;
	 extends 'DBIx::Class::ResultSet';
	 sub BUILDARGS { $_[2] } # ::RS::new() expects my ($class, $rsrc, $args) = @_

	 ...your code...

	 1;

       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 DBIC	one.

	 package MyApp::Schema::ResultSet::User;

	 use Moose;
	 use MooseX::NonMoose;
	 extends 'DBIx::Class::ResultSet';

	 sub BUILDARGS { $_[2] } # ::RS::new() expects my ($class, $rsrc, $args) = @_

	 ...your code...

	 __PACKAGE__->meta->make_immutable;

	 1;

       The MooseX::NonMoose is necessary so that the Moose constructor does
       not entirely overwrite the DBIC one (in contrast	Moo does this
       automatically).	Alternatively, you can skip MooseX::NonMoose and get
       by with just Moose instead by doing:

	 __PACKAGE__->meta->make_immutable(inline_constructor => 0);

METHODS
   new
       Arguments: $source, \%attrs?
       Return Value: $resultset

       The resultset constructor. Takes	a source object	(usually a
       DBIx::Class::ResultSourceProxy::Table) and an attribute hash (see
       "ATTRIBUTES" below).  Does not perform any queries -- these are
       executed	as needed by the other methods.

       Generally you never construct a resultset manually. Instead you get one
       from e.g. a "$schema->resultset('$source_name')"	or
       "$another_resultset->search(...)" (the later called in scalar context):

	 my $rs	= $schema->resultset('CD')->search({ title => '100th Window' });

       WARNING
	   If called on	an object, proxies to "new_result" instead, so

	     my	$cd = $schema->resultset('CD')->new({ title => 'Spoon' });

	   will	return a CD object, not	a ResultSet, and is equivalent to:

	     my	$cd = $schema->resultset('CD')->new_result({ title => 'Spoon' });

	   Please also keep in mind that many internals	call "new_result"
	   directly, so	overloading this method	with the idea of intercepting
	   new result object creation will not work. See also warning
	   pertaining to "create".

   search
       Arguments: $cond	| undef, \%attrs?
       Return Value: $resultset	(scalar	context) | @result_objs	(list context)

	 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

       In list context,	"->all()" is called implicitly on the resultset, thus
       returning a list	of result objects instead.  To avoid that, use
       "search_rs".

       If you need to pass in additional attributes but	no additional
       condition, call it as "search(undef, \%attrs)".

	 # "SELECT name, artistid FROM $artist_table"
	 my @all_artists = $schema->resultset('Artist')->search(undef, {
	   columns => [qw/name artistid/],
	 });

       For a list of attributes	that can be passed to "search",	see
       "ATTRIBUTES". For more examples of using	this function, see Searching.
       For a complete documentation for	the first argument, see	"WHERE
       CLAUSES"	in SQL::Abstract and its extension DBIx::Class::SQLMaker.

       For more	help on	using joins with search, see
       DBIx::Class::Manual::Joining.

       CAVEAT

       Note that "search" does not process/deflate any of the values passed in
       the SQL::Abstract-compatible search condition structure.	This is	unlike
       other condition-bound methods "new_result", "create" and	"find".	The
       user must ensure	manually that any value	passed to this method will
       stringify to something the RDBMS	knows how to deal with.	A notable
       example is the handling of DateTime objects, for	more info see:
       "Formatting DateTime objects in queries"	in
       DBIx::Class::Manual::Cookbook.

   search_rs
       Arguments: $cond, \%attrs?
       Return Value: $resultset

       This method does	the same exact thing as	search() except	it will	always
       return a	resultset, even	in list	context.

   search_literal
       CAVEAT: "search_literal"	is provided for	Class::DBI compatibility and
       should only be used in that context. "search_literal" is	a convenience
       method. It is equivalent	to calling "$schema->search(\[])", but if you
       want to ensure columns are bound	correctly, use "search".

       See "SEARCHING" in DBIx::Class::Manual::Cookbook	and "Searching"	in
       DBIx::Class::Manual::FAQ	for searching techniques that do not require
       "search_literal".

       Arguments: $sql_fragment, @standalone_bind_values
       Return Value: $resultset	(scalar	context) | @result_objs	(list context)

	 my @cds   = $cd_rs->search_literal('year = ? AND title	= ?', qw/2001 Reload/);
	 my $newrs = $artist_rs->search_literal('name =	?', 'Metallica');

       Pass a literal chunk of SQL to be added to the conditional part of the
       resultset query.

       Example of how to use "search" instead of "search_literal"

	 my @cds = $cd_rs->search_literal('cdid	= ? AND	(artist	= ? OR artist =	?)', (2, 1, 2));
	 my @cds = $cd_rs->search(\[ 'cdid = ? AND (artist = ? OR artist = ?)',	[ 'cdid', 2 ], [ 'artist', 1 ],	[ 'artist', 2 ]	]);

   find
       Arguments: \%columns_values | @pk_values, { key => $unique_constraint,
       %attrs }?
       Return Value: $result | undef

       Finds and returns a single row based on supplied	criteria. Takes	either
       a hashref with the same format as "create" (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
       "result_source".

       In either case an attempt is made to combine conditions already
       existing	on the resultset with the condition passed to this method.

       To aid with preparing the correct query for the storage you may supply
       the "key" attribute, which is the name of a unique constraint (the
       unique constraint corresponding to the primary columns is always	named
       "primary"). If the "key"	attribute has been supplied, and DBIC 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.

       If no "key" is specified, the search is carried over all	unique
       constraints which are fully defined by the available condition.

       If no such constraint is	found, "find" currently	defaults to a simple
       "search->(\%column_values)" 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 "search". 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 $result_object.

       In addition to "key", "find" recognizes and applies standard resultset
       attributes in the same way as "search" does.

       Note that if you	have extra concerns about the correctness of the
       resulting query you need	to specify the "key" 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).

       For example, to find a row by its primary key:

	 my $cd	= $schema->resultset('CD')->find(5);

       You can also find a row by a specific unique constraint:

	 my $cd	= $schema->resultset('CD')->find(
	   {
	     artist => 'Massive	Attack',
	     title  => 'Mezzanine',
	   },
	   { key => 'cd_artist_title' }
	 );

       See also	"find_or_create" and "update_or_create".

   search_related
       Arguments: $rel_name, $cond?, \%attrs?
       Return Value: $resultset	(scalar	context) | @result_objs	(list context)

	 $new_rs = $cd_rs->search_related('artist', {
	   name	=> 'Emo-R-Us',
	 });

       Searches	the specified relationship, optionally specifying a condition
       and attributes for matching records. See	"ATTRIBUTES" for more
       information.

       In list context,	"->all()" is called implicitly on the resultset, thus
       returning a list	of result objects instead. To avoid that, use
       "search_related_rs".

       See also	"search_related_rs".

   search_related_rs
       This method works exactly the same as search_related, except that it
       guarantees a resultset, even in list context.

   cursor
       Arguments: none
       Return Value: $cursor

       Returns a storage-driven	cursor to the given resultset. See
       DBIx::Class::Cursor for more information.

   single
       Arguments: $cond?
       Return Value: $result | undef

	 my $cd	= $schema->resultset('CD')->single({ year => 2001 });

       Inflates	the first result without creating a cursor if the resultset
       has any records in it; if not returns "undef". Used by "find" as	a lean
       version of "search".

       While this method can take an optional search condition (just like
       "search") being a fast-code-path	it does	not recognize search
       attributes. If you need to add extra joins or similar, call "search"
       and then	chain-call "single" on the DBIx::Class::ResultSet returned.

       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:

	     Query returned more than one row

	   In this case, you should be using "next" or "find" instead, or if
	   you really know what	you are	doing, use the "rows" attribute	to
	   explicitly limit the	size of	the resultset.

	   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.

   get_column
       Arguments: $cond?
       Return Value: $resultsetcolumn

	 my $max_length	= $rs->get_column('length')->max;

       Returns a DBIx::Class::ResultSetColumn instance for a column of the
       ResultSet.

   search_like
       Arguments: $cond, \%attrs?
       Return Value: $resultset	(scalar	context) | @result_objs	(list context)

	 # WHERE title LIKE '%blue%'
	 $cd_rs	= $rs->search_like({ title => '%blue%'});

       Performs	a search, but uses "LIKE" instead of "=" as the	condition.
       Note that this is simply	a convenience method retained for ex
       Class::DBI users.  You most likely want to use "search" with specific
       operators.

       For more	information, see DBIx::Class::Manual::Cookbook.

       This method is deprecated and will be removed in	0.09. Use search()
       instead.	An example conversion is:

	 ->search_like({ foo =>	'bar' });

	 # Becomes

	 ->search({ foo	=> { like => 'bar' } });

   slice
       Arguments: $first, $last
       Return Value: $resultset	(scalar	context) | @result_objs	(list context)

       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:

	 my ($one, $two, $three) = $rs->slice(0, 2);

   next
       Arguments: none
       Return Value: $result | undef

       Returns the next	element	in the resultset ("undef" is there is none).

       Can be used to efficiently iterate over records in the resultset:

	 my $rs	= $schema->resultset('CD')->search;
	 while (my $cd = $rs->next) {
	   print $cd->title;
	 }

       Note that you need to store the resultset object, and call "next" on
       it.  Calling "resultset('Table')->next" repeatedly will always return
       the first record	from the resultset.

   result_source
       Arguments: $result_source?
       Return Value: $result_source

       An accessor for the primary ResultSource	object from which this
       ResultSet is derived.

   result_class
       Arguments: $result_class?
       Return Value: $result_class

       An accessor for the class to use	when creating result objects. Defaults
       to "result_source->result_class"	- which	in most	cases is the name of
       the "table" class.

       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.

   count
       Arguments: $cond, \%attrs?
       Return Value: $count

       Performs	an SQL "COUNT" with the	same query as the resultset was	built
       with to find the	number of elements. Passing arguments is equivalent to
       "$rs->search ($cond, \%attrs)->count"

   count_rs
       Arguments: $cond, \%attrs?
       Return Value: $count_rs

       Same as "count" but returns a DBIx::Class::ResultSetColumn object.
       This can	be very	handy for subqueries:

	 ->search( { amount => $some_rs->count_rs->as_query } )

       As with regular resultsets the SQL query	will be	executed only after
       the resultset is	accessed via "next" or "all". That would return	the
       same single value obtainable via	"count".

   count_literal
       CAVEAT: "count_literal" is provided for Class::DBI compatibility	and
       should only be used in that context. See	"search_literal" for further
       info.

       Arguments: $sql_fragment, @standalone_bind_values
       Return Value: $count

       Counts the results in a literal query. Equivalent to calling
       "search_literal"	with the passed	arguments, then	"count".

   all
       Arguments: none
       Return Value: @result_objs

       Returns all elements in the resultset.

   reset
       Arguments: none
       Return Value: $self

       Resets the resultset's cursor, so you can iterate through the elements
       again.  Implicitly resets the storage cursor, so	a subsequent "next"
       will trigger another query.

   first
       Arguments: none
       Return Value: $result | undef

       Resets the resultset (causing a fresh query to storage) and returns an
       object for the first result (or "undef" if the resultset	is empty).

   update
       Arguments: \%values
       Return Value: $underlying_storage_rv

       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 "update_all" if you	need
       to execute any on-update	triggers or cascades defined either by you or
       a result	component.

       The return value	is a pass through of what the underlying storage
       backend returned, and may vary. See "execute" in	DBI for	the most
       common case.

       CAVEAT

       Note that "update" does not process/deflate any of the values passed
       in.  This is unlike the corresponding "update" in DBIx::Class::Row. The
       user must ensure	manually that any value	passed to this method will
       stringify to something the RDBMS	knows how to deal with.	A notable
       example is the handling of DateTime objects, for	more info see:
       "Formatting DateTime objects in queries"	in
       DBIx::Class::Manual::Cookbook.

   update_all
       Arguments: \%values
       Return Value: 1

       Fetches all objects and updates them one	at a time via "update" in
       DBIx::Class::Row. Note that "update_all"	will run DBIC defined
       triggers, while "update"	will not.

   delete
       Arguments: none
       Return Value: $underlying_storage_rv

       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 "delete_all"
       if you need to execute any on-delete triggers or	cascades defined
       either by you or	a result component.

       The return value	is a pass through of what the underlying storage
       backend returned, and may vary. See "execute" in	DBI for	the most
       common case.

   delete_all
       Arguments: none
       Return Value: 1

       Fetches all objects and deletes them one	at a time via "delete" in
       DBIx::Class::Row. Note that "delete_all"	will run DBIC defined
       triggers, while "delete"	will not.

   populate
       Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ]
       Return Value: \@result_objects (scalar context) | @result_objects (list
       context)

       Accepts either an arrayref of hashrefs or alternatively an arrayref of
       arrayrefs.

       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 "execute_for_fetch" in DBI), 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.

       In non-void (scalar or list) context, this method is simply a wrapper
       for "create". Depending on list or scalar context either	a list of
       Result objects or an arrayref containing	these objects is returned.

       When supplying data in "arrayref	of arrayrefs" 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:

	 $schema->resultset("Artist")->populate([
	   [ qw( artistid name ) ],
	   [ 100, 'A Formally Unknown Singer' ],
	   [ 101, 'A singer that jumped	the shark two albums ago' ],
	   [ 102, 'An actually cool singer' ],
	 ]);

       For the arrayref	of hashrefs style each hashref should be a structure
       suitable	for passing to "create". Multi-create is also permitted	with
       this syntax.

	 $schema->resultset("Artist")->populate([
	    { artistid => 4, name => 'Manufactured Crap', cds => [
	       { title => 'My First CD', year => 2006 },
	       { title => 'Yet More Tweeny-Pop crap', year => 2007 },
	     ],
	    },
	    { artistid => 5, name => 'Angsty-Whiny Girl', cds => [
	       { title => 'My parents sold me to a record company', year => 2005 },
	       { title => 'Why Am I So Ugly?', year => 2006 },
	       { title => 'I Got Surgery and am	now Popular', year => 2007 }
	     ],
	    },
	 ]);

       If you attempt a	void-context multi-create as in	the example above
       (each Artist also has the related list of CDs), and do not supply the
       necessary autoinc foreign key information, this method will proxy to
       the less	efficient "create", and	then throw the Result objects away. In
       this case there are obviously no	benefits to using this method over
       "create".

   pager
       Arguments: none
       Return Value: $pager

       Returns a Data::Page object for the current resultset. Only makes sense
       for queries with	a "page" attribute.

       To get the full count of	entries	for a paged resultset, call
       "total_entries" on the Data::Page object.

   page
       Arguments: $page_number
       Return Value: $resultset

       Returns a resultset for the $page_number	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).

   new_result
       Arguments: \%col_data
       Return Value: $result

       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
       "insert"	in DBIx::Class::Row to do that.	Calling	"in_storage" in
       DBIx::Class::Row	will tell you whether the result object	has been
       inserted	or not.

       Passes the hashref of input on to "new" in DBIx::Class::Row.

   as_query
       Arguments: none
       Return Value: \[	$sql, @bind_values ]

       Returns the SQL query and bind vars associated with the invocant.

       This is generally used as the RHS for a subquery.

   find_or_new
       Arguments: \%col_data, {	key => $unique_constraint, %attrs }?
       Return Value: $result

	 my $artist = $schema->resultset('Artist')->find_or_new(
	   { artist => 'fred' }, { key => 'artists' });

	 $cd->cd_to_producer->find_or_new({ producer =>	$producer },
					  { key	=> 'primary' });

       Find an existing	record from this resultset using "find". if none
       exists, instantiate a new result	object and return it. The object will
       not be saved into your storage until you	call "insert" in
       DBIx::Class::Row	on it.

       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.

       If you want objects to be saved immediately, use	"find_or_create"
       instead.

       Note: Make sure to read the documentation of "find" and understand the
       significance of the "key" attribute, as its lack	may skew your search,
       and subsequently	result in spurious new objects.

       Note: Take care when using "find_or_new"	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	NOT be included	at all in the call to
       "find_or_new", even when	set to "undef".

   create
       Arguments: \%col_data
       Return Value: $result

       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
       "find_or_create"	to do that.

       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.

       To create related objects, pass a hashref of related-object column
       values keyed on the relationship	name. If the relationship is of	type
       "multi" ("has_many" 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.

       Instead of hashrefs of plain related data (key/value pairs), you	may
       also pass new or	inserted objects. New objects (not inserted yet, see
       "new_result"), will be inserted into their appropriate tables.

       Effectively a shortcut for "->new_result(\%col_data)->insert".

       Example of creating a new row.

	 $person_rs->create({
	   name=>"Some Person",
	   email=>"somebody@someplace.com"
	 });

       Example of creating a new row and also creating rows in a related
       "has_many" or "has_one" resultset.  Note	Arrayref.

	 $artist_rs->create(
	    { artistid => 4, name => 'Manufactured Crap', cds => [
	       { title => 'My First CD', year => 2006 },
	       { title => 'Yet More Tweeny-Pop crap', year => 2007 },
	     ],
	    },
	 );

       Example of creating a new row and also creating a row in	a related
       "belongs_to" resultset. Note Hashref.

	 $cd_rs->create({
	   title=>"Music for Silly Walks",
	   year=>2000,
	   artist => {
	     name=>"Silly Musician",
	   }
	 });

       WARNING
	   When	subclassing ResultSet never attempt to override	this method.
	   Since it is a simple	shortcut for
	   "$self->new_result($attrs)->insert",	a lot of the internals simply
	   never call it, so your override will	be bypassed more often than
	   not.	Override either	"new" in DBIx::Class::Row or "insert" in
	   DBIx::Class::Row depending on how early in the "create" process you
	   need	to intervene. See also warning pertaining to "new".

   find_or_create
       Arguments: \%col_data, {	key => $unique_constraint, %attrs }?
       Return Value: $result

	 $cd->cd_to_producer->find_or_create({ producer	=> $producer },
					     { key => 'primary'	});

       Tries to	find a record based on its primary key or unique constraints;
       if none is found, creates one and returns that instead.

	 my $cd	= $schema->resultset('CD')->find_or_create({
	   cdid	  => 5,
	   artist => 'Massive Attack',
	   title  => 'Mezzanine',
	   year	  => 2005,
	 });

       Also takes an optional "key" attribute, to search by a specific key or
       unique constraint. For example:

	 my $cd	= $schema->resultset('CD')->find_or_create(
	   {
	     artist => 'Massive	Attack',
	     title  => 'Mezzanine',
	   },
	   { key => 'cd_artist_title' }
	 );

       Note: Make sure to read the documentation of "find" and understand the
       significance of the "key" attribute, as its lack	may skew your search,
       and subsequently	result in spurious row creation.

       Note: Because find_or_create() 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 find_or_create() inside a transaction.

       Note: Take care when using "find_or_create" 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	NOT be included	at all in the call to
       "find_or_create", even when set to "undef".

       See also	"find" and "update_or_create". For information on how to
       declare unique constraints, see "add_unique_constraint" in
       DBIx::Class::ResultSource.

       If you need to know if an existing row was found	or a new one created
       use "find_or_new" and "in_storage" in DBIx::Class::Row instead. Don't
       forget to call "insert" in DBIx::Class::Row to save the newly created
       row to the database!

	 my $cd	= $schema->resultset('CD')->find_or_new({
	   cdid	  => 5,
	   artist => 'Massive Attack',
	   title  => 'Mezzanine',
	   year	  => 2005,
	 });

	 if( !$cd->in_storage )	{
	     # do some stuff
	     $cd->insert;
	 }

   update_or_create
       Arguments: \%col_data, {	key => $unique_constraint, %attrs }?
       Return Value: $result

	 $resultset->update_or_create({	col => $val, ... });

       Like "find_or_create", but if a row is found it is immediately updated
       via "$found_row->update (\%col_data)".

       Takes an	optional "key" attribute to search on a	specific unique
       constraint.  For	example:

	 # In your application
	 my $cd	= $schema->resultset('CD')->update_or_create(
	   {
	     artist => 'Massive	Attack',
	     title  => 'Mezzanine',
	     year   => 1998,
	   },
	   { key => 'cd_artist_title' }
	 );

	 $cd->cd_to_producer->update_or_create({
	   producer => $producer,
	   name	=> 'harry',
	 }, {
	   key => 'primary',
	 });

       Note: Make sure to read the documentation of "find" and understand the
       significance of the "key" attribute, as its lack	may skew your search,
       and subsequently	result in spurious row creation.

       Note: Take care when using "update_or_create" 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 NOT be	included at
       all in the call to "update_or_create", even when	set to "undef".

       See also	"find" and "find_or_create". For information on	how to declare
       unique constraints, see "add_unique_constraint" in
       DBIx::Class::ResultSource.

       If you need to know if an existing row was updated or a new one created
       use "update_or_new" and "in_storage" in DBIx::Class::Row	instead. Don't
       forget to call "insert" in DBIx::Class::Row to save the newly created
       row to the database!

   update_or_new
       Arguments: \%col_data, {	key => $unique_constraint, %attrs }?
       Return Value: $result

	 $resultset->update_or_new({ col => $val, ... });

       Like "find_or_new" but if a row is found	it is immediately updated via
       "$found_row->update (\%col_data)".

       For example:

	 # In your application
	 my $cd	= $schema->resultset('CD')->update_or_new(
	   {
	     artist => 'Massive	Attack',
	     title  => 'Mezzanine',
	     year   => 1998,
	   },
	   { key => 'cd_artist_title' }
	 );

	 if ($cd->in_storage) {
	     # the cd was updated
	 }
	 else {
	     # the cd is not yet in the	database, let's	insert it
	     $cd->insert;
	 }

       Note: Make sure to read the documentation of "find" and understand the
       significance of the "key" attribute, as its lack	may skew your search,
       and subsequently	result in spurious new objects.

       Note: Take care when using "update_or_new" 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	NOT be included	at all in the call to
       "update_or_new",	even when set to "undef".

       See also	"find",	"find_or_create" and "find_or_new".

   get_cache
       Arguments: none
       Return Value: \@result_objs | undef

       Gets the	contents of the	cache for the resultset, if the	cache is set.

       The cache is populated either by	using the "prefetch" attribute to
       "search"	or by calling "set_cache".

   set_cache
       Arguments: \@result_objs
       Return Value: \@result_objs

       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.

       The contents of the cache can also be populated by using	the "prefetch"
       attribute to "search".

   clear_cache
       Arguments: none
       Return Value: undef

       Clears the cache	for the	resultset.

   is_paged
       Arguments: none
       Return Value: true, if the resultset has	been paginated

   is_ordered
       Arguments: none
       Return Value: true, if the resultset has	been ordered with "order_by".

   related_resultset
       Arguments: $rel_name
       Return Value: $resultset

       Returns a related resultset for the supplied relationship name.

	 $artist_rs = $schema->resultset('CD')->related_resultset('Artist');

   current_source_alias
       Arguments: none
       Return Value: $source_alias

       Returns the current table alias for the result source this resultset is
       built on, that will be used in the SQL query. Usually it	is "me".

       Currently the source alias that refers to the result set	returned by a
       "search"/"find" family method depends on	how you	got to the resultset:
       it's "me" by default, but eg. "search_related" aliases it to the
       related result source name (and keeps "me" referring to the original
       result set). The	long term goal is to make DBIx::Class always alias the
       current resultset as "me" (and make this	method unnecessary).

       Thus it's currently necessary to	use this method	in predefined queries
       (see "Predefined	searches" in DBIx::Class::Manual::Cookbook) when
       referring to the	source alias of	the current result set:

	 # in a	result set class
	 sub modified_by {
	   my ($self, $user) = @_;

	   my $me = $self->current_source_alias;

	   return $self->search({
	     "$me.modified" => $user->id,
	   });
	 }

       The alias of newly created resultsets can be altered by the alias
       attribute.

   as_subselect_rs
       Arguments: none
       Return Value: $resultset

       Act as a	barrier	to SQL symbols.	 The resultset provided	will be	made
       into a "virtual view" 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:

	my $rs = $schema->resultset('Bar')->search({'x.name' =>	'abc'},{ join => 'x' });

	# 'x' now pollutes the query namespace

	# So the following works as expected
	my $ok_rs = $rs->search({'x.other' => 1});

	# But this doesn't: instead of finding a 'Bar' related to two x	rows (abc and
	# def) we look for one row with	contradictory terms and	join in	another	table
	# (aliased 'x_2') which	we never use
	my $broken_rs =	$rs->search({'x.name' => 'def'});

	my $rs2	= $rs->as_subselect_rs;

	# doesn't work - 'x' is	no longer accessible in	$rs2, having been sealed away
	my $not_joined_rs = $rs2->search({'x.other' => 1});

	# works	as expected: finds a 'table' row related to two	x rows (abc and	def)
	my $correctly_joined_rs	= $rs2->search({'x.name' => 'def'});

       Another example of when one might use this would	be to select a subset
       of columns in a group by	clause:

	my $rs = $schema->resultset('Bar')->search(undef, {
	  group_by => [qw{ id foo_id baz_id }],
	})->as_subselect_rs->search(undef, {
	  columns => [qw{ id foo_id }]
	});

       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.

   throw_exception
       See "throw_exception" in	DBIx::Class::Schema for	details.

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
       "\%attrs" argument. See "search", "search_rs", "find", "count".

       Default attributes can be set on	the result class using
       "resultset_attributes" in DBIx::Class::ResultSource.  (Please read the
       CAVEATS on that feature before using it!)

       These are in no particular order:

   order_by
       Value: (	$order_by | \@order_by | \%order_by )

       Which column(s) to order	the results by.

       [The full list of suitable values is documented in "ORDER BY CLAUSES"
       in SQL::Abstract; the following is a summary of common options.]

       If a single column name,	or an arrayref of names	is supplied, the
       argument	is passed through directly to SQL. The hashref syntax allows
       for connection-agnostic specification of	ordering direction:

	For descending order:

	 order_by => { -desc =>	[qw/col1 col2 col3/] }

	For explicit ascending order:

	 order_by => { -asc => 'col' }

       The old scalarref syntax	(i.e. order_by => \'year DESC')	is still
       supported, although you are strongly encouraged to use the hashref
       syntax as outlined above.

   columns
       Value: \@columns	| \%columns | $column

       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 "as"	value, and the value is	used as	the "select"
       expression). Adds the "current_source_alias" onto the start of any
       column without a	"." in it and sets "select" from that, then auto-
       populates "as" from "select" as normal. (You may	also use the "cols"
       attribute, as in	earlier	versions of DBIC, but this is deprecated)

       Essentially "columns" does the same as "select" and "as".

	   columns => [	'some_column', { dbic_slot => 'another_column' } ]

       is the same as

	   select => [qw(some_column another_column)],
	   as	  => [qw(some_column dbic_slot)]

       If you want to individually retrieve related columns (in	essence
       perform manual "prefetch") you have to make sure	to specify the correct
       inflation slot chain such that it matches existing relationships:

	   my $rs = $schema->resultset('Artist')->search({}, {
	       # required to tell DBIC to collapse has_many relationships
	       collapse	=> 1,
	       join	=> { cds => 'tracks' },
	       '+columns'  => {
		 'cds.cdid'	    => 'cds.cdid',
		 'cds.tracks.title' => 'tracks.title',
	       },
	   });

       Like elsewhere, literal SQL 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 "get_column" (see also "Literal SQL	and
       value type operators" in	SQL::Abstract):

	   # equivalent	SQL: SELECT 1, 'a string', IF(my_column,?,?) ...
	   # bind values: $true_value, $false_value
	   columns => [
	       {
		   foo => \1,
		   bar => \q{'a	string'},
		   baz => \[ 'IF(my_column,?,?)', $true_value, $false_value ],
	       }
	   ]

   +columns
       NOTE: You MUST explicitly quote '+columns' when using this attribute.
       Not doing so causes Perl	to incorrectly interpret "+columns" as a
       bareword	with a unary plus operator before it, which is the same	as
       simply "columns".

       Value: \@extra_columns

       Indicates additional columns to be selected from	storage. Works the
       same as "columns" but adds columns to the current selection. (You may
       also use	the "include_columns" attribute, as in earlier versions	of
       DBIC, but this is deprecated)

	 $schema->resultset('CD')->search(undef, {
	   '+columns' => ['artist.name'],
	   join	=> ['artist']
	 });

       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.

   select
       Value: \@select_columns

       Indicates which columns should be selected from the storage. You	can
       use column names, or in the case	of RDBMS back ends, function or	stored
       procedure names:

	 $rs = $schema->resultset('Employee')->search(undef, {
	   select => [
	     'name',
	     { count =>	'employeeid' },
	     { max => {	length => 'name' }, -as	=> 'longest_name' }
	   ]
	 });

	 # Equivalent SQL
	 SELECT	name, COUNT( employeeid	), MAX(	LENGTH(	name ) ) AS longest_name FROM employee

       NOTE: You will almost always need a corresponding "as" attribute	when
       you use "select", to instruct DBIx::Class how to	store the result of
       the column.

       Also note that the "as" attribute has nothing to	do with	the SQL-side
       "AS" identifier aliasing. You can alias a function (so you can use it
       e.g.  in	an "ORDER BY" clause), however this is done via	the "-as"
       select function attribute supplied as shown in the example above.

   +select
       NOTE: You MUST explicitly quote '+select' when using this attribute.
       Not doing so causes Perl	to incorrectly interpret "+select" as a
       bareword	with a unary plus operator before it, which is the same	as
       simply "select".

       Value: \@extra_select_columns

       Indicates additional columns to be selected from	storage.  Works	the
       same as "select"	but adds columns to the	current	selection, instead of
       specifying a new	explicit list.

   as
       Value: \@inflation_names

       Indicates DBIC-side names for object inflation. That is "as" 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
       "get_column" method (or via the object accessor if one with the same
       name already exists) as shown below.

       The "as"	attribute has nothing to do with the SQL-side identifier
       aliasing	"AS". See "select" for details.

	 $rs = $schema->resultset('Employee')->search(undef, {
	   select => [
	     'name',
	     { count =>	'employeeid' },
	     { max => {	length => 'name' }, -as	=> 'longest_name' }
	   ],
	   as => [qw/
	     name
	     employee_count
	     max_name_length
	   /],
	 });

       If the object against which the search is performed already has an
       accessor	matching a column name specified in "as", the value can	be
       retrieved using the accessor as normal:

	 my $name = $employee->name();

       If on the other hand an accessor	does not exist in the object, you need
       to use "get_column" instead:

	 my $employee_count = $employee->get_column('employee_count');

       You can create your own accessors if required - see
       DBIx::Class::Manual::Cookbook for details.

   +as
       NOTE: You MUST explicitly quote '+as' when using	this attribute.	 Not
       doing so	causes Perl to incorrectly interpret "+as" as a	bareword with
       a unary plus operator before it,	which is the same as simply "as".

       Value: \@extra_inflation_names

       Indicates additional inflation names for	selectors added	via "+select".
       See "as".

   join
       Value: ($rel_name | \@rel_names | \%rel_names)

       Contains	a list of relationships	that should be joined for this query.
       For example:

	 # Get CDs by Nine Inch	Nails
	 my $rs	= $schema->resultset('CD')->search(
	   { 'artist.name' => 'Nine Inch Nails'	},
	   { join => 'artist' }
	 );

       Can also	contain	a hash reference to refer to the other relation's
       relations.  For example:

	 package MyApp::Schema::Track;
	 use base qw/DBIx::Class/;
	 __PACKAGE__->table('track');
	 __PACKAGE__->add_columns(qw/trackid cd	position title/);
	 __PACKAGE__->set_primary_key('trackid');
	 __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
	 1;

	 # In your application
	 my $rs	= $schema->resultset('Artist')->search(
	   { 'track.title' => 'Teardrop' },
	   {
	     join     => { cd => 'track' },
	     order_by => 'artist.name',
	   }
	 );

       You need	to use the relationship	(not the table)	name in	 conditions,
       because they are	aliased	as such. The current table is aliased as "me",
       so you need to use me.column_name in order to avoid ambiguity. For
       example:

	 # Get CDs from	1984 with a 'Foo' track
	 my $rs	= $schema->resultset('CD')->search(
	   {
	     'me.year' => 1984,
	     'tracks.name' => 'Foo'
	   },
	   { join => 'tracks' }
	 );

       If the same join	is supplied twice, it will be aliased to <rel>_2 (and
       similarly for a third time). For	e.g.

	 my $rs	= $schema->resultset('Artist')->search({
	   'cds.title'	 => 'Down to Earth',
	   'cds_2.title' => 'Popular',
	 }, {
	   join	=> [ qw/cds cds/ ],
	 });

       will return a set of all	artists	that have both a cd with title 'Down
       to Earth' and a cd with title 'Popular'.

       If you want to fetch related objects from other tables as well, see
       "prefetch" below.

	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.

       For more	help on	using joins with search, see
       DBIx::Class::Manual::Joining.

   collapse
       Value: (0 | 1)

       When set	to a true value, indicates that	any rows fetched from joined
       has_many	relationships are to be	aggregated into	the corresponding
       "parent"	object.	For example, the resultset:

	 my $rs	= $schema->resultset('CD')->search({}, {
	   '+columns' => [ qw/ tracks.title tracks.position / ],
	   join	=> 'tracks',
	   collapse => 1,
	 });

       While executing the following query:

	 SELECT	me.*, tracks.title, tracks.position
	   FROM	cd me
	   LEFT	JOIN track tracks
	     ON	tracks.cdid = me.cdid

       Will return only	as many	objects	as there are rows in the CD source,
       even though the result of the query may span many rows. Each of these
       CD objects will in turn have multiple "Track" objects hidden behind the
       has_many	generated accessor "tracks". Without "collapse => 1", the
       return values of	this resultset would be	as many	CD objects as there
       are tracks (a "Cartesian	product"), with	each CD	object containing
       exactly one of all fetched Track	data.

       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
       "lazy" -	calling	$rs->next will fetch only as many rows as it needs to
       build the next object with all of its related data.

       If an "order_by"	is already declared, and orders	the resultset in a way
       that makes collapsing as	described above	impossible (e.g. "ORDER	BY
       has_many_rel.column" or "ORDER BY RANDOM()"), DBIC will automatically
       switch to "eager" mode and slurp	the entire resultset before
       constructing the	first object returned by "next".

       Setting this attribute on a resultset that does not join	any has_many
       relations is a no-op.

       For a more in-depth discussion, see "PREFETCHING".

   prefetch
       Value: ($rel_name | \@rel_names | \%rel_names)

       This attribute is a shorthand for specifying a "join" spec, adding all
       columns from the	joined related sources as "+columns" and setting
       "collapse" to a true value. It can be thought of	as a rough superset of
       the "join" attribute.

       For example, the	following two queries are equivalent:

	 my $rs	= $schema->resultset('Artist')->search({}, {
	   prefetch => { cds =>	['genre', 'tracks' ] },
	 });

       and

	 my $rs	= $schema->resultset('Artist')->search({}, {
	   join	=> { cds => ['genre', 'tracks' ] },
	   collapse => 1,
	   '+columns' => [
	     (map
	       { +{ "cds.$_" =>	"cds.$_" } }
	       $schema->source('Artist')->related_source('cds')->columns
	     ),
	     (map
	       { +{ "cds.genre.$_" => "genre.$_" } }
	       $schema->source('Artist')->related_source('cds')->related_source('genre')->columns
	     ),
	     (map
	       { +{ "cds.tracks.$_" => "tracks.$_" } }
	       $schema->source('Artist')->related_source('cds')->related_source('tracks')->columns
	     ),
	   ],
	 });

       Both producing the following SQL:

	 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

       While "prefetch"	implies	a "join", 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:

	 my $artists_and_cds_without_genre = $schema->resultset('Artist')->search(
	   { 'genre.genreid' =>	undef },
	   {
	     join => { cds => 'genre' },
	     prefetch => 'cds',
	   }
	 );

       Which generates the following SQL:

	 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

       For a more in-depth discussion, see "PREFETCHING".

   alias
       Value: $source_alias

       Sets the	source alias for the query.  Normally, this defaults to	"me",
       but nested search queries (sub-SELECTs) might need specific aliases set
       to reference inner queries.  For	example:

	  my $q	= $rs
	     ->related_resultset('CDs')
	     ->related_resultset('Tracks')
	     ->search({
		'track.id' => {	-ident => 'none_search.id' },
	     })
	     ->as_query;

	  my $ids = $self->search({
	     -not_exists => $q,
	  }, {
	     alias    => 'none_search',
	     group_by => 'none_search.id',
	  })->get_column('id')->as_query;

	  $self->search({ id =>	{ -in => $ids }	})

       This attribute is directly tied to "current_source_alias".

   page
       Value: $page

       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.

       If "rows" attribute is not specified it defaults	to 10 rows per page.

       When you	have a paged resultset,	"count"	will only return the number of
       rows in the page. To get	the total, use the "pager" and call
       "total_entries" on it.

   rows
       Value: $rows

       Specifies the maximum number of rows for	direct retrieval or the	number
       of rows per page	if the page attribute or method	is used.

   offset
       Value: $offset

       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.

   software_limit
       Value: (0 | 1)

       When combined with "rows" and/or	"offset" the generated SQL will	not
       include any limit dialect stanzas. Instead the entire result will be
       selected	as if no limits	were specified,	and DBIC will perform the
       limit locally, by artificially advancing	and finishing the resulting
       "cursor".

       This is the recommended way of performing resultset limiting when no
       sane RDBMS implementation is available (e.g.  Sybase ASE	using the
       Generic Sub Query hack)

   group_by
       Value: \@columns

       A arrayref of columns to	group by. Can include columns of joined
       tables.

	 group_by => [qw/ column1 column2 ... /]

   having
       Value: $condition

       The HAVING operator specifies a secondary condition applied to the set
       after the grouping calculations have been done. In other	words it is a
       constraint just like "where" (and accepting the same SQL::Abstract
       syntax) applied to the data as it exists	after GROUP BY has taken
       place. Specifying "having" without "group_by" is	a logical mistake, and
       a fatal error on	most RDBMS engines.

       E.g.

	 having	=> { 'count_employee' => { '>=', 100 } }

       or with an in-place function in which case literal SQL is required:

	 having	=> \[ 'count(employee) >= ?', 100 ]

   distinct
       Value: (0 | 1)

       Set to 1	to automatically generate a "group_by" clause based on the
       selection (including intelligent	handling of "order_by" contents). Note
       that the	group criteria calculation takes place over the	final
       selection. This includes	any "+columns",	"+select" or "order_by"
       additions in subsequent "search"	calls, and standalone columns selected
       via DBIx::Class::ResultSetColumn	("get_column").	A notable exception
       are the extra selections	specified via "prefetch" - such	selections are
       explicitly excluded from	group criteria calculations.

       If the final ResultSet also explicitly defines a	"group_by" attribute,
       this setting is ignored and an appropriate warning is issued.

   where
	   Adds	to the WHERE clause.

	     # only return rows	WHERE deleted IS NULL for all searches
	     __PACKAGE__->resultset_attributes({ where => { deleted => undef } });

	   Can be overridden by	passing	"{ where => undef }" as	an attribute
	   to a	resultset.

	   For more complicated	where clauses see "WHERE CLAUSES" in
	   SQL::Abstract.

   cache
       Set to 1	to cache search	results. This prevents extra SQL queries if
       you revisit rows	in your	ResultSet:

	 my $resultset = $schema->resultset('Artist')->search( undef, {	cache => 1 } );

	 while(	my $artist = $resultset->next )	{
	   ... do stuff	...
	 }

	 $rs->first; # without cache, this would issue a query

       By default, searches are	not cached.

       For more	examples of using these	attributes, see
       DBIx::Class::Manual::Cookbook.

   for
       Value: (	'update' | 'shared' | \$scalar )

       Set to 'update' for a SELECT ...	FOR UPDATE or 'shared' for a SELECT
       ... FOR SHARED. If \$scalar is passed, this is taken directly and
       embedded	in the query.

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.

       Here are	some more involved examples, based on the following
       relationship map:

	 # Assuming:
	 My::Schema::CD->belongs_to( artist	 => 'My::Schema::Artist'     );
	 My::Schema::CD->might_have( liner_note	 => 'My::Schema::LinerNotes' );
	 My::Schema::CD->has_many(   tracks	 => 'My::Schema::Track'	     );

	 My::Schema::Artist->belongs_to( record_label => 'My::Schema::RecordLabel' );

	 My::Schema::Track->has_many( guests =>	'My::Schema::Guest' );

	 my $rs	= $schema->resultset('Tag')->search(
	   undef,
	   {
	     prefetch => {
	       cd => 'artist'
	     }
	   }
	 );

       The initial search results in SQL like the following:

	 SELECT	tag.*, cd.*, artist.* FROM tag
	 JOIN cd ON tag.cd = cd.cdid
	 JOIN artist ON	cd.artist = artist.artistid

       DBIx::Class has no need to go back to the database when we access the
       "cd" or "artist"	relationships, which saves us two SQL statements in
       this case.

       Simple prefetches will be joined	automatically, so there	is no need for
       a "join"	attribute in the above search.

       The "prefetch" 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 CD's artist, its liner	notes (if
       present), the cover image, the tracks on	that CD, and the guests	on
       those tracks.

	 my $rs	= $schema->resultset('CD')->search(
	   undef,
	   {
	     prefetch => [
	       { artist	=> 'record_label'},  # belongs_to => belongs_to
	       'liner_note',		     # might_have
	       'cover_image',		     # has_one
	       { tracks	=> 'guests' },	     # has_many	=> has_many
	     ]
	   }
	 );

       This will produce SQL like the following:

	 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

       Now the "artist", "record_label", "liner_note", "cover_image",
       "tracks", and "guests" of the CD	will all be available through the
       relationship accessors without the need for additional queries to the
       database.

       CAVEATS

       Prefetch	does a lot of deep magic. As such, it may not behave exactly
       as you might expect.

       o   Prefetch uses the "cache" to	populate the prefetched	relationships.
	   This	may or may not be what you want.

       o   If you specify a condition on a prefetched relationship, ONLY those
	   rows	that match the prefetched condition will be fetched into that
	   relationship.  This means that adding prefetch to a search()	may
	   alter what is returned by traversing	a relationship.	So, if you
	   have	"Artist->has_many(CDs)"	and you	do

	     my	$artist_rs = $schema->resultset('Artist')->search({
		 'cds.year' => 2008,
	     },	{
		 join => 'cds',
	     });

	     my	$count = $artist_rs->first->cds->count;

	     my	$artist_rs_prefetch = $artist_rs->search( {}, {	prefetch => 'cds' } );

	     my	$prefetch_count	= $artist_rs_prefetch->first->cds->count;

	     cmp_ok( $count, '==', $prefetch_count, "Counts should be the same"	);

	   That	cmp_ok() may or	may not	pass depending on the datasets
	   involved. In	other words the	"WHERE"	condition would	apply to the
	   entire dataset, just	like it	would in regular SQL. If you want to
	   add a condition only	to the "right side" of a "LEFT JOIN" -
	   consider declaring and using	a relationship with a custom condition

DBIC BIND VALUES
       Because DBIC 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 "[ \%args =>	$val ]".  The format of	"\%args" is currently:

       dbd_attrs
	   If present (in any form), this is what is being passed directly to
	   bind_param.	Note that different DBD's expect different bind	args.
	   (e.g. DBD::SQLite takes a single numerical type, while DBD::Pg
	   takes a hashref if bind options.)

	   If this is specified, all other bind	options	described below	are
	   ignored.

       sqlt_datatype
	   If present, this is used to infer the actual	bind attribute by
	   passing to "$resolved_storage->bind_attribute_by_data_type()".
	   Defaults to the "data_type" from the	add_columns column info.

	   Note	that the data type is somewhat freeform	(hence the sqlt_
	   prefix); currently drivers are expected to "Do the Right Thing"
	   when	given a	common datatype	name.  (Not ideal, but that's what we
	   got at this point.)

       sqlt_size
	   Currently used to correctly allocate	buffers	for
	   bind_param_inout().	Defaults to "size" from	the add_columns	column
	   info, or to a sensible value	based on the "data_type".

       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).

       For backwards compatibility and convenience, the	following shortcuts
       are supported:

	 [ $name => $val ] === [ { dbic_colname	=> $name }, $val ]
	 [ \$dt	 => $val ] === [ { sqlt_datatype => $dt	}, $val	]
	 [ undef,   $val ] === [ {}, $val ]
	 $val		   === [ {}, $val ]

FURTHER	QUESTIONS?
       Check the list of additional DBIC resources.

COPYRIGHT AND LICENSE
       This module is free software copyright by the DBIx::Class (DBIC)
       authors.	You can	redistribute it	and/or modify it under the same	terms
       as the DBIx::Class library.

perl v5.24.1			  2016-06-20	     DBIx::Class::ResultSet(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | METHODS | ATTRIBUTES | PREFETCHING | DBIC BIND VALUES | FURTHER QUESTIONS? | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::ResultSet&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help