Eager Loading

Eager loading; while getting one thing, also get three other things. For example; you can get an index of customers with all user data included.

Should not be used in conjuction with Partial Data (show)

To show it in action you can test it out by using the following query parameter with=user:

Response:

{
    "data": [
        {
            "id": 24,
            "user_id": 5,
            "name": "Lowe, Farrell and Leuschke",
            ...omitted all other fields
            "user": {
                "id": 5,
                "name": "Tierra Osinski",
                "email": "4@cirqll.nl",
                ...omitted all other fields
            }
        },
        {
            ...omitted all fields
        }
    ],
    "limit": 100,
    "total": 2,
    "offset": 0
}

Nested Selectors

If you want to get all customers with their user, but also their contacts also with the user, you can.

Response:

{
    "data": [
        {
            "id": 24,
            "user_id": 5,
            "name": "Lowe, Farrell and Leuschke",
            ...omitted all other fields
            "user": {
                "id": 5,
                "name": "Tierra Osinski",
                "email": "4@cirqll.nl",
                ...omitted all other fields
            },
            "contacts": {
                "data": [
                    {
                        "id": 302,
                        "user_id": 2,
                        "customer_id": 93,
                        "first_name": "bean",
                        "last_name": "burh",
                        ...omitted all other fields
                        "user": {
                            "id": 2,
                            "name": "Matteo Kertzmann",
                            "email": "1@cirqll.nl",
                            ...omitted all other fields
                        }
                    },
                    {
                        ...omitted all fields
                    }
                ],
                "limit": 50,
                "total": 2,
                "offset": 0
            }
        },
        {
            ...omitted all fields
        }
    ],
    "limit": 100,
    "total": 2,
    "offset": 0
}

Limitations

Due to the exponential increase of data when loading many-to-many relations, there are some thresholds that stop you from loading too much data. Some examples of what is and what isn't allowed are as follows (using /api/customer):

with	allowed	reason
user	✅	one-to-one relationship
user.company	✅	one-to-one-to-one relationship
user.company.address	✅	one-to-one-to-one-to-one relationship
user.company.address.company	✅	one-to-one-to-one-to-one relationship
user.customers	❌	one-to-one-to-many relationship
contacts	✅	many-to-many relationship
contacts.user	✅	many-to-many-to-one relationship
contacts.user.company	✅	many-to-many-to-one relationship
contacts.notes	❌	many-to-many-to-many relationship

Weight System

A one to one relationship costs 1 point. A many-to-many costs 3 points. A nested relationship will cost depth * points. You have a maximum threshold of 16 (this number might change in the future). The "X-Eager-Loading-Weight" header will appear in the response with your calculated weight.

Some examples which have a weight of 16:

Many-to-Many Exceptions

There are some many-to-many relationships which will not appear within a Pagination Schema and they also only cost 1 point. These exceptions are:

permissions in roles

field_values

in customers, contacts, appointments, tasks, chances, assignments and contracts

options in fields

What can you Eager Load?

In every resource you can find a list of relations which may be eager loaded. And it is commonly safe to assume that foreign keys signify an eager load option. If you see a user_id it means you can eager load the user.

Nested Selectors#

Limitations#

Weight System#

Many-to-Many Exceptions#

What can you Eager Load?#

Nested Selectors

Limitations

Weight System

Many-to-Many Exceptions

What can you Eager Load?