Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation Improvements #100

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Documentation Improvements #100

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a8d6c49
(travis) Reorganize POISON_ENV mode
ribasushi Apr 11, 2016
fcdc83f
Improve a document's introduction
tomhukins Apr 11, 2016
03dfab9
Improve documentation readability
tomhukins Apr 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions lib/DBIx/Class/Manual/Joining.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,15 @@ If you don't know the basics of DBIx::Class, read
L<DBIx::Class::Manual::Intro> first. Skip this section if you know how
SQL joins work.

But I'll explain anyway. Assuming you have created your database in a
more or less sensible way, you will end up with several tables that
contain C<related> information. For example, you may have a table
containing information about C<CD>s, containing the CD title and its
year of publication, and another table containing all the C<Track>s
for the CDs, one track per row.
If you have created your database sensibly, you will have several tables
that contain C<related> information. For example, you may have a table
representing C<CD>s, containing each CD's title and its year of
publication, and another table representing all the C<Track>s for the
CDs, one track per row.

When you wish to extract information about a particular CD and all
its tracks, You can either fetch the CD row, then make another query
to fetch the tracks, or you can use a join. Compare:
To retrieve information about a particular CD and all its tracks, either
fetch the CD row, then make another query to fetch the tracks, or use a
join. Compare:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this needs to be expanded a little - as join on its own won't fetch anything extra. Perhaps L<join and select|DBIx::Class::Resultset/prefetch> the extra data.

Also towards the end of this section there is a link to a reference manual on SQL-side join syntax, not sure if this is the best resource... Thoughts?

Thanks for the contribution!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Mon, Apr 11, 2016 at 03:29:08PM -0700, Peter Rabbitson wrote:

I think this needs to be expanded a little - as join on its own
won't fetch anything extra. Perhaps L<join and select|DBIx::Class::Resultset/prefetch> the extra data.

Good point. I'll work on that.

Also towards the end of this section there is a link to a reference
manual on SQL-side join syntax, not sure if this is the best
resource... Thoughts?

https://en.wikipedia.org/wiki/Join_%28SQL%29 provides a more database
agnostic reference and
https://blog.codinghorror.com/a-visual-explanation-of-sql-joins/
provides a popular visual summary. How about I link to those instead?

Tom

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about I link to those instead?

Excellent! I'd order the visual explainer first. Also since you are in this headspace already: could you possibly work a sentence about this somewhere: https://rt.cpan.org/Ticket/Display.html?id=104289#txn-1494725. I am not trying to create more work for you, this is just tightly related and has been gathering dust for a while...

Cheers!


SELECT ID, Title, Year FROM CD WHERE Title = 'Funky CD';
# .. Extract the ID, which is 10
Expand All @@ -39,7 +38,7 @@ L<http://dev.mysql.com/doc/refman/5.0/en/join.html>.

=head1 DEFINING JOINS AND RELATIONSHIPS

In L<DBIx::Class> each relationship between two tables needs to first
In L<DBIx::Class> each relationship between two tables must
be defined in the L<ResultSource|DBIx::Class::Manual::Glossary/ResultSource> for the
table. If the relationship needs to be accessed in both directions
(i.e. Fetch all tracks of a CD, and fetch the CD data for a Track),
Expand All @@ -53,7 +52,7 @@ And in C<MySchema::Tracks>:

MySchema::Tracks->belongs_to('cd', 'MySchema::CD', 'CDID');

There are several other types of relationships, they are more
There are several other types of relationships, more
comprehensively described in L<DBIx::Class::Relationship>.

=head1 USING JOINS
Expand Down