Add explanation of `polymorphic_identity` to docs

Fixes: #4951
Change-Id: I592063ffc7c9ffa0eff8bffd53f6ce407a551d15
(cherry picked from commit 295441bab3051e96e7651047acb02cabca9ac0f5)

diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst
index ed4470e19b29b041724954600f7c100c6b067811..7a4ee7025090a0beff012916cb50d302da725dae 100644 (file)
--- a/doc/build/orm/inheritance.rst
+++ b/doc/build/orm/inheritance.rst
@@ -58,7 +58,9 @@ Above, an additional column ``type`` is established to act as the
 **discriminator**, configured as such using the :paramref:`.mapper.polymorphic_on`
 parameter.  This column will store a value which indicates the type of object
 represented within the row. The column may be of any datatype, though string
-and integer are the most common.
+and integer are the most common.  The actual data value to be applied to this
+column for a particular row in the database is specified using the
+:paramref:`.mapper.polymorphic_identity` parameter, described below.
 
 While a polymorphic discriminator expression is not strictly necessary, it is
 required if polymorphic loading is desired.   Establishing a simple column on
@@ -96,11 +98,34 @@ columns), as well as a foreign key reference to the parent table::
             'polymorphic_identity':'manager',
         }
 
-It is most common that the foreign key constraint is established on the same
-column or columns as the primary key itself, however this is not required; a
-column distinct from the primary key may also be made to refer to the parent
-via foreign key.  The way that a JOIN is constructed from the base table to
-subclasses is also directly customizable, however this is rarely necessary.
+In the above example, each mapping specifies the
+:paramref:`.mapper.polymorphic_identity` parameter within its mapper arguments.
+This value populates the column designated by the
+:paramref:`.mapper.polymorphic_on` parameter established on the base  mapper.
+The :paramref:`.mapper.polymorphic_identity`  parameter should be unique to
+each mapped class across the whole hierarchy, and there should only be one
+"identity" per mapped class; as noted above,  "cascading" identities where some
+subclasses introduce a second identity are not supported.
+
+The ORM uses the value set up by :paramref:`.mapper.polymorphic_identity` in
+order to determine which class a row belongs towards when loading rows
+polymorphically.  In the example above, every row which represents an
+``Employee`` will have the value ``'employee'`` in its ``type`` row; similarly,
+every ``Engineer`` will get the value ``'engineer'``, and each ``Manager`` will
+get the value ``'manager'``. Regardless of whether the inheritance mapping uses
+distinct joined tables for subclasses as in joined table inheritance, or all
+one table as in single table inheritance, this value is expected to be
+persisted and available to the ORM when querying. The
+:paramref:`.mapper.polymorphic_identity` parameter also applies to concrete
+table inheritance, but is not actually persisted; see the later section at
+:ref:`concrete_inheritance` for details.
+
+In a polymorphic setup, it is most common that the foreign key constraint is
+established on the same column or columns as the primary key itself, however
+this is not required; a column distinct from the primary key may also be made
+to refer to the parent via foreign key.  The way that a JOIN is constructed
+from the base table to subclasses is also directly customizable, however this
+is rarely necessary.
 
 .. topic:: Joined inheritance primary keys