docs clarification- orm.joinedload

Issue #3538 closed
jvanasco
created an issue

I'd like to suggest extending the note in the docs on orm.joined load with something like the following: [http://docs.sqlalchemy.org/en/latest/orm/loading_relationships.html#sqlalchemy.orm.joinedload, http://docs.sqlalchemy.org/en/rel_0_8/orm/loading.html#sqlalchemy.orm.joinedload]

========== If you have already explicitly JOINed a collection onto your query for filtering (or other use), you will likely want to use orm.contains_eager instead of orm.joinedload. joinedload will create a second anonymously aliased join, while contains_eager will more efficiently re-use the existing join. =======

Comments (4)

  1. Michael Bayer repo owner

    this note is there right now:

    The joins produced by orm.joinedload() are anonymously aliased. The criteria by which the join proceeds cannot be modified, nor can the Query refer to these joins in any way, including ordering.

    To produce a specific SQL JOIN which is explicitly available, use Query.join(). To combine explicit JOINs with eager loading of collections, use orm.contains_eager(); see Routing Explicit Joins/Statements into Eagerly Loaded Collections.

  2. jvanasco reporter

    Yeah, I meant to suggest my sentence as an addition to that note. The idea was to keyword onto the "second" join and "re-use" (vs "combine"). It's a small difference and somewhat redundant for looking at the docs in a narrative context, but is geared to address a wider net on how people will search for help (ie, why is there a second join? how do i re-use the join?" The existing note also doesn't make it obvious that if you don't "combine explicit joins with eager loading" you'll end up with a redundant query -- and that you probably want to use contains_eager.

  3. Log in to comment