<commit_before>
================================
Model from multiple joined table
================================

.. php:class:: Join

Sometimes model logically contains information that is stored in various places
in the database. Your database may want to split up logical information into
tables for various reasons, such as to avoid repetition or to better optimize
indexes.

Join Basics
===========

Agile Data allows you to map multiple table fields into a single business model
by using joins::

    $user->addField('username');
    $j_contact = $user->join('contact');
    $j_contact->addField('address');
    $j_contact->addField('county');
    $j_contact->hasOne('Country');

This code will load data from two tables simultaneously and if you do change any
of those fields they will be update in their respective tables. With SQL the
load query would look like this:

.. code-block:: sql

    select
        u.username, c.address, c.county, c.country_id
        (select name from country where country.id=c.country_id) country
    from user u
    join contact c on c.id=u.contact_id
    where u.id = $id

If driver is unable to query both tables simultaneously, then it will load one
record first, then load other record and will collect fields together::

    $user_data = $user->find($id);
    $contact_data = $contact->find($user_data['contact_id']);

When saving the record, Joins will automatically record data correctly:

.. code-block:: sql

    insert into contact (address, county, country_id) values ($, $, $);
    @join_c = last_insert_id();
    insert into user (username, contact_id) values ($, @join_c)

Strong and Weak joins
---------------------

When you are joining tables, then by default a strong join is used. That means
that both records are mandatory and when adding records, they will both be added
and linked.

Weak join is used if you do not really want to modify the other table.
For example it can be used to pull country information based on user.country_id
but you wouldn't want that adding a new user would create a new country::

    $user->addField('username');
    $user->addField('country_id');
    $j_country = $user->weakJoin('country', ['prefix'=>'country_']);
    $j_country->addField('code');
    $j_country->addField('name');
    $j_country->addField('default_currency', ['prefix'=>false]);

After this you will have the following fields in your model:

- username
- country_id
- country_code [read_only]
- country_name [read_only]
- default_currency [read_only]

.. php:method:: imortModel
<commit_msg>Fix typo in joins.rst (#426)<commit_after>
================================
Model from multiple joined table
================================

.. php:class:: Join

Sometimes model logically contains information that is stored in various places
in the database. Your database may want to split up logical information into
tables for various reasons, such as to avoid repetition or to better optimize
indexes.

Join Basics
===========

Agile Data allows you to map multiple table fields into a single business model
by using joins::

    $user->addField('username');
    $j_contact = $user->join('contact');
    $j_contact->addField('address');
    $j_contact->addField('county');
    $j_contact->hasOne('Country');

This code will load data from two tables simultaneously and if you do change any
of those fields they will be update in their respective tables. With SQL the
load query would look like this:

.. code-block:: sql

    select
        u.username, c.address, c.county, c.country_id
        (select name from country where country.id=c.country_id) country
    from user u
    join contact c on c.id=u.contact_id
    where u.id = $id

If driver is unable to query both tables simultaneously, then it will load one
record first, then load other record and will collect fields together::

    $user_data = $user->find($id);
    $contact_data = $contact->find($user_data['contact_id']);

When saving the record, Joins will automatically record data correctly:

.. code-block:: sql

    insert into contact (address, county, country_id) values ($, $, $);
    @join_c = last_insert_id();
    insert into user (username, contact_id) values ($, @join_c)

Strong and Weak joins
---------------------

When you are joining tables, then by default a strong join is used. That means
that both records are mandatory and when adding records, they will both be added
and linked.

Weak join is used if you do not really want to modify the other table.
For example it can be used to pull country information based on user.country_id
but you wouldn't want that adding a new user would create a new country::

    $user->addField('username');
    $user->addField('country_id');
    $j_country = $user->weakJoin('country', ['prefix'=>'country_']);
    $j_country->addField('code');
    $j_country->addField('name');
    $j_country->addField('default_currency', ['prefix'=>false]);

After this you will have the following fields in your model:

- username
- country_id
- country_code [read_only]
- country_name [read_only]
- default_currency [read_only]

.. php:method:: importModel

{'fraction_non_alphanumeric': 0.12792511700468018, 'fraction_numerical': 0.0005850234009360375, 'mean_word_length': 4.1085657370517925, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 33, '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': '6667410', 'n_tokens_mistral': 1402, 'n_tokens_neox': 1357, 'n_words': 594}