Fix complex limits with subqueries in selectors
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / ResultSource / View.pm
CommitLineData
1d521afd 1package DBIx::Class::ResultSource::View;
2
3use strict;
4use warnings;
5
6use DBIx::Class::ResultSet;
7
8use base qw/DBIx::Class/;
9__PACKAGE__->load_components(qw/ResultSource/);
030c27ad 10__PACKAGE__->mk_group_accessors(
e55d9d89 11 'simple' => qw(is_virtual view_definition deploy_depends_on) );
1d521afd 12
1d521afd 13=head1 NAME
14
00be2e0b 15DBIx::Class::ResultSource::View - ResultSource object representing a view
1d521afd 16
17=head1 SYNOPSIS
18
03460bef 19 package MyApp::Schema::Result::Year2000CDs;
00be2e0b 20
d88ecca6 21 use base qw/DBIx::Class::Core/;
00be2e0b 22
00be2e0b 23 __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
24
25 __PACKAGE__->table('year2000cds');
26 __PACKAGE__->result_source_instance->is_virtual(1);
27 __PACKAGE__->result_source_instance->view_definition(
28 "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
b4664250 29 );
30 __PACKAGE__->add_columns(
31 'cdid' => {
32 data_type => 'integer',
33 is_auto_increment => 1,
34 },
35 'artist' => {
36 data_type => 'integer',
37 },
38 'title' => {
39 data_type => 'varchar',
40 size => 100,
41 },
42 );
00be2e0b 43
1d521afd 44=head1 DESCRIPTION
45
00be2e0b 46View object that inherits from L<DBIx::Class::ResultSource>
47
b4664250 48This class extends ResultSource to add basic view support.
00be2e0b 49
b4664250 50A view has a L</view_definition>, which contains a SQL query. The query can
51only have parameters if L</is_virtual> is set to true. It may contain JOINs,
52sub selects and any other SQL your database supports.
00be2e0b 53
54View definition SQL is deployed to your database on
55L<DBIx::Class::Schema/deploy> unless you set L</is_virtual> to true.
56
57Deploying the view does B<not> translate it between different database
58syntaxes, so be careful what you write in your view SQL.
59
66d2a14e 60Virtual views (L</is_virtual> true), are assumed to not
00be2e0b 61exist in your database as a real view. The L</view_definition> in this
62case replaces the view name in a FROM clause in a subselect.
63
b4664250 64=head1 EXAMPLES
65
03460bef 66Having created the MyApp::Schema::Year2000CDs schema as shown in the SYNOPSIS
b4664250 67above, you can then:
68
69 $2000_cds = $schema->resultset('Year2000CDs')
70 ->search()
71 ->all();
72 $count = $schema->resultset('Year2000CDs')
73 ->search()
74 ->count();
75
76If you modified the schema to include a placeholder
77
78 __PACKAGE__->result_source_instance->view_definition(
c584b60b 79 "SELECT cdid, artist, title FROM cd WHERE year = ?"
b4664250 80 );
81
82and ensuring you have is_virtual set to true:
83
84 __PACKAGE__->result_source_instance->is_virtual(1);
85
86You could now say:
87
88 $2001_cds = $schema->resultset('Year2000CDs')
89 ->search({}, { bind => [2001] })
90 ->all();
91 $count = $schema->resultset('Year2000CDs')
92 ->search({}, { bind => [2001] })
93 ->count();
94
00be2e0b 95=head1 SQL EXAMPLES
96
97=over
98
66d2a14e 99=item is_virtual set to false
00be2e0b 100
101 $schema->resultset('Year2000CDs')->all();
102
103 SELECT cdid, artist, title FROM year2000cds me
104
66d2a14e 105=item is_virtual set to true
00be2e0b 106
107 $schema->resultset('Year2000CDs')->all();
108
109 SELECT cdid, artist, title FROM
110 (SELECT cdid, artist, title FROM cd WHERE year ='2000') me
111
112=back
1d521afd 113
114=head1 METHODS
115
9774f48b 116=head2 is_virtual
117
00be2e0b 118 __PACKAGE__->result_source_instance->is_virtual(1);
119
120Set to true for a virtual view, false or unset for a real
121database-based view.
122
123=head2 view_definition
124
125 __PACKAGE__->result_source_instance->view_definition(
126 "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
127 );
128
129An SQL query for your view. Will not be translated across database
130syntaxes.
131
e55d9d89 132=head2 deploy_depends_on
133
134 __PACKAGE__->result_source_instance->deploy_depends_on(
03460bef 135 ["MyApp::Schema::Result::Year","MyApp::Schema::Result::CD"]
e55d9d89 136 );
137
41d90e35 138Specify the views (and only the views) that this view depends on.
0edbc8f0 139Pass this an array reference of fully qualified result classes.
00be2e0b 140
141=head1 OVERRIDDEN METHODS
9774f48b 142
1d521afd 143=head2 from
144
145Returns the FROM entry for the table (i.e. the view name)
00be2e0b 146or the SQL as a subselect if this is a virtual view.
1d521afd 147
148=cut
149
9774f48b 150sub from {
e55d9d89 151 my $self = shift;
152 return \"(${\$self->view_definition})" if $self->is_virtual;
153 return $self->name;
9774f48b 154}
1d521afd 155
5f2aeb09 156=head1 OTHER METHODS
1d521afd 157
5f2aeb09 158=head2 new
1d521afd 159
5f2aeb09 160The constructor.
1d521afd 161
5f2aeb09 162=cut
1d521afd 163
7364d776 164sub new {
165 my ( $self, @args ) = @_;
166 my $new = $self->next::method(@args);
7c4ade2a 167 $new->{deploy_depends_on} =
168 { map { $_ => 1 }
169 @{ $new->{deploy_depends_on} || [] } }
170 unless ref $new->{deploy_depends_on} eq 'HASH';
7364d776 171 return $new;
172}
1d521afd 173
1d521afd 1741;
175
176=head1 AUTHORS
00be2e0b 177
7aaf4192 178See L<DBIx::Class/CONTRIBUTORS>.
66d2a14e 179
1d521afd 180=head1 LICENSE
181
182You may distribute this code under the same terms as Perl itself.
183
184=cut
185