view release on metacpan or  search on metacpan

lib/DBIO/ResultSet.pm  view on Meta::CPAN

=item Arguments: none

=item Return Value: L<$result|DBIO::Manual::ResultClass> | undef

=back

L<Resets|/reset> the resultset (causing a fresh query to storage) and returns
an object for the first result (or C<undef> if the resultset is empty).

=head2 all_async

  my $future = $rs->all_async;
  $future->then(sub { my @rows = @_; ... });

Async variant of L</all>. Returns a L<DBIO::Future> that resolves with
all result objects. With synchronous storage, the Future resolves
immediately.

=head2 first_async

  my $future = $rs->first_async;

Async variant of L</first>. Returns a L<DBIO::Future> that resolves
with the first result object (or undef).

=head2 single_async

  my $future = $rs->single_async;

Async variant of L</single>.

=head2 count_async

  my $future = $rs->count_async;
  $future->then(sub { my $count = shift; ... });

Async variant of L</count>.

=head2 create_async

  my $future = $rs->create_async(\%vals);
  $future->then(sub { my $row = shift; ... });

Async variant of L</create>.

=head2 update

=over 4

=item Arguments: \%values

=item Return Value: $underlying_storage_rv

=back

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 L<resultset cache|/set_cache>
if any). See L</update_all> if you need to execute any on-update
triggers or cascades defined either by you or a
L<result component|DBIO::Manual::Component/WHAT IS A COMPONENT>.

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

=head3 CAVEAT

Note that L</update> does not process/deflate any of the values passed in.
This is unlike the corresponding L<DBIO::Row/update>. 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 L<DateTime> objects, for more info see:
L<DBIO::Manual::Cookbook/Formatting DateTime objects in queries>.

=head2 update_all

=over 4

=item Arguments: \%values

=item Return Value: 1

=back

Fetches all objects and updates them one at a time via
L<DBIO::Row/update>. Note that C<update_all> will run DBIO defined
triggers, while L</update> will not.

=head2 delete

=over 4

=item Arguments: none

=item Return Value: $underlying_storage_rv

=back

Deletes the rows matching this resultset in a single query. Note that this
will not run any delete triggers, nor will it alter the
L<in_storage|DBIO::Row/in_storage> status of any result object instances
derived from this resultset (this includes the contents of the
L<resultset cache|/set_cache> if any). See L</delete_all> if you need to
execute any on-delete triggers or cascades defined either by you or a
L<result component|DBIO::Manual::Component/WHAT IS A COMPONENT>.

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

=head2 delete_all

=over 4

=item Arguments: none

=item Return Value: 1

=back

Fetches all objects and deletes them one at a time via
L<DBIO::Row/delete>. Note that C<delete_all> will run DBIO defined
triggers, while L</delete> will not.

=head2 populate

=over 4

=item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ]

=item Return Value: L<\@result_objects|DBIO::Manual::ResultClass> (scalar context) | L<@result_objects|DBIO::Manual::ResultClass> (list context)

=back

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

=over

=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<DBI/execute_for_fetch>), bypassing the L<new|DBIO::Row/new> and
L<insert|DBIO::Row/insert> calls on the
L<Result|DBIO::Manual::ResultClass> class, including any
augmentation of these methods provided by components. For example if you
are using something like L<DBIO::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.

=back

In non-void (scalar or list) context, this method is simply a wrapper
for L</create>. Depending on list or scalar context either a list of
L<Result|DBIO::Manual::ResultClass> 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: