From: Alexander Hartmaier Date: Wed, 7 Nov 2012 16:17:55 +0000 (+0100) Subject: Improve the populate docs in ::Schema and ::ResultSet X-Git-Tag: v0.08205~45 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=44e95db4537a7ace8aee44bcf74b8b9d79c03b6b;p=dbsrgits%2FDBIx-Class.git Improve the populate docs in ::Schema and ::ResultSet --- diff --git a/Changes b/Changes index 6776d3e..2751605 100644 --- a/Changes +++ b/Changes @@ -9,6 +9,8 @@ Revision history for DBIx::Class - Fix hash-randomization test issues (RT#81638) - Disallow erroneous calling of connect_info on a replicated storage (RT#78436) + * Misc + - Improve the populate docs in ::Schema and ::ResultSet 0.08204 2012-11-08 * New Features / Changes diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm index ed5a7ae..8806682 100644 --- a/lib/DBIx/Class/ResultSet.pm +++ b/lib/DBIx/Class/ResultSet.pm @@ -2038,28 +2038,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 -In void context, C in L is used -to insert the data, as this is a faster method. +=item NOTE -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. +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. + +=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. + +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: + + $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' ], + ]); - my $Artist_rs = $schema->resultset("Artist"); +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. - ## Void Context Example - $Artist_rs->populate([ + $schema->resultset("Artist")->populate([ { artistid => 4, name => 'Manufactured Crap', cds => [ { title => 'My First CD', year => 2006 }, { title => 'Yet More Tweeny-Pop crap', year => 2007 }, @@ -2073,37 +2100,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 diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm index c55eefd..0d49b4b 100644 --- a/lib/DBIx/Class/Schema.pm +++ b/lib/DBIx/Class/Schema.pm @@ -738,45 +738,33 @@ found in L. =over 4 -=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>, \@data; +=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>, [ \@column_list, \@row_values+ ] | [ \%col_data+ ] -=item Return Value: L<\@$results|DBIx::Class::Manual::ResultClass> | undef +=item Return Value: L<\@result_objects|DBIx::Class::Manual::ResultClass> (scalar context) | L<@result_objects|DBIx::Class::Manual::ResultClass> (list context) =back -Pass this method a resultsource name, and an arrayref of -arrayrefs. The arrayrefs should contain a list of column names, -followed by one or many sets of matching data for the given columns. - -In void context, C in L is used -to insert the data, as this is a fast method. However, insert_bulk currently -assumes that your datasets all contain the same type of values, using scalar -references in a column in one row, and not in another will probably not work. - -Otherwise, each set of data is inserted into the database using -L, and an arrayref of the Result -objects is returned. - -e.g. - - $schema->populate('Artist', [ - [ qw/artistid name/ ], - [ 1, 'Popular Band' ], - [ 2, 'Indie Band' ], - ... - ]); - -Since wantarray context is basically the same as looping over $rs->create(...) -you won't see any performance benefits and in this case the method is more for -convenience. Void context sends the column information directly to storage -using s bulk insert method. So the performance will be much better for -storages that support this method. - -Because of this difference in the way void context inserts rows into your -database you need to note how this will effect any loaded components that -override or augment insert. For example if you are using a component such -as L to populate your primary keys you MUST use -wantarray context if you want the PKs automatically created. +A convenience shortcut to L. Equivalent to: + + $schema->resultset($source_name)->populate([...]); + +=over 4 + +=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), 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. + +=back =cut