<commit_before>.. _inheritance_toplevel:

Mapping Class Inheritance Hierarchies
=====================================

SQLAlchemy supports three forms of inheritance: **single table inheritance**,
where several types of classes are represented by a single table, **concrete
table inheritance**, where each type of class is represented by independent
tables, and **joined table inheritance**, where the class hierarchy is broken
up among dependent tables, each class represented by its own table that only
includes those attributes local to that class.

The most common forms of inheritance are single and joined table, while
concrete inheritance presents more configurational challenges.

When mappers are configured in an inheritance relationship, SQLAlchemy has the
ability to load elements :term:`polymorphically`, meaning that a single query can
return objects of multiple types.

.. seealso::

    :ref:`examples_inheritance` - complete exampes of joined, single and
    concrete inheritance

.. _joined_inheritance:

Joined Table Inheritance
------------------------

In joined table inheritance, each class along a hierarchy of classes
is represented by a distinct table.  Querying for a particular subclass
in the hierarchy will render as a SQL JOIN along all tables in its
inheritance path - if the class is the base class, the default behavior
is to include only the base table in the SELECT.   In all cases, the
ultimate class to instantiate for a given row is determined by a discriminator
column or expression that works against the base table.    A subclass
loaded against the base table only will have only base attributes
populated at first; the additional attributes will :term:`lazy load` when
they are accessed.  Options also exist to query for all
columns across multiple tables/subclasses up front.

The base class in a joined inheritance hierarchy is configured with
additional arguments that will refer to the polymorphic discriminator
column as well as the identifier for the base class::

    class Employee(Base):
        __tablename__ = 'employee'
        id = Column(Integer, primary_key=True)
        name = Column(String(50))
        type = Column(String(50))

        __mapper_args__ = {
            'polymorphic_identity':'employee',
            'polymorphic_on':type
        }

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.

While a polymorphic discriminator expression is not strictly necessary, it is
required if polymorphic loading is desired.   Establishing a simple column on
the base table is the easiest way to achieve this, however very sophisticated
inheritance mappings may even configure a SQL expression such as a CASE
statement as the polymorphic discriminator.

.. note::<commit_msg>Small docs style fixes in inheritance.rst<commit_after>.. _inheritance_toplevel:

Mapping Class Inheritance Hierarchies
=====================================

SQLAlchemy supports three forms of inheritance: **single table inheritance**,
where several types of classes are represented by a single table, **concrete
table inheritance**, where each type of class is represented by independent
tables, and **joined table inheritance**, where the class hierarchy is broken
up among dependent tables, each class represented by its own table that only
includes those attributes local to that class.

The most common forms of inheritance are single and joined table, while
concrete inheritance presents more configurational challenges.

When mappers are configured in an inheritance relationship, SQLAlchemy has the
ability to load elements :term:`polymorphically`, meaning that a single query can
return objects of multiple types.

.. seealso::

    :ref:`examples_inheritance` - complete exampes of joined, single and
    concrete inheritance

.. _joined_inheritance:

Joined Table Inheritance
------------------------

In joined table inheritance, each class along a hierarchy of classes
is represented by a distinct table.  Querying for a particular subclass
in the hierarchy will render as a SQL JOIN along all tables in its
inheritance path. If the queried class is the base class, the **default behavior
is to include only the base table** in a SELECT statement.   In all cases, the
ultimate class to instantiate for a given row is determined by a discriminator
column or an expression that works against the base table.    When a subclass
is loaded **only** against a base table, resulting objects will have base attributes
populated at first; attributes that are local to the subclass will :term:`lazy load`
when they are accessed.    Alternatively, there are options which can change
the default behavior, allowing the query to include columns corresponding to
multiple tables/subclasses up front.

The base class in a joined inheritance hierarchy is configured with
additional arguments that will refer to the polymorphic discriminator
column as well as the identifier for the base class::

    class Employee(Base):
        __tablename__ = 'employee'
        id = Column(Integer, primary_key=True)
        name = Column(String(50))
        type = Column(String(50))

        __mapper_args__ = {
            'polymorphic_identity':'employee',
            'polymorphic_on':type
        }

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.

While a polymorphic discriminator expression is not strictly necessary, it is
required if polymorphic loading is desired.   Establishing a simple column on
the base table is the easiest way to achieve this, however very sophisticated
inheritance mappings may even configure a SQL expression such as a CASE
statement as the polymorphic discriminator.

.. note::
{'fraction_non_alphanumeric': 0.06215780998389694, 'fraction_numerical': 0.0012882447665056361, 'mean_word_length': 4.322193658954585, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4013331', 'n_tokens_mistral': 1493, 'n_tokens_neox': 1385, 'n_words': 819}