Has many through

The HasManyThrough relationship class manages you to define a has many relationship via an intermediate model. A great example of this is, "a country has many posts via users".

You will not find yourself directly working with this class. However, an instance of the class can be accessed using the Model.$getRelation method.

import {
  BaseModel,
  hasManyThrough,
  HasManyThrough,
} from '@ioc:Adonis/Lucid/Orm'

import Post from 'App/Models/Post'
import User from 'App/Models/User'

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}
Copy

Country.$getRelation('posts').relationName
Country.$getRelation('posts').type
Country.$getRelation('posts').relatedModel()
Copy

Methods/Properties#

Following is the list of methods and properties available on the HasManyThrough relationship.

type#

The type of the relationship. The value is always set to hasManyThrough.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}

Country.$getRelation('posts').type // 'hasManyThrough'
Copy

relationName#

The relationship name. It is a property name defined on the parent model.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}

Country.$getRelation('posts').relationName // 'posts'
Copy

serializeAs#

The name to be used for serializing the relationship. You can define it using the decorator options.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    serializeAs: 'articles'
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

booted#

Find if the relationship has been booted. If not, call the boot method.

boot#

Boot the relationship. Lucid models public APIs call this method internally, and you never have to boot the relationship manually.

model#

Reference to the parent model (the one that defines the relationship).

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}

Country.$getRelation('posts').model // Country
Copy

relatedModel#

Reference to the relationship model. The property value is a function that returns the related model.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}

Country.$getRelation('posts').relatedModel() // Post
Copy

throughModel#

Reference to the throughModel. The property value is a function that returns the throughModel.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User])
  public posts: HasManyThrough<typeof Post>
}

Country.$getRelation('posts').throughModel() // User
Copy

localKey#

The localKey for the relationship. You must read the NamingStrategy doc to learn more about how the key name is computed.

You can also define the localKey explicitly. Do make sure you mention the model property name and NOT the database column name.

class Country extends BaseModel {
  @column()
  public id: number

  @hasManyThrough([() => Post, () => User], {
    localKey: 'id', // id column on the "Country" model
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

foreignKey#

The foreignKey for the relationship. The foreign key is the reference on the through model and not the related model.

You can also define the foreignKey explicitly. Do make sure you mention the model property name and NOT the database column name.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    foreignKey: 'countryId', // countryId column on the "User" model
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

throughLocalKey#

The throughLocalKey for the relationship. It is usually the primary key on the through model.

You can also define the throughLocalKey explicitly. Do make sure you mention the model property name and NOT the database column name.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    throughLocalKey: 'id', // id column on the "User" model
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

throughForeignKey#

The throughForeignKey for the relationship. It is the foreign key between the through and the related model.

You can also define the throughForeignKey explicitly. Do make sure you mention the model property name and NOT the database column name.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    throughForeignKey: 'userId', // userId column on the "Post" model
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

onQuery#

The onQuery method is an optional hook to modify the relationship queries. You can define it at the time of declaring the relation.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    onQuery(query) {
      query.where('isPublished', true)
    }
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

If you want to preload a nested relationship using the onQuery hook, then make sure to put it inside the !query.isRelatedSubQuery conditional because sub-queries are NOT executed directly, they are used inside other queries.

class Country extends BaseModel {
  @hasManyThrough([() => Post, () => User], {
    onQuery(query) {
      if (!query.isRelatedSubQuery) {
        query.preload('comments')
      }
    }
  })
  public posts: HasManyThrough<typeof Post>
}
Copy

setRelated#

Set a relationship on the parent model instance. The methods accept the parent model as the first argument and the related model instance as the second argument.

You must ensure that both the model instances are related to each other before calling this method.

const country = new Country()
const post = new Post()

Country.$getRelation('posts').setRelated(country, [post])
Copy

pushRelated#

The pushRelated method pushes the relationship to the existing relationship value array.

const country = new Country()

Country.$getRelation('posts').pushRelated(country, new Post())
Country.$getRelation('posts').pushRelated(country, new Post())
Country.$getRelation('posts').pushRelated(country, new Post())

country.posts.length // 3
Copy

setRelatedForMany#

Set the relationships on more than one parent model. The method accepts an array of the parent models as the first argument and an array of related models as the second argument.

Lucid internally calls this with the results of the preloader.

const countries = [
  Country {
    id: 1,
  },
  Country {
    id: 2,
  },
  Country {
    id: 3,
  }
]

const posts = [
  Post {
    id: 1,
    $extras: {
      through_country_id: 1,
    }
  },
  Post {
    id: 2,
    $extras: {
      through_country_id: 1,
    }
  },
  Post {
    id: 3,
    $extras: {
      through_country_id: 2,
    }
  },
  Post {
    id: 4,
    $extras: {
      through_country_id: 3,
    }
  }
]

Country.$getRelation('posts').setRelatedForMany(countries, posts)
Copy

client#

Returns the reference to the HasManyThroughQueryClient . The query client exposes the API to fetch related rows from the database.

eagerQuery#

Returns an instance of the HasManyThroughQueryBuilder . The query builder has the same API as the Model query builder

subQuery#

Returns an instance of the HasManyThroughSubQueryBuilder . The sub queries are not meant to be executed and mainly used by the withCount and whereHas methods.

Query client#

The query client exposes the API to fetch related rows from the database. You can access the query client for a relationship using the related method.

You cannot persist a hasManyThrough relationships directly and instead use the closest relationship for persistence. For example: Use the posts relationship on the User model to create related posts.

const country = await Country.find(1)
country.related('posts') // HasManyThroughClientContract
Copy

Using the query client, you can access the query builder instance for making related queries.

Query Builder#

The HasManyThroughQueryBuilder has the following additional methods on top of a standard model query builder.

You can access the relationship query builder as follows:

const country = await Country.find(1)

country.related('posts').query() // HasManyThroughQueryBuilder
Copy

groupLimit#

The groupLimit method uses SQL window functions to add a limit to each group during relationship preloading. Please read the preloading guide to learn why and when you need the groupLimit method.

await Country.query().preload('posts', (query) => {
  query.groupLimit(10)
})
Copy

groupOrderBy#

Add an order by clause to the group limit query. The method has the same API as the orderBy method on the standard query builder.

You only need to apply groupOrderBy when using the groupLimit method.

await Country.query().preload('posts', (query) => {
  query
    .groupLimit(10)
    .groupOrderBy('posts.created_at', 'desc')
})
Copy