Many to Many
============

The many to many relationship is used when a parent model can have many
children but the child can also have many parents. For example, an employee
could be working on multiple projects and multiple employees are generally
assigned to a project.

.. seealso::

    :ref:`many-to-many`
      OpenAlchemy documentation for many to many relationships.

    `SQLAlchemy Many to Many <https://docs.sqlalchemy.org/en/13/orm/basic_relationships.html#many-to-many>`_
      SQLAlchemy documentation for many to many relationships.

The following example defines a many to many relationship between
:samp:`Employee` and :samp:`Project`:

.. literalinclude:: ../../../../examples/relationship/many_to_many/example-spec.yml
    :language: yaml
    :linenos:

The following file uses OpenAlchemy to generate the SQLAlchemy models:

.. literalinclude:: ../../../../examples/relationship/many_to_many/models.py
    :language: python
    :linenos:

The SQLAlchemy models generated by OpenAlchemy are equivalent to the following
traditional models file:

.. literalinclude:: ../../../../examples/relationship/many_to_many/models_traditional.py
    :language: python
    :linenos:

OpenAlchemy will generate the following typed models:

.. literalinclude:: ../../../../examples/relationship/many_to_many/models_auto.py
    :language: python
    :linenos:

Custom Association Schema
-------------------------

OpenAlchemy also supports customization of the association schema that
implements the many-to-many relationship. This means that the schema can be
changed to include, for example, a column tracking when the association was
established.

.. seealso::

    :ref:`custom-association`
      OpenAlchemy documentation for many to many relationships with a custom
      association schema.

The following example defines a schema for the association:

.. literalinclude:: ../../../../examples/relationship/many_to_many/pre-defined-example-spec.yml
    :language: yaml
    :linenos:

The following file uses OpenAlchemy to generate the SQLAlchemy models:

.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models.py
    :language: python
    :linenos:

The SQLAlchemy models generated by OpenAlchemy are equivalent to the following
traditional models file:

.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models_traditional.py
    :language: python
    :linenos:

OpenAlchemy will generate the following typed models:

.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models_auto.py
    :language: python
    :linenos: