NAME

DBIO::ResultSetColumn - Convenience wrapper for working with a single ResultSet column

VERSION

version 0.900004

SYNOPSIS

$rs = $schema->resultset('CD')->search({ artist => 'Tool' });
$rs_column = $rs->get_column('year');
$max_year = $rs_column->max; #returns latest year

See t/resultset/get_column_max.t for a runnable example of the scalar aggregate return shown above (and t/resultset/as_query.t for the ->as_query/*_rs resultset builders).

DESCRIPTION

DBIO::ResultSetColumn is the helper object returned by "get_column" in DBIO::ResultSet. It lets you run column-oriented operations such as aggregates or value iteration without fetching full row objects.

METHODS

new

my $obj = DBIO::ResultSetColumn->new($rs, $column);

Creates a new resultset column object from the resultset and column passed as params. Used internally by "get_column" in DBIO::ResultSet.

new

all

reset

first

single

single_async

all_async

min

min_async

max

max_async

sum

sum_async

func

func_rs

func_async

with_context

$rs->get_column($col)->with_context($ctx)->all_async;

Returns a clone of this column resultset bound to a pinned async context -- the object handed to a "txn_do_async" in DBIO::Storage::Async or pipeline coderef. Once bound, every *_async method on the clone routes onto the context's pinned connection instead of the pool. See "with_context" in DBIO::ResultSet for the full picture; a column resultset inherits this binding automatically when produced by get_column or count_rs on a context-bound resultset.

The resultsets a bound column hands out -- "func_rs", "min_rs", "max_rs" and "sum_rs" -- are bound too, however the column came by its binding. The column with_context is called on is left as it was.

In the immediate mode the context txn_do_async hands its coderef is the storage itself, and with_context takes it; see "with_context" in DBIO::ResultSet for what is particular to that mode.

throw_exception

_resultset

ASYNC

"single_async", "all_async", "min_async", "max_async", "sum_async" and "func_async" mirror their synchronous counterparts, requiring an async connection (connect(..., { async => ... }), see "ASYNC" in DBIO::ResultSet for the full three-way live-backend/immediate/croak contract shared by every DBIO *_async method). single_async/all_async route through the same backend calls "single_async" in DBIO::ResultSet/"all_async" in DBIO::ResultSet use, one tier down; min_async/max_async/sum_async/func_async route the aggregate through func_rs and the backend's select_single_async, bypassing the cursor. One asymmetry worth knowing: if func_rs ends up selecting more than one row (e.g. a func_async call over a resultset with a group_by, so the "aggregate" is really one value per group), select_single_async carps "Query returned more than one row... DEPRECATED for ->find and ->single" -- naming the wrong methods, since it's a shared warning from the storage layer, not written for min_async/max_async/sum_async/func_async. The synchronous func() has no such warning in this situation: it reads exactly one row off the cursor (($cursor->next)[0]) and silently ignores the rest.

"next", "first" and "reset" have no async twin: they iterate a cursor, and there is no async cursor iteration yet -- the same gap ADR 0031 already documents for "first_async" in DBIO::ResultSet's own over-fetch. This gap does not limit func_async, though: func always returns a single scalar ("func"), never a per-row list, so its async twin covers it completely.

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.

Arguments: none
Return Value: $value

Returns the next value of the column in the resultset (or undef if there is none).

Much like "next" in DBIO::ResultSet but just returning the one value.

all

Arguments: none
Return Value: @values

Returns all values of the column in the resultset (an empty list if there are none).

Much like "all" in DBIO::ResultSet but returns values rather than result objects.

reset

Arguments: none
Return Value: $self

Resets the underlying resultset's cursor, so you can iterate through the elements of the column again.

Much like "reset" in DBIO::ResultSet.

first

Arguments: none
Return Value: $value

Resets the underlying resultset and returns the next value of the column in the resultset (or undef if there is none).

Much like "first" in DBIO::ResultSet but just returning the one value.

single

Arguments: none
Return Value: $value

Much like "single" in DBIO::ResultSet fetches one and only one column value using the cursor directly. If additional rows are present a warning is issued before discarding the cursor.

single_async

my $future = $rs_column->single_async;

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

all_async

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

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

min

Arguments: none
Return Value: $lowest_value

my $first_year = $year_col->min();

Wrapper for ->func. Returns the lowest value of the column in the resultset (or undef if there are none).

min_rs

Arguments: none
Return Value: $resultset

my $rs = $year_col->min_rs();

Wrapper for ->func_rs for function MIN().

min_async

my $future = $year_col->min_async;

Async variant of "min". Routes the aggregate through func_rs('MIN') and the backend's select_single_async (the same shape "single_async" uses), rather than through a cursor. Requires an async connection; on a sync instance it croaks. In the immediate mode it runs synchronously and resolves immediately. See ADR 0030/0031.

max

Arguments: none
Return Value: $highest_value

my $last_year = $year_col->max();

Wrapper for ->func. Returns the highest value of the column in the resultset (or undef if there are none).

max_rs

Arguments: none
Return Value: $resultset

my $rs = $year_col->max_rs();

Wrapper for ->func_rs for function MAX().

max_async

my $future = $year_col->max_async;

Async variant of "max". Routes the aggregate through func_rs('MAX') and the backend's select_single_async (the same shape "single_async" uses), rather than through a cursor. Requires an async connection; on a sync instance it croaks. In the immediate mode it runs synchronously and resolves immediately. See ADR 0030/0031.

sum

Arguments: none
Return Value: $sum_of_values

my $total = $prices_col->sum();

Wrapper for ->func. Returns the sum of all the values in the column of the resultset. Use on varchar-like columns at your own risk.

sum_rs

Arguments: none
Return Value: $resultset

my $rs = $year_col->sum_rs();

Wrapper for ->func_rs for function SUM().

sum_async

my $future = $prices_col->sum_async;

Async variant of "sum". Routes the aggregate through func_rs('SUM') and the backend's select_single_async (the same shape "single_async" uses), rather than through a cursor. Requires an async connection; on a sync instance it croaks. In the immediate mode it runs synchronously and resolves immediately. See ADR 0030/0031.

func

Arguments: $function
Return Value: $function_return_value

$rs = $schema->resultset("CD")->search({});
$length = $rs->get_column('title')->func('LENGTH');

Runs a query using the function on the column and returns the value. Produces the following SQL:

SELECT LENGTH( title ) FROM cd me

The function name is an identifier, optionally schema-qualified (LENGTH, pg_catalog.max); any other name throws. Write an expression as a literal in select (\'...' or \[ ... ]).

func_rs

Arguments: $function
Return Value: $resultset

Creates the resultset that func() uses to run its query. The function name is an identifier as described at "func". A binding made with "with_context" goes with it.

func_async

my $future = $rs_column->func_async('LENGTH');

Async variant of "func". Routes the aggregate through func_rs($function) and the backend's select_single_async, exactly like "min_async", "max_async" and "sum_async". Like "func" it returns the single scalar value the aggregate produces; there is no per-row list variant to mirror.

Requires an async connection; on a sync instance it croaks. In the immediate mode it runs synchronously and resolves immediately. See ADR 0030/0031.

throw_exception

See "throw_exception" in DBIO::Schema for details.

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install DBIO, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBIO

CPAN shell

perl -MCPAN -e shell
install DBIO

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new

new

next

all

reset

first

single

single_async

all_async

min

min_async

max

max_async

sum

sum_async

func

func_rs

func_async

with_context

throw_exception

_resultset

ASYNC

as_query

next

all

reset

first

single

single_async

all_async

min

min_rs

min_async

max

max_rs

max_async

sum

sum_rs

sum_async

func

func_rs

func_async

throw_exception

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

Keyboard Shortcuts