What is differences between ResultSet and an object?

Question

From DBIx::Class::ResultSet we read that:

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' });

Could someone explain what is differences between object and ResultSet?

Answer 1

The warning is about the difference between calling new on a ResultSet object and the ResultSet class name. If you want to create a new ResultSet object using the ResultSet constructor, call new on the ResultSet package:

my $resultset = DBIx::Class::ResultSet->new(...);

(Although you typically don't have to create ResultSet objects this way.) If you call new on a ResultSet object, you won't get a new ResultSet object but a corresponding result (row) object:

my $row = $resultset->new(...);

Many other Perl classes make no difference whether new is called on the class name or an object of the class, hence the warning.

Answer 2

Taken from the DBIx::Class::ResultSet docs:

DBIx::Class::ResultSet - Represents a query used for fetching a set of results. A ResultSet is an object which stores a set of conditions representing a query.

A ResultSet is a specific object which represent a query. An object (not a ResultSet Object) is a single entity from the tables defined in the DBIx.

Lets say you have a DB of fathers and sons, one to many (each father can have many sons). So a single father in the DBIx context is an object, and so does a son. But the query "which father has a son named James" is a ResultSet Object.