X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FResultSet.pm;h=204b75f1e8cc508e0ef67a942dbdd80f3e61e548;hb=6b9268d27194824fd4199f91bedaac46e3f96afb;hp=2a198f48f8cc6ea8f73955234acb9981d1080a88;hpb=d4a9feb61f70c254ed31df7e865fc609aede66c1;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index 2a198f4..204b75f 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -34,12 +34,12 @@ DBIx::Class::ResultSet - Represents a query used for fetching a set of results. =head1 SYNOPSIS - my $users_rs = $schema->resultset('User'); + 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 $registered_users_rs = $schema->resultset('User')->search({ registered => 1 }); my @cds_in_2005 = $schema->resultset('CD')->search({ year => 2005 })->all(); =head1 DESCRIPTION @@ -191,9 +191,9 @@ See: L, L, L, L, L. =over 4 -=item Arguments: $source, \%$attrs +=item Arguments: L<$source|DBIx::Class::ResultSource>, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $rs +=item Return Value: L<$resultset|/search> =back @@ -202,8 +202,11 @@ L) and an attribute hash (see L below). Does not perform any queries -- these are executed as needed by the other methods. -Generally you won't need to construct a resultset manually. You'll -automatically get one from e.g. a L called in scalar context: +Generally you never construct a resultset manually. Instead you get one +from e.g. a +C<< $schema->L('$source_name') >> +or C<< $another_resultset->L(...) >> (the later called in +scalar context): my $rs = $schema->resultset('CD')->search({ title => '100th Window' }); @@ -219,7 +222,7 @@ 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 C directly, +Please also keep in mind that many internals call L directly, so overloading this method with the idea of intercepting new result object creation B. See also warning pertaining to L. @@ -266,9 +269,9 @@ sub new { =over 4 -=item Arguments: $cond, \%attrs? +=item Arguments: L<$cond|DBIx::Class::SQLMaker> | undef, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $resultset (scalar context) || @row_objs (list context) +=item Return Value: $resultset (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context) =back @@ -279,7 +282,8 @@ sub new { # year = 2005 OR year = 2004 In list context, C<< ->all() >> is called implicitly on the resultset, thus -returning a list of row objects instead. To avoid that, use L. +returning a list of L objects instead. +To avoid that, use L. If you need to pass in additional attributes but no additional condition, call it as C. @@ -301,7 +305,7 @@ For more help on using joins with search, see L. Note that L does not process/deflate any of the values passed in the L-compatible search condition structure. This is unlike other -condition-bound methods L, L and L. The user must ensure +condition-bound methods L, L and L. 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 objects, for more info see: @@ -336,9 +340,9 @@ sub search { =over 4 -=item Arguments: $cond, \%attrs? +=item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $resultset +=item Return Value: L<$resultset|/search> =back @@ -350,20 +354,36 @@ always return a resultset, even in list context. sub search_rs { my $self = shift; - # Special-case handling for (undef, undef). - if ( @_ == 2 && !defined $_[1] && !defined $_[0] ) { - @_ = (); - } + my $rsrc = $self->result_source; + my ($call_cond, $call_attrs); - my $call_attrs = {}; - if (@_ > 1) { - if (ref $_[-1] eq 'HASH') { - # copy for _normalize_selection - $call_attrs = { %{ pop @_ } }; - } - elsif (! defined $_[-1] ) { - pop @_; # search({}, undef) + # Special-case handling for (undef, undef) or (undef) + # Note that (foo => undef) is valid deprecated syntax + @_ = () if not scalar grep { defined $_ } @_; + + # just a cond + if (@_ == 1) { + $call_cond = shift; + } + # fish out attrs in the ($condref, $attr) case + elsif (@_ == 2 and ( ! defined $_[0] or (ref $_[0]) ne '') ) { + ($call_cond, $call_attrs) = @_; + } + elsif (@_ % 2) { + $self->throw_exception('Odd number of arguments to search') + } + # legacy search + elsif (@_) { + carp_unique 'search( %condition ) is deprecated, use search( \%condition ) instead' + unless $rsrc->result_class->isa('DBIx::Class::CDBICompat'); + + for my $i (0 .. $#_) { + next if $i % 2; + $self->throw_exception ('All keys in condition key/value pairs must be plain scalars') + if (! defined $_[$i] or ref $_[$i] ne ''); } + + $call_cond = { @_ }; } # see if we can keep the cache (no $rs changes) @@ -379,8 +399,6 @@ sub search_rs { $cache = $self->get_cache; } - my $rsrc = $self->result_source; - my $old_attrs = { %{$self->{attrs}} }; my $old_having = delete $old_attrs->{having}; my $old_where = delete $old_attrs->{where}; @@ -388,7 +406,10 @@ sub search_rs { my $new_attrs = { %$old_attrs }; # take care of call attrs (only if anything is changing) - if (keys %$call_attrs) { + if ($call_attrs and keys %$call_attrs) { + + # copy for _normalize_selection + $call_attrs = { %$call_attrs }; my @selector_attrs = qw/select as columns cols +select +as +columns include_columns/; @@ -435,28 +456,6 @@ sub search_rs { } - # rip apart the rest of @_, parse a condition - my $call_cond = do { - - if (ref $_[0] eq 'HASH') { - (keys %{$_[0]}) ? $_[0] : undef - } - elsif (@_ == 1) { - $_[0] - } - elsif (@_ % 2) { - $self->throw_exception('Odd number of arguments to search') - } - else { - +{ @_ } - } - - } if @_; - - if( @_ > 1 and ! $rsrc->result_class->isa('DBIx::Class::CDBICompat') ) { - carp_unique 'search( %condition ) is deprecated, use search( \%condition ) instead'; - } - for ($old_where, $call_cond) { if (defined $_) { $new_attrs->{where} = $self->_stack_cond ( @@ -642,7 +641,7 @@ require C. =item Arguments: $sql_fragment, @standalone_bind_values -=item Return Value: $resultset (scalar context) || @row_objs (list context) +=item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context) =back @@ -672,9 +671,9 @@ sub search_literal { =over 4 -=item Arguments: \%columns_values | @pk_values, \%attrs? +=item Arguments: \%columns_values | @pk_values, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }? -=item Return Value: $row_object | undef +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef =back @@ -706,7 +705,7 @@ Note that this fallback behavior may be deprecated in further versions. If you need to search with arbitrary conditions - use L. 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 -C<$row_object>. +C<$result_object>. In addition to C, L recognizes and applies standard L in the same way as L does. @@ -920,7 +919,7 @@ sub _build_unique_cond { and !$ENV{DBIC_NULLABLE_KEY_NOWARN} and - my @undefs = grep { ! defined $final_cond->{$_} } (keys %$final_cond) + my @undefs = sort grep { ! defined $final_cond->{$_} } (keys %$final_cond) ) { carp_unique ( sprintf ( "NULL/undef values supplied for requested unique constraint '%s' (NULL " @@ -938,9 +937,9 @@ sub _build_unique_cond { =over 4 -=item Arguments: $rel, $cond?, \%attrs? +=item Arguments: $rel_name, $cond?, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $new_resultset (scalar context) || @row_objs (list context) +=item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context) =back @@ -952,7 +951,7 @@ Searches the specified relationship, optionally specifying a condition and attributes for matching records. See L for more information. In list context, C<< ->all() >> is called implicitly on the resultset, thus -returning a list of row objects instead. To avoid that, use L. +returning a list of result objects instead. To avoid that, use L. See also L. @@ -979,7 +978,7 @@ sub search_related_rs { =item Arguments: none -=item Return Value: $cursor +=item Return Value: L<$cursor|DBIx::Class::Cursor> =back @@ -989,22 +988,23 @@ L for more information. =cut sub cursor { - my ($self) = @_; - - my $attrs = $self->_resolved_attrs_copy; + my $self = shift; - return $self->{cursor} - ||= $self->result_source->storage->select($attrs->{from}, $attrs->{select}, - $attrs->{where},$attrs); + return $self->{cursor} ||= do { + my $attrs = { %{$self->_resolved_attrs } }; + $self->result_source->storage->select( + $attrs->{from}, $attrs->{select}, $attrs->{where}, $attrs + ); + }; } =head2 single =over 4 -=item Arguments: $cond? +=item Arguments: L<$cond?|DBIx::Class::SQLMaker> -=item Return Value: $row_object | undef +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef =back @@ -1047,7 +1047,7 @@ sub single { $self->throw_exception('single() only takes search conditions, no attributes. You want ->search( $cond, $attrs )->single()'); } - my $attrs = $self->_resolved_attrs_copy; + my $attrs = { %{$self->_resolved_attrs} }; if (keys %{$attrs->{collapse}}) { $self->throw_exception( @@ -1112,9 +1112,9 @@ sub _collapse_query { =over 4 -=item Arguments: $cond? +=item Arguments: L<$cond?|DBIx::Class::SQLMaker> -=item Return Value: $resultsetcolumn +=item Return Value: L<$resultsetcolumn|DBIx::Class::ResultSetColumn> =back @@ -1134,9 +1134,9 @@ sub get_column { =over 4 -=item Arguments: $cond, \%attrs? +=item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $resultset (scalar context) || @row_objs (list context) +=item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context) =back @@ -1179,7 +1179,7 @@ sub search_like { =item Arguments: $first, $last -=item Return Value: $resultset (scalar context) || @row_objs (list context) +=item Return Value: L<$resultset|/search> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context) =back @@ -1208,7 +1208,7 @@ sub slice { =item Arguments: none -=item Return Value: $result | undef +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef =back @@ -1390,9 +1390,9 @@ sub _collapse_result { =over 4 -=item Arguments: $result_source? +=item Arguments: L<$result_source?|DBIx::Class::ResultSource> -=item Return Value: $result_source +=item Return Value: L<$result_source|DBIx::Class::ResultSource> =back @@ -1409,7 +1409,7 @@ is derived. =back -An accessor for the class to use when creating row objects. Defaults to +An accessor for the class to use when creating result objects. Defaults to C<< result_source->result_class >> - which in most cases is the name of the L<"table"|DBIx::Class::Manual::Glossary/"ResultSource"> class. @@ -1439,7 +1439,7 @@ sub result_class { =over 4 -=item Arguments: $cond, \%attrs?? +=item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES> =item Return Value: $count @@ -1456,7 +1456,7 @@ sub count { return $self->search(@_)->count if @_ and defined $_[0]; return scalar @{ $self->get_cache } if $self->get_cache; - my $attrs = $self->_resolved_attrs_copy; + my $attrs = { %{ $self->_resolved_attrs } }; # this is a little optimization - it is faster to do the limit # adjustments in software, instead of a subquery @@ -1483,9 +1483,9 @@ sub count { =over 4 -=item Arguments: $cond, \%attrs?? +=item Arguments: L<$cond|DBIx::Class::SQLMaker>, L<\%attrs?|/ATTRIBUTES> -=item Return Value: $count_rs +=item Return Value: L<$count_rs|DBIx::Class::ResultSetColumn> =back @@ -1663,7 +1663,7 @@ sub count_literal { shift->search_literal(@_)->count; } =item Arguments: none -=item Return Value: @objects +=item Return Value: L<@result_objs|DBIx::Class::Manual::ResultClass> =back @@ -1721,7 +1721,6 @@ another query. sub reset { my ($self) = @_; - delete $self->{_attrs} if exists $self->{_attrs}; $self->{all_cache_position} = 0; $self->cursor->reset; return $self; @@ -1733,12 +1732,12 @@ sub reset { =item Arguments: none -=item Return Value: $object | undef +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef =back -Resets the resultset and returns an object for the first result (or C -if the resultset is empty). +L the resultset (causing a fresh query to storage) and returns +an object for the first result (or C if the resultset is empty). =cut @@ -1756,152 +1755,146 @@ sub first { sub _rs_update_delete { my ($self, $op, $values) = @_; - my $cond = $self->{cond}; my $rsrc = $self->result_source; my $storage = $rsrc->schema->storage; my $attrs = { %{$self->_resolved_attrs} }; + my $join_classifications; my $existing_group_by = delete $attrs->{group_by}; - my $needs_subq = defined $existing_group_by; - # simplify the joinmap and maybe decide if a subquery is necessary - my $relation_classifications = {}; + # do we need a subquery for any reason? + my $needs_subq = ( + defined $existing_group_by + or + # if {from} is unparseable wrap a subq + ref($attrs->{from}) ne 'ARRAY' + or + # limits call for a subq + $self->_has_resolved_attr(qw/rows offset/) + ); - if (ref($attrs->{from}) eq 'ARRAY') { - # if we already know we need a subq, no point of classifying relations - if (!$needs_subq and @{$attrs->{from}} > 1) { - $attrs->{from} = $storage->_prune_unused_joins ($attrs->{from}, $attrs->{select}, $cond, $attrs); + # simplify the joinmap, so we can further decide if a subq is necessary + if (!$needs_subq and @{$attrs->{from}} > 1) { + $attrs->{from} = $storage->_prune_unused_joins ($attrs->{from}, $attrs->{select}, $self->{cond}, $attrs); - $relation_classifications = $storage->_resolve_aliastypes_from_select_args ( + # check if there are any joins left after the prune + if ( @{$attrs->{from}} > 1 ) { + $join_classifications = $storage->_resolve_aliastypes_from_select_args ( [ @{$attrs->{from}}[1 .. $#{$attrs->{from}}] ], $attrs->{select}, - $cond, + $self->{cond}, $attrs ); + + # any non-pruneable joins imply subq + $needs_subq = scalar keys %{ $join_classifications->{restricting} || {} }; } } - else { - $needs_subq ||= 1; # if {from} is unparseable assume the worst - } + # check if the head is composite (by now all joins are thrown out unless $needs_subq) + $needs_subq ||= ( + (ref $attrs->{from}[0]) ne 'HASH' + or + ref $attrs->{from}[0]{ $attrs->{from}[0]{-alias} } + ); + + my ($cond, $guard); # do we need anything like a subquery? - if ( - ! $needs_subq - and - ! keys %{ $relation_classifications->{restricting} || {} } - and - ! $self->_has_resolved_attr(qw/rows offset/) # limits call for a subq - ) { + if (! $needs_subq) { # Most databases do not allow aliasing of tables in UPDATE/DELETE. Thus # a condition containing 'me' or other table prefixes will not work # at all. Tell SQLMaker to dequalify idents via a gross hack. - my $cond = do { + $cond = do { my $sqla = $rsrc->storage->sql_maker; local $sqla->{_dequalify_idents} = 1; \[ $sqla->_recurse_where($self->{cond}) ]; }; - return $rsrc->storage->$op( - $rsrc, - $op eq 'update' ? $values : (), - $cond, - ); - } - - # we got this far - means it is time to wrap a subquery - my $idcols = $rsrc->_identifying_column_set || $self->throw_exception( - sprintf( - "Unable to perform complex resultset %s() without an identifying set of columns on source '%s'", - $op, - $rsrc->source_name, - ) - ); - - # make a new $rs selecting only the PKs (that's all we really need for the subq) - delete $attrs->{$_} for qw/collapse _collapse_order_by select _prefetch_selector_range as/; - $attrs->{columns} = [ map { "$attrs->{alias}.$_" } @$idcols ]; - $attrs->{group_by} = \ ''; # FIXME - this is an evil hack, it causes the optimiser to kick in and throw away the LEFT joins - my $subrs = (ref $self)->new($rsrc, $attrs); - - if (@$idcols == 1) { - return $storage->$op ( - $rsrc, - $op eq 'update' ? $values : (), - { $idcols->[0] => { -in => $subrs->as_query } }, - ); } - elsif ($storage->_use_multicolumn_in) { - # This is hideously ugly, but SQLA does not understand multicol IN expressions - my $sql_maker = $storage->sql_maker; - my ($sql, @bind) = @${$subrs->as_query}; - $sql = sprintf ('(%s) IN %s', # the as_query already comes with a set of parenthesis - join (', ', map { $sql_maker->_quote ($_) } @$idcols), - $sql, + else { + # we got this far - means it is time to wrap a subquery + my $idcols = $rsrc->_identifying_column_set || $self->throw_exception( + sprintf( + "Unable to perform complex resultset %s() without an identifying set of columns on source '%s'", + $op, + $rsrc->source_name, + ) ); - return $storage->$op ( - $rsrc, - $op eq 'update' ? $values : (), - \[$sql, @bind], - ); - } - else { + # make a new $rs selecting only the PKs (that's all we really need for the subq) + delete $attrs->{$_} for qw/collapse _collapse_order_by select _prefetch_selector_range as/; + $attrs->{columns} = [ map { "$attrs->{alias}.$_" } @$idcols ]; + $attrs->{group_by} = \ ''; # FIXME - this is an evil hack, it causes the optimiser to kick in and throw away the LEFT joins + my $subrs = (ref $self)->new($rsrc, $attrs); - # if all else fails - get all primary keys and operate over a ORed set - # wrap in a transaction for consistency - # this is where the group_by starts to matter - if ( - $existing_group_by - or - keys %{ $relation_classifications->{multiplying} || {} } - ) { - # make sure if there is a supplied group_by it matches the columns compiled above - # perfectly. Anything else can not be sanely executed on most databases so croak - # right then and there - if ($existing_group_by) { - my @current_group_by = map - { $_ =~ /\./ ? $_ : "$attrs->{alias}.$_" } - @$existing_group_by - ; - - if ( - join ("\x00", sort @current_group_by) - ne - join ("\x00", sort @{$attrs->{columns}} ) - ) { - $self->throw_exception ( - "You have just attempted a $op operation on a resultset which does group_by" - . ' on columns other than the primary keys, while DBIC internally needs to retrieve' - . ' the primary keys in a subselect. All sane RDBMS engines do not support this' - . ' kind of queries. Please retry the operation with a modified group_by or' - . ' without using one at all.' - ); + if (@$idcols == 1) { + $cond = { $idcols->[0] => { -in => $subrs->as_query } }; + } + elsif ($storage->_use_multicolumn_in) { + # no syntax for calling this properly yet + # !!! EXPERIMENTAL API !!! WILL CHANGE !!! + $cond = $storage->sql_maker->_where_op_multicolumn_in ( + $idcols, # how do I convey a list of idents...? can binds reside on lhs? + $subrs->as_query + ), + } + else { + # if all else fails - get all primary keys and operate over a ORed set + # wrap in a transaction for consistency + # this is where the group_by/multiplication starts to matter + if ( + $existing_group_by + or + keys %{ $join_classifications->{multiplying} || {} } + ) { + # make sure if there is a supplied group_by it matches the columns compiled above + # perfectly. Anything else can not be sanely executed on most databases so croak + # right then and there + if ($existing_group_by) { + my @current_group_by = map + { $_ =~ /\./ ? $_ : "$attrs->{alias}.$_" } + @$existing_group_by + ; + + if ( + join ("\x00", sort @current_group_by) + ne + join ("\x00", sort @{$attrs->{columns}} ) + ) { + $self->throw_exception ( + "You have just attempted a $op operation on a resultset which does group_by" + . ' on columns other than the primary keys, while DBIC internally needs to retrieve' + . ' the primary keys in a subselect. All sane RDBMS engines do not support this' + . ' kind of queries. Please retry the operation with a modified group_by or' + . ' without using one at all.' + ); + } } - } - $subrs = $subrs->search({}, { group_by => $attrs->{columns} }); - } + $subrs = $subrs->search({}, { group_by => $attrs->{columns} }); + } - my $guard = $storage->txn_scope_guard; + $guard = $storage->txn_scope_guard; - my @op_condition; - for my $row ($subrs->cursor->all) { - push @op_condition, { map - { $idcols->[$_] => $row->[$_] } - (0 .. $#$idcols) - }; + $cond = []; + for my $row ($subrs->cursor->all) { + push @$cond, { map + { $idcols->[$_] => $row->[$_] } + (0 .. $#$idcols) + }; + } } + } - my $res = $storage->$op ( - $rsrc, - $op eq 'update' ? $values : (), - \@op_condition, - ); + my $res = $storage->$op ( + $rsrc, + $op eq 'update' ? $values : (), + $cond, + ); - $guard->commit; + $guard->commit if $guard; - return $res; - } + return $res; } =head2 update @@ -1910,13 +1903,13 @@ sub _rs_update_delete { =item Arguments: \%values -=item Return Value: $storage_rv +=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 row object instances derived from this +triggers, nor will it update any result object instances derived from this resultset (this includes the contents of the L if any). See L if you need to execute any on-update triggers or cascades defined either by you or a @@ -1978,13 +1971,13 @@ sub update_all { =item Arguments: none -=item Return Value: $storage_rv +=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 status of any row object instances +L status of any result object instances derived from this resultset (this includes the contents of the L if any). See L if you need to execute any on-delete triggers or cascades defined either by you or a @@ -2034,28 +2027,55 @@ sub delete_all { =over 4 -=item Arguments: \@data; +=item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ] + +=item Return Value: L<\@result_objects|DBIx::Class::Manual::ResultClass> (scalar context) | L<@result_objects|DBIx::Class::Manual::ResultClass> (list context) =back -Accepts either an arrayref of hashrefs or alternatively an arrayref of arrayrefs. -For the arrayref of hashrefs style each hashref should be a structure suitable -for submitting to a $resultset->create(...) method. +Accepts either an arrayref of hashrefs or alternatively an arrayref of +arrayrefs. + +=over + +=item NOTE -In void context, C in L is used -to insert the data, as this is a faster method. +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), bypassing the L and +L calls on the +L class, including any +augmentation of these methods provided by components. For example if you +are using something like L 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. -Otherwise, each set of data is inserted into the database using -L, and the resulting objects are -accumulated into an array. The array itself, or an array reference -is returned depending on scalar or list context. +=back -Example: Assuming an Artist Class that has many CDs Classes relating: +In non-void (scalar or list) context, this method is simply a wrapper +for L. Depending on list or scalar context either a list of +L objects or an arrayref +containing these objects is returned. - my $Artist_rs = $schema->resultset("Artist"); +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: - ## Void Context Example - $Artist_rs->populate([ + $Arstist_rs->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 L. 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 }, @@ -2069,37 +2089,11 @@ Example: Assuming an Artist Class that has many CDs Classes relating: }, ]); - ## Array Context Example - my ($ArtistOne, $ArtistTwo, $ArtistThree) = $Artist_rs->populate([ - { name => "Artist One"}, - { name => "Artist Two"}, - { name => "Artist Three", cds=> [ - { title => "First CD", year => 2007}, - { title => "Second CD", year => 2008}, - ]} - ]); - - print $ArtistOne->name; ## response is 'Artist One' - print $ArtistThree->cds->count ## reponse is '2' - -For the arrayref of arrayrefs style, the first element should be a list of the -fieldsnames to which the remaining elements are rows being inserted. For -example: - - $Arstist_rs->populate([ - [qw/artistid name/], - [100, 'A Formally Unknown Singer'], - [101, 'A singer that jumped the shark two albums ago'], - [102, 'An actually cool singer'], - ]); - -Please note an important effect on your data when choosing between void and -wantarray context. Since void context goes straight to C in -L this will skip any component that is overriding -C. So if you are using something like L to -create primary keys for you, you will find that your PKs are empty. In this -case you will have to use the wantarray context in order to create those -values. +If you attempt a void-context multi-create as in the example above (each +Artist also has the related list of CDs), and B supply the +necessary autoinc foreign key information, this method will proxy to the +less efficient L, and then throw the Result objects away. In this +case there are obviously no benefits to using this method over L. =cut @@ -2112,10 +2106,7 @@ sub populate { return unless @$data; if(defined wantarray) { - my @created; - foreach my $item (@$data) { - push(@created, $self->create($item)); - } + my @created = map { $self->create($_) } @$data; return wantarray ? @created : \@created; } else { @@ -2170,14 +2161,12 @@ sub populate { ## inherit the data locked in the conditions of the resultset my ($rs_data) = $self->_merge_with_rscond({}); delete @{$rs_data}{@columns}; - my @inherit_cols = keys %$rs_data; - my @inherit_data = values %$rs_data; ## do bulk insert on current row $rsrc->storage->insert_bulk( $rsrc, - [@columns, @inherit_cols], - [ map { [ @$_{@columns}, @inherit_data ] } @$data ], + [@columns, keys %$rs_data], + [ map { [ @$_{@columns}, values %$rs_data ] } @$data ], ); ## do the has_many relationships @@ -2240,11 +2229,11 @@ sub _normalize_populate_args { =item Arguments: none -=item Return Value: $pager +=item Return Value: L<$pager|Data::Page> =back -Return Value a L object for the current resultset. Only makes +Returns a L object for the current resultset. Only makes sense for queries with a C attribute. To get the full count of entries for a paged resultset, call @@ -2287,7 +2276,7 @@ sub pager { =item Arguments: $page_number -=item Return Value: $rs +=item Return Value: L<$resultset|/search> =back @@ -2306,16 +2295,16 @@ sub page { =over 4 -=item Arguments: \%vals +=item Arguments: \%col_data -=item Return Value: $rowobject +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back -Creates a new row object in the resultset's result class and returns +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 L to do that. Calling L -will tell you whether the row object has been inserted or not. +will tell you whether the result object has been inserted or not. Passes the hashref of input on to L. @@ -2513,7 +2502,7 @@ sub _remove_alias { =item Arguments: none -=item Return Value: \[ $sql, @bind ] +=item Return Value: \[ $sql, L<@bind_values|/DBIC BIND VALUES> ] =back @@ -2526,7 +2515,7 @@ This is generally used as the RHS for a subquery. sub as_query { my $self = shift; - my $attrs = $self->_resolved_attrs_copy; + my $attrs = { %{ $self->_resolved_attrs } }; # For future use: # @@ -2544,9 +2533,9 @@ sub as_query { =over 4 -=item Arguments: \%vals, \%attrs? +=item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }? -=item Return Value: $rowobject +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back @@ -2591,9 +2580,9 @@ sub find_or_new { =over 4 -=item Arguments: \%vals +=item Arguments: \%col_data -=item Return Value: a L $object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back @@ -2619,9 +2608,9 @@ 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 -L), will be inserted into their appropriate tables. +L), will be inserted into their appropriate tables. -Effectively a shortcut for C<< ->new_result(\%vals)->insert >>. +Effectively a shortcut for C<< ->new_result(\%col_data)->insert >>. Example of creating a new row. @@ -2659,8 +2648,8 @@ C resultset. Note Hashref. When subclassing ResultSet never attempt to override this method. Since it is a simple shortcut for C<< $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 L -or L depending on how early in the +bypassed more often than not. Override either L +or L depending on how early in the L process you need to intervene. See also warning pertaining to L. @@ -2679,9 +2668,9 @@ sub create { =over 4 -=item Arguments: \%vals, \%attrs? +=item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }? -=item Return Value: $rowobject +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back @@ -2761,16 +2750,16 @@ sub find_or_create { =over 4 -=item Arguments: \%col_values, { key => $unique_constraint }? +=item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }? -=item Return Value: $row_object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back $resultset->update_or_create({ col => $val, ... }); Like L, but if a row is found it is immediately updated via -C<< $found_row->update (\%col_values) >>. +C<< $found_row->update (\%col_data) >>. Takes an optional C attribute to search on a specific unique constraint. @@ -2831,16 +2820,16 @@ sub update_or_create { =over 4 -=item Arguments: \%col_values, { key => $unique_constraint }? +=item Arguments: \%col_data, { key => $unique_constraint, L<%attrs|/ATTRIBUTES> }? -=item Return Value: $rowobject +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back $resultset->update_or_new({ col => $val, ... }); Like L but if a row is found it is immediately updated via -C<< $found_row->update (\%col_values) >>. +C<< $found_row->update (\%col_data) >>. For example: @@ -2896,7 +2885,7 @@ sub update_or_new { =item Arguments: none -=item Return Value: \@cache_objects | undef +=item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass> | undef =back @@ -2915,15 +2904,15 @@ sub get_cache { =over 4 -=item Arguments: \@cache_objects +=item Arguments: L<\@result_objs|DBIx::Class::Manual::ResultClass> -=item Return Value: \@cache_objects +=item Return Value: L<\@result_objs|DBIx::Class::Manual::ResultClass> =back 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 +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 @@ -2994,9 +2983,9 @@ sub is_ordered { =over 4 -=item Arguments: $relationship_name +=item Arguments: $rel_name -=item Return Value: $resultset +=item Return Value: L<$resultset|/search> =back @@ -3108,9 +3097,7 @@ source alias of the current result set: =cut sub current_source_alias { - my ($self) = @_; - - return ($self->{attrs} || {})->{alias} || 'me'; + return (shift->{attrs} || {})->{alias} || 'me'; } =head2 as_subselect_rs @@ -3119,7 +3106,7 @@ sub current_source_alias { =item Arguments: none -=item Return Value: $resultset +=item Return Value: L<$resultset|/search> =back @@ -3292,12 +3279,6 @@ sub _chain_relationship { return {%$attrs, from => $from, seen_join => $seen}; } -# too many times we have to do $attrs = { %{$self->_resolved_attrs} } -sub _resolved_attrs_copy { - my $self = shift; - return { %{$self->_resolved_attrs (@_)} }; -} - sub _resolved_attrs { my $self = shift; return $self->{_attrs} if $self->{_attrs}; @@ -3321,7 +3302,7 @@ sub _resolved_attrs { if (my $cols = delete $attrs->{columns}) { for my $c (ref $cols eq 'ARRAY' ? @$cols : $cols) { if (ref $c eq 'HASH') { - for my $as (keys %$c) { + for my $as (sort keys %$c) { push @sel, $c->{$as}; push @as, $as; } @@ -3750,6 +3731,10 @@ searching for data. They can be passed to any method which takes an C<\%attrs> argument. See L, L, L, L. +Default attributes can be set on the result class using +L. (Please read +the CAVEATS on that feature before using it!) + These are in no particular order: =head2 order_by @@ -4115,12 +4100,6 @@ relationship on a given level. e.g.: } ); -In fact, C will emit the following warning: - - Prefetching multiple has_many rels tracks and cd_to_producer at top - level will explode the number of row objects retrievable via ->next - or ->all. Use at your own risk. - The collapser currently can't identify duplicate tuples for multiple L relationships and as a result the second L @@ -4198,6 +4177,37 @@ behavior may or may not survive the 0.09 transition. =back +=head2 alias + +=over 4 + +=item Value: $source_alias + +=back + +Sets the source alias for the query. Normally, this defaults to C, 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 L. + =head2 page =over 4 @@ -4343,6 +4353,54 @@ 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. +=head1 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 +C<< [ \%args => $val ] >>. The format of C<< \%args >> is currently: + +=over 4 + +=item 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. + +=item sqlt_datatype + +If present, this is used to infer the actual bind attribute by passing to +C<< $resolved_storage->bind_attribute_by_data_type() >>. Defaults to the +"data_type" from the L. + +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.) + +=item sqlt_size + +Currently used to correctly allocate buffers for bind_param_inout(). +Defaults to "size" from the L, +or to a sensible value based on the "data_type". + +=item dbic_colname + +Used to fill in missing sqlt_datatype and sqlt_size attributes (if they are +explicitly specified they are never overriden). Also used by some weird DBDs, +where the column name should be available at bind_param time (e.g. Oracle). + +=back + +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 ] + =head1 AUTHOR AND CONTRIBUTORS See L and L in DBIx::Class