Add doc note for contains_eager() w/ subclasses.

Change-Id: I9634136e1855a081c25b04bb6ae8248f0f94be1c
Fixes: #4130
(cherry picked from commit 152522b3f28de290d9ea2903fa2c414b8579515a)

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 079f0d6e60e6498b03e0e8b17f5fee2126f0d9fc..4e3f1e767efef643b3a0ffb44bc697d08f074a40 100644 (file)
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -546,7 +546,7 @@ def contains_eager(loadopt, attr, alias=None):
     ``User`` entity, and the returned ``Order`` objects would have the
     ``Order.user`` attribute pre-populated.
 
-    :func:`contains_eager` also accepts an `alias` argument, which is the
+    :func:`.contains_eager` also accepts an `alias` argument, which is the
     string name of an alias, an :func:`~sqlalchemy.sql.expression.alias`
     construct, or an :func:`~sqlalchemy.orm.aliased` construct. Use this when
     the eagerly-loaded rows are to come from an aliased table::
@@ -556,6 +556,18 @@ def contains_eager(loadopt, attr, alias=None):
                 join((user_alias, Order.user)).\
                 options(contains_eager(Order.user, alias=user_alias))
 
+    When using :func:`.contains_eager` in conjunction with inherited
+    subclasses, the :meth:`.RelationshipProperty.of_type` modifier should
+    also be used in order to set up the pathing properly::
+
+        sess.query(Company).\
+            outerjoin(Company.employees.of_type(Manager)).\
+            options(
+                contains_eager(
+                    Company.employees.of_type(Manager),
+                    alias=Manager)
+            )
+
     .. seealso::
 
         :ref:`loading_toplevel`