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>
}

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

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'

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'

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>
}

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

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

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

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>
}

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>
}

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>
}

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>
}

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>
}

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>
}

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])

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

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)

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.

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

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

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)
})

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.

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