use strict;
use warnings;
use overload
- '0+' => \&count,
- 'bool' => sub { 1; },
+ '0+' => "count",
+ 'bool' => "_bool",
fallback => 1;
use Carp::Clan qw/^DBIx::Class/;
use Data::Page;
use Storable;
use DBIx::Class::ResultSetColumn;
use DBIx::Class::ResultSourceHandle;
+use List::Util ();
+use Scalar::Util ();
use base qw/DBIx::Class/;
__PACKAGE__->mk_group_accessors('simple' => qw/result_class _source_handle/);
=head1 SYNOPSIS
- my $rs = $schema->resultset('User')->search(registered => 1);
- my @rows = $schema->resultset('CD')->search(year => 2005);
+ my $rs = $schema->resultset('User')->search({ registered => 1 });
+ my @rows = $schema->resultset('CD')->search({ year => 2005 })->all();
=head1 DESCRIPTION
__PACKAGE__->belongs_to(artist => 'MyApp::Schema::Artist');
1;
+=head1 OVERLOADING
+
+If a resultset is used in a numeric context it returns the L</count>.
+However, if it is used in a booleand context it is always true. So if
+you want to check if a resultset has any results use C<if $rs != 0>.
+C<if $rs> will always be true.
+
=head1 METHODS
=head2 new
$attrs->{alias} ||= 'me';
+ # Creation of {} and bless separated to mitigate RH perl bug
+ # see https://bugzilla.redhat.com/show_bug.cgi?id=196836
my $self = {
_source_handle => $source,
result_class => $attrs->{result_class} || $source->resolve->result_class,
L<Searching|DBIx::Class::Manual::Cookbook/Searching>. For a complete
documentation for the first argument, see L<SQL::Abstract>.
+For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
+
=cut
sub search {
sub search_rs {
my $self = shift;
- my $rows;
-
- unless (@_) { # no search, effectively just a clone
- $rows = $self->get_cache;
- }
-
my $attrs = {};
$attrs = pop(@_) if @_ > 1 and ref $_[$#_] eq 'HASH';
my $our_attrs = { %{$self->{attrs}} };
my $having = delete $our_attrs->{having};
my $where = delete $our_attrs->{where};
+ my $rows;
+
+ my %safe = (alias => 1, cache => 1);
+
+ unless (
+ (@_ && defined($_[0])) # @_ == () or (undef)
+ ||
+ (keys %$attrs # empty attrs or only 'safe' attrs
+ && List::Util::first { !$safe{$_} } keys %$attrs)
+ ) {
+ # no search, effectively just a clone
+ $rows = $self->get_cache;
+ }
+
my $new_attrs = { %{$our_attrs}, %{$attrs} };
# merge new attrs into inherited
Pass a literal chunk of SQL to be added to the conditional part of the
resultset query.
+CAVEAT: C<search_literal> is provided for Class::DBI compatibility and should
+only be used in that context. There are known problems using C<search_literal>
+in chained queries; it can result in bind values in the wrong order. See
+L<DBIx::Class::Manual::Cookbook/Searching> and
+L<DBIx::Class::Manual::FAQ/Searching> for searching techniques that do not
+require C<search_literal>.
+
=cut
sub search_literal {
If the C<key> is specified as C<primary>, it searches only on the primary key.
If no C<key> is specified, it searches on all unique constraints defined on the
-source, including the primary key.
+source for which column data is provided, including the primary key.
If your table does not have a primary key, you B<must> provide a value for the
C<key> attribute matching one of the unique constraints on the source.
+Note: If your query does not return only one row, a warning is generated:
+
+ Query returned more than one row
+
See also L</find_or_create> and L</update_or_create>. For information on how to
declare unique constraints, see
L<DBIx::Class::ResultSource/add_unique_constraint>.
@{$input_query}{@keys} = values %related;
}
- my @unique_queries = $self->_unique_queries($input_query, $attrs);
# Build the final query: Default to the disjunction of the unique queries,
# but allow the input query in case the ResultSet defines the query or the
# user is abusing find
my $alias = exists $attrs->{alias} ? $attrs->{alias} : $self->{attrs}{alias};
- my $query = @unique_queries
- ? [ map { $self->_add_alias($_, $alias) } @unique_queries ]
- : $self->_add_alias($input_query, $alias);
+ my $query;
+ if (exists $attrs->{key}) {
+ my @unique_cols = $self->result_source->unique_constraint_columns($attrs->{key});
+ my $unique_query = $self->_build_unique_query($input_query, \@unique_cols);
+ $query = $self->_add_alias($unique_query, $alias);
+ }
+ else {
+ my @unique_queries = $self->_unique_queries($input_query, $attrs);
+ $query = @unique_queries
+ ? [ map { $self->_add_alias($_, $alias) } @unique_queries ]
+ : $self->_add_alias($input_query, $alias);
+ }
# Run the query
if (keys %$attrs) {
my $rs = $self->search($query, $attrs);
- return keys %{$rs->_resolved_attrs->{collapse}} ? $rs->next : $rs->single;
+ if (keys %{$rs->_resolved_attrs->{collapse}}) {
+ my $row = $rs->next;
+ carp "Query returned more than one row" if $rs->next;
+ return $row;
+ }
+ else {
+ return $rs->single;
+ }
}
else {
- return keys %{$self->_resolved_attrs->{collapse}}
- ? $self->search($query)->next
- : $self->single($query);
+ if (keys %{$self->_resolved_attrs->{collapse}}) {
+ my $rs = $self->search($query);
+ my $row = $rs->next;
+ carp "Query returned more than one row" if $rs->next;
+ return $row;
+ }
+ else {
+ return $self->single($query);
+ }
}
}
return shift->related_resultset(shift)->search(@_);
}
+=head2 search_related_rs
+
+This method works exactly the same as search_related, except that
+it guarantees a restultset, even in list context.
+
+=cut
+
+sub search_related_rs {
+ return shift->related_resultset(shift)->search_rs(@_);
+}
+
=head2 cursor
=over 4
Inflates the first result without creating a cursor if the resultset has
any records in it; if not returns nothing. Used by L</find> as an optimisation.
-Can optionally take an additional condition *only* - this is a fast-code-path
-method; if you need to add extra joins or similar call ->search and then
-->single without a condition on the $rs returned from that.
+Can optionally take an additional condition B<only> - this is a fast-code-path
+method; if you need to add extra joins or similar call L</search> and then
+L</single> without a condition on the L<DBIx::Class::ResultSet> returned from
+that.
+
+B<Note>: As of 0.08100, this method assumes that the query returns only one
+row. If more than one row is returned, you will receive a warning:
+
+ Query returned more than one row
+
+In this case, you should be using L</first> or L</find> instead.
=cut
with to find the number of elements. If passed arguments, does a search
on the resultset and counts the results of that.
-Note: When using C<count> with C<group_by>, L<DBIX::Class> emulates C<GROUP BY>
+Note: When using C<count> with C<group_by>, L<DBIx::Class> emulates C<GROUP BY>
using C<COUNT( DISTINCT( columns ) )>. Some databases (notably SQLite) do
not support C<DISTINCT> with multiple columns. If you are using such a
database, you should only use columns from the main table in your C<group_by>
$count -= $self->{_attrs}{offset} if $self->{_attrs}{offset};
$count = $self->{attrs}{rows} if
$self->{attrs}{rows} and $self->{attrs}{rows} < $count;
+ $count = 0 if ($count < 0);
return $count;
}
# offset, order by and page are not needed to count. record_filter is cdbi
delete $attrs->{$_} for qw/rows offset order_by page pager record_filter/;
- my $tmp_rs = (ref $self)->new($self->_source_handle, $attrs);
+ my $tmp_rs = (ref $self)->new($self->result_source, $attrs);
my ($count) = $tmp_rs->cursor->next;
return $count;
}
+sub _bool {
+ return 1;
+}
+
=head2 count_literal
=over 4
submitting to a $resultset->create(...) method.
In void context, C<insert_bulk> in L<DBIx::Class::Storage::DBI> is used
-to insert the data, as this is a faster method.
+to insert the data, as this is a faster method.
Otherwise, each set of data is inserted into the database using
L<DBIx::Class::ResultSet/create>, and a arrayref of the resulting row
print $ArtistOne->name; ## response is 'Artist One'
print $ArtistThree->cds->count ## reponse is '2'
+
+Please note an important effect on your data when choosing between void and
+wantarray context. Since void context goes straight to C<insert_bulk> in
+L<DBIx::Class::Storage::DBI> this will skip any component that is overriding
+c<insert>. So if you are using something like L<DBIx-Class-UUIDColumns> 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.
=cut
}
## do bulk insert on current row
- my @values = map {
- [ map {
- defined $_ ? $_ : $self->throw_exception("Undefined value for column!")
- } @$_{@names} ]
- } @$data;
+ my @values = map { [ @$_{@names} ] } @$data;
$self->result_source->storage->insert_bulk(
$self->result_source,
sub page {
my ($self, $page) = @_;
- return (ref $self)->new($self->_source_handle, { %{$self->{attrs}}, page => $page });
+ return (ref $self)->new($self->result_source, { %{$self->{attrs}}, page => $page });
}
=head2 new_result
=back
-Creates an object in the resultset's result class and returns it.
+Creates a new row object in the resultset's result class and returns
+it. The row is not inserted into the database at this point, call
+L<DBIx::Class::Row/insert> to do that. Calling L<DBIx::Class::Row/in_storage>
+will tell you whether the row object has been inserted or not.
+
+Passes the hashref of input on to L<DBIx::Class::Row/new>.
=cut
my ($self, $values) = @_;
$self->throw_exception( "new_result needs a hash" )
unless (ref $values eq 'HASH');
- $self->throw_exception(
- "Can't abstract implicit construct, condition not a hash"
- ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
+ my %new;
my $alias = $self->{attrs}{alias};
- my $collapsed_cond = $self->{cond} ? $self->_collapse_cond($self->{cond}) : {};
- my %new = (
+
+ if (
+ defined $self->{cond}
+ && $self->{cond} eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION
+ ) {
+ %new = %{$self->{attrs}{related_objects}};
+ } else {
+ $self->throw_exception(
+ "Can't abstract implicit construct, condition not a hash"
+ ) if ($self->{cond} && !(ref $self->{cond} eq 'HASH'));
+
+ my $collapsed_cond = (
+ $self->{cond}
+ ? $self->_collapse_cond($self->{cond})
+ : {}
+ );
+
+ # precendence must be given to passed values over values inherited from
+ # the cond, so the order here is important.
+ my %implied = %{$self->_remove_alias($collapsed_cond, $alias)};
+ while( my($col,$value) = each %implied ){
+ if(ref($value) eq 'HASH' && keys(%$value) && (keys %$value)[0] eq '='){
+ $new{$col} = $value->{'='};
+ next;
+ }
+ $new{$col} = $value if $self->_is_deterministic_value($value);
+ }
+ }
+
+ %new = (
+ %new,
%{ $self->_remove_alias($values, $alias) },
- %{ $self->_remove_alias($collapsed_cond, $alias) },
-source_handle => $self->_source_handle,
-result_source => $self->result_source, # DO NOT REMOVE THIS, REQUIRED
);
return $self->result_class->new(\%new);
}
+# _is_deterministic_value
+#
+# Make an effor to strip non-deterministic values from the condition,
+# to make sure new_result chokes less
+
+sub _is_deterministic_value {
+ my $self = shift;
+ my $value = shift;
+ my $ref_type = ref $value;
+ return 1 if $ref_type eq '' || $ref_type eq 'SCALAR';
+ return 1 if Scalar::Util::blessed($value);
+ return 0;
+}
+
# _collapse_cond
#
# Recursively collapse the condition.
=item Arguments: \%vals
-=item Return Value: $object
+=item Return Value: a L<DBIx::Class::Row> $object
=back
-Inserts a record into the resultset and returns the object representing it.
+Attempt to create a single new row or a row with multiple related rows
+in the table represented by the resultset (and related tables). This
+will not check for duplicate rows before inserting, use
+L</find_or_create> to do that.
+
+To create one row for this resultset, pass a hashref of key/value
+pairs representing the columns of the table and the values you wish to
+store. If the appropriate relationships are set up, foreign key fields
+can also be passed an object representing the foreign row, and the
+value will be set to it's primary key.
+
+To create related objects, pass a hashref for the value if the related
+item is a foreign key relationship (L<DBIx::Class::Relationship/belongs_to>),
+and use the name of the relationship as the key. (NOT the name of the field,
+necessarily). For C<has_many> and C<has_one> relationships, pass an arrayref
+of hashrefs containing the data for each of the rows to create in the foreign
+tables, again using the relationship name as the key.
+
+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</new>), will be inserted into their appropriate tables.
Effectively a shortcut for C<< ->new_result(\%vals)->insert >>.
+Example of creating a new row.
+
+ $person_rs->create({
+ name=>"Some Person",
+ email=>"somebody@someplace.com"
+ });
+
+Example of creating a new row and also creating rows in a related C<has_many>
+or C<has_one> resultset. Note Arrayref.
+
+ $artist_rs->create(
+ { artistid => 4, name => 'Manufactured Crap', cds => [
+ { title => 'My First CD', year => 2006 },
+ { title => 'Yet More Tweeny-Pop crap', year => 2007 },
+ ],
+ },
+ );
+
+Example of creating a new row and also creating a row in a related
+C<belongs_to>resultset. Note Hashref.
+
+ $cd_rs->create({
+ title=>"Music for Silly Walks",
+ year=>2000,
+ artist => {
+ name=>"Silly Musician",
+ }
+ });
+
=cut
sub create {
{ key => 'cd_artist_title' }
);
+Note: Because find_or_create() reads from the database and then
+possibly inserts based on the result, this method is subject to a race
+condition. Another process could create a record in the table after
+the find has completed and before the create has started. To avoid
+this problem, use find_or_create() inside a transaction.
+
See also L</find> and L</update_or_create>. For information on how to declare
unique constraints, see L<DBIx::Class::ResultSource/add_unique_constraint>.
Gets the contents of the cache for the resultset, if the cache is set.
+The cache is populated either by using the L</prefetch> attribute to
+L</search> or by calling L</set_cache>.
+
=cut
sub get_cache {
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
+L</prefetch> attribute to L</search>.
+
=cut
sub set_cache {
my $rel_obj = $self->result_source->relationship_info($rel);
$self->throw_exception(
- "search_related: result source '" . $self->_source_handle->source_moniker .
+ "search_related: result source '" . $self->result_source->source_name .
"' has no such relationship $rel")
unless $rel_obj;
#XXX - temp fix for result_class bug. There likely is a more elegant fix -groditi
my %attrs = %{$self->{attrs}||{}};
- delete $attrs{result_class};
+ delete @attrs{qw(result_class alias)};
my $new_cache;
}
}
- my $new = $self->_source_handle
- ->schema
- ->resultset($rel_obj->{class})
- ->search_rs(
- undef, {
- %attrs,
- join => undef,
- prefetch => undef,
- select => undef,
- as => undef,
- alias => $alias,
- where => $self->{cond},
- seen_join => $seen,
- from => $from,
- });
+ my $rel_source = $self->result_source->related_source($rel);
+
+ my $new = do {
+
+ # The reason we do this now instead of passing the alias to the
+ # search_rs below is that if you wrap/overload resultset on the
+ # source you need to know what alias it's -going- to have for things
+ # to work sanely (e.g. RestrictWithObject wants to be able to add
+ # extra query restrictions, and these may need to be $alias.)
+
+ my $attrs = $rel_source->resultset_attributes;
+ local $attrs->{alias} = $alias;
+
+ $rel_source->resultset
+ ->search_rs(
+ undef, {
+ %attrs,
+ join => undef,
+ prefetch => undef,
+ select => undef,
+ as => undef,
+ where => $self->{cond},
+ seen_join => $seen,
+ from => $from,
+ });
+ };
$new->set_cache($new_cache) if $new_cache;
$new;
};
my $join = ($attrs->{join}
? [ $attrs->{join}, $extra_join ]
: $extra_join);
+
+ # we need to take the prefetch the attrs into account before we
+ # ->resolve_join as otherwise they get lost - captainL
+ my $merged = $self->_merge_attr( $join, $attrs->{prefetch} );
+
$from = [
@$from,
- ($join ? $source->resolve_join($join, $attrs->{alias}, $seen) : ()),
+ ($join ? $source->resolve_join($merged, $attrs->{alias}, $seen) : ()),
];
return ($from,$seen);
$join = $self->_merge_attr(
$join, $attrs->{prefetch}
);
+
}
$attrs->{from} = # have to copy here to avoid corrupting the original
@{$attrs->{from}},
$source->resolve_join($join, $alias, { %{$attrs->{seen_join}||{}} })
];
+
}
$attrs->{group_by} ||= $attrs->{select} if delete $attrs->{distinct};
return $self->{_attrs} = $attrs;
}
+sub _rollout_attr {
+ my ($self, $attr) = @_;
+
+ if (ref $attr eq 'HASH') {
+ return $self->_rollout_hash($attr);
+ } elsif (ref $attr eq 'ARRAY') {
+ return $self->_rollout_array($attr);
+ } else {
+ return [$attr];
+ }
+}
+
+sub _rollout_array {
+ my ($self, $attr) = @_;
+
+ my @rolled_array;
+ foreach my $element (@{$attr}) {
+ if (ref $element eq 'HASH') {
+ push( @rolled_array, @{ $self->_rollout_hash( $element ) } );
+ } elsif (ref $element eq 'ARRAY') {
+ # XXX - should probably recurse here
+ push( @rolled_array, @{$self->_rollout_array($element)} );
+ } else {
+ push( @rolled_array, $element );
+ }
+ }
+ return \@rolled_array;
+}
+
+sub _rollout_hash {
+ my ($self, $attr) = @_;
+
+ my @rolled_array;
+ foreach my $key (keys %{$attr}) {
+ push( @rolled_array, { $key => $attr->{$key} } );
+ }
+ return \@rolled_array;
+}
+
+sub _calculate_score {
+ my ($self, $a, $b) = @_;
+
+ if (ref $b eq 'HASH') {
+ my ($b_key) = keys %{$b};
+ if (ref $a eq 'HASH') {
+ my ($a_key) = keys %{$a};
+ if ($a_key eq $b_key) {
+ return (1 + $self->_calculate_score( $a->{$a_key}, $b->{$b_key} ));
+ } else {
+ return 0;
+ }
+ } else {
+ return ($a eq $b_key) ? 1 : 0;
+ }
+ } else {
+ if (ref $a eq 'HASH') {
+ my ($a_key) = keys %{$a};
+ return ($b eq $a_key) ? 1 : 0;
+ } else {
+ return ($b eq $a) ? 1 : 0;
+ }
+ }
+}
+
sub _merge_attr {
my ($self, $a, $b) = @_;
+
return $b unless defined($a);
return $a unless defined($b);
- if (ref $b eq 'HASH' && ref $a eq 'HASH') {
- foreach my $key (keys %{$b}) {
- if (exists $a->{$key}) {
- $a->{$key} = $self->_merge_attr($a->{$key}, $b->{$key});
- } else {
- $a->{$key} = $b->{$key};
+ $a = $self->_rollout_attr($a);
+ $b = $self->_rollout_attr($b);
+
+ my $seen_keys;
+ foreach my $b_element ( @{$b} ) {
+ # find best candidate from $a to merge $b_element into
+ my $best_candidate = { position => undef, score => 0 }; my $position = 0;
+ foreach my $a_element ( @{$a} ) {
+ my $score = $self->_calculate_score( $a_element, $b_element );
+ if ($score > $best_candidate->{score}) {
+ $best_candidate->{position} = $position;
+ $best_candidate->{score} = $score;
}
+ $position++;
}
- return $a;
- } else {
- $a = [$a] unless ref $a eq 'ARRAY';
- $b = [$b] unless ref $b eq 'ARRAY';
-
- my $hash = {};
- my @array;
- foreach my $x ($a, $b) {
- foreach my $element (@{$x}) {
- if (ref $element eq 'HASH') {
- $hash = $self->_merge_attr($hash, $element);
- } elsif (ref $element eq 'ARRAY') {
- push(@array, @{$element});
- } else {
- push(@array, $element) unless $b == $x
- && grep { $_ eq $element } @array;
- }
+ my ($b_key) = ( ref $b_element eq 'HASH' ) ? keys %{$b_element} : ($b_element);
+
+ if ($best_candidate->{score} == 0 || exists $seen_keys->{$b_key}) {
+ push( @{$a}, $b_element );
+ } else {
+ my $a_best = $a->[$best_candidate->{position}];
+ # merge a_best and b_element together and replace original with merged
+ if (ref $a_best ne 'HASH') {
+ $a->[$best_candidate->{position}] = $b_element;
+ } elsif (ref $b_element eq 'HASH') {
+ my ($key) = keys %{$a_best};
+ $a->[$best_candidate->{position}] = { $key => $self->_merge_attr($a_best->{$key}, $b_element->{$key}) };
}
}
-
- @array = grep { !exists $hash->{$_} } @array;
-
- return keys %{$hash}
- ? ( scalar(@array)
- ? [$hash, @array]
- : $hash
- )
- : \@array;
+ $seen_keys->{$b_key} = 1; # don't merge the same key twice
}
+
+ return $a;
}
sub result_source {
sub throw_exception {
my $self=shift;
- $self->_source_handle->schema->throw_exception(@_);
+ if (ref $self && $self->_source_handle->schema) {
+ $self->_source_handle->schema->throw_exception(@_)
+ } else {
+ croak(@_);
+ }
+
}
# XXX: FIXME: Attributes docs need clearing up
=over 4
Indicates additional columns to be selected from storage. Works the same as
-L<select> but adds columns to the selection.
+L</select> but adds columns to the selection.
=back
=over 4
-Indicates additional column names for those added via L<+select>.
+Indicates additional column names for those added via L</+select>.
=back
=back
-Indicates column names for object inflation. That is, c< as >
+Indicates column names for object inflation. That is, C<as>
indicates the name that the column can be accessed as via the
C<get_column> method (or via the object accessor, B<if one already
-exists>). It has nothing to do with the SQL code C< SELECT foo AS bar
->.
+exists>). It has nothing to do with the SQL code C<SELECT foo AS bar>.
-The C< as > attribute is used in conjunction with C<select>,
+The C<as> attribute is used in conjunction with C<select>,
usually when C<select> contains one or more function or stored
procedure names:
If you want to fetch related objects from other tables as well, see C<prefetch>
below.
+For more help on using joins with search, see L<DBIx::Class::Manual::Joining>.
+
=head2 prefetch
=over 4
=back
-Contains one or more relationships that should be fetched along with the main
-query (when they are accessed afterwards they will have already been
-"prefetched"). This is useful for when you know you will need the related
-objects, because it saves at least one query:
+Contains one or more relationships that should be fetched along with
+the main query (when they are accessed afterwards the data will
+already be available, without extra queries to the database). This is
+useful for when you know you will need the related objects, because it
+saves at least one query:
my $rs = $schema->resultset('Tag')->search(
undef,
case.
Simple prefetches will be joined automatically, so there is no need
-for a C<join> attribute in the above search. If you're prefetching to
-depth (e.g. { cd => { artist => 'label' } or similar), you'll need to
-specify the join as well.
+for a C<join> attribute in the above search.
C<prefetch> can be used with the following relationship types: C<belongs_to>,
C<has_one> (or if you're using C<add_relationship>, any relationship declared
-with an accessor type of 'single' or 'filter').
+with an accessor type of 'single' or 'filter'). A more complex example that
+prefetches an artists cds, the tracks on those cds, and the tags associted
+with that artist is given below (assuming many-to-many from artists to tags):
+
+ my $rs = $schema->resultset('Artist')->search(
+ undef,
+ {
+ prefetch => [
+ { cds => 'tracks' },
+ { artist_tags => 'tags' }
+ ]
+ }
+ );
+
+
+B<NOTE:> If you specify a C<prefetch> attribute, the C<join> and C<select>
+attributes will be ignored.
=head2 page
# SELECT child.* FROM person child
# INNER JOIN person father ON child.father_id = father.id
+=head2 for
+
+=over 4
+
+=item Value: ( 'update' | 'shared' )
+
+=back
+
+Set to 'update' for a SELECT ... FOR UPDATE or 'shared' for a SELECT
+... FOR SHARED.
+
=cut
1;
projects / dbsrgits/DBIx-Class.git / blobdiff