view release on metacpan or  search on metacpan

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

L</all> (the raw rows fetched through the backend's C<select_async> are run
through the same C<_construct_results> path).

Requires an async connection (C<< connect(..., { async => ... }) >>); on a sync
instance it croaks. In the C<immediate> mode it runs synchronously and resolves
immediately. See ADR 0030/0031.

=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). The backend path fetches and collapses the full
result set (the only collapse-correct way to obtain the first object under a
prefetch) and resolves with its first element.

=head2 single_async

  my $future = $rs->single_async;

Async variant of L</single>. Routes the single-row fetch through the backend's
C<select_single_async> and inflates the row with the same single-row collapse
assertion as L</single>.

=head2 count_async

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

Async variant of L</count>. Routes the count query through the backend's
C<select_single_async> and resolves with the integer count (applying the same
software-side C<rows>/C<offset> adjustment as L</count>).

=head2 create_async

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

Async variant of L</create>. For a plain single-row create the row's own insert
is routed through the backend's C<insert_async> and the resulting result object
is built in the Future's C<then> (reusing the same column store-back as the
synchronous L<DBIO::Row/insert>). A create that involves related-object
multi-create cannot be expressed as a single C<insert_async> and is run
synchronously, resolving immediately (delegated to L<DBIO::Row/insert_async>).

=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: