Has many

The HasMany relationship class manages the has many relationship between two models.

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, hasMany, HasMany } from '@ioc:Adonis/Lucid/Orm'
import Post from 'App/Models/Post'

class User extends BaseModel {
  @hasMany(() => Post)
  public posts: HasMany<typeof Post>
}

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

Methods/Properties

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

type

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

class User extends BaseModel {
  @hasMany(() => Post)
  public posts: HasMany<typeof Post>
}

User.$getRelation('posts').type // 'hasMany'

relationName

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

class User extends BaseModel {
  @hasMany(() => Post)
  public posts: HasMany<typeof Post>
}

User.$getRelation('posts').relationName // 'posts'

serializeAs

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

class User extends BaseModel {
  @hasMany(() => Post, {
    serializeAs: 'articles'
  })
  public posts: HasMany<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 User extends BaseModel {
  @hasMany(() => Post)
  public posts: HasMany<typeof Post>
}

User.$getRelation('posts').model // User

relatedModel

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

class User extends BaseModel {
  @hasMany(() => Post)
  public posts: HasMany<typeof Post>
}

User.$getRelation('posts').relatedModel() // Post

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 User extends BaseModel {
  @column()
  public id: number

  @hasMany(() => Post, {
    localKey: 'id', // id column on "User" model
  })
  public posts: HasMany<typeof Post>
}

foreignKey

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

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

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

  @hasMany(() => Post, {
    foreignKey: 'userId', // userId column on "Post" model
  })
  public posts: HasMany<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 User extends BaseModel {
  @column()
  public id: number

  @hasMany(() => Post, {
    onQuery(query) {
      query.where('isPublished', true)
    }
  })
  public posts: HasMany<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 User extends BaseModel {
  @column()
  public id: number

  @hasMany(() => Post, {
    onQuery(query) {
      if (!query.isRelatedSubQuery) {
        query.preload('comments')
      }
    }
  })
  public posts: HasMany<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 user = new User()
const post = new Post()

User.$getRelation('posts').setRelated(user, [post])

pushRelated

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

const user = new User()

User.$getRelation('posts').pushRelated(user, new Post())
User.$getRelation('posts').pushRelated(user, new Post())
User.$getRelation('posts').pushRelated(user, new Post())

user.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 users = [
  User {
    id: 1,
  },
  User {
    id: 2,
  },
  User {
    id: 3,
  }
]

const posts = [
  Post {
    id: 1,
    user_id: 1,
  },
  Post {
    id: 2,
    user_id: 1,
  },
  Post {
    id: 3,
    user_id: 2,
  },
  Post {
    id: 4,
    user_id: 3,
  }
]

User.$getRelation('posts').setRelatedForMany(users, posts)

client

Returns the reference to the HasManyQueryClient . The query client exposes the API to persist/fetch related rows from the database.

hydrateForPersistance

Hydrates the values for persistence by defining the foreignKey value. The method accepts the parent model as the first argument and an object or the related model instance as the second argument.

const user = new User()
user.id = 1

const post = new Post()
User.$getRelation('posts').hydrateForPersistance(user, post)

console.log(post.userId === user.id) // true

eagerQuery

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

subQuery

Returns an instance of the HasManySubQueryBuilder . 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 persist/fetch related rows from the database. You can access the query client for a relationship using the related method.

const user = await User.find(1)

user.related('posts') // HasManyClientContract

create

Please create a new relationship model instance and persist it to the database right away.

const post = await user
  .related('posts')
  .create({
    title: 'Adonis 101'
  })

The create method inherits the transaction client, or the connection name defined on the parent model instance. For example:

const trx = await Database.transaction()
const user = await User.query({ client: trx }).first()

/**
* Uses the `$trx` property from the `user` instance to
* persist relationship
*/
await user.related('posts').create()

await trx.commit()

createMany

Create multiple instances of a relationship model and persist them to the database. The method accepts an array of objects to persist.

One insert query is issued for each model instance to ensure that we execute the lifecycle hooks for every individual instance.
All the insert queries are internally wrapped inside a transaction. In case of an error, we will roll everything back.

await user.related('posts').createMany([
  {
    title: 'Adonis 101',
  },
  {
    title: 'Lucid 101'
  }
])

save

The save method persists an existing instance of the relationship.

Like the create method, the save method also uses the transaction client/connection name from the parent model.

const post = new Post()
post.title = 'Adonis 101'

const post = await user
  .related('post')
  .save(post)

saveMany

The saveMany method persists an array of related model instances to the database.

One insert query is issued for each model instance to ensure that we execute the lifecycle hooks for every individual instance.
All the insert queries are internally wrapped inside a transaction. In case of an error, we will roll everything back.

const post = new Post()
post.title = 'Adonis 101'

const post1 = new Post()
post1.title = 'Lucid 101'

const post2 = new Post()
post2.title = 'Validator 101'

const post = await user
  .related('post')
  .saveMany([post, post1, post2])

firstOrCreate

The firstOrCreate method works similar to the static firstOrCreate method on the base model. However, we implicitly adds the foreignKey and its value to the search payload.

await user
  .related('posts')
  .firstOrCreate({}, {
    title: 'Adonis 101',
  })

updateOrCreate

The updateOrCreate method works similar to the static updateOrCreate method on the base model. However, we implicitly adds the foreignKey and its value to the search payload.

await user
  .related('posts')
  .updateOrCreate({}, {
    title: 'Adonis 101',
  })

fetchOrCreateMany

The fetchOrCreateMany method works similar to the static fetchOrCreateMany method on the base model. However, we implicitly add the foreignKey as the lookup key for finding unique rows.

In the following example, only the posts with a unique slug for a given user will be created.

const posts = [
  {
    title: 'Adonis 101',
    slug: 'adonis-101',
  },
  {
    title: 'Lucid 101',
    slug: 'lucid-101',
  }
]

await user
  .related('posts')
  .fetchOrCreateMany(posts, 'slug')

updateOrCreateMany

The updateOrCreateMany method works similar to the static updateOrCreateMany method on the base model. However, we implicitly add the foreignKey as the lookup key for finding unique rows.

In the following example, only the posts with a unique slug for a given user will be created.

const posts = [
  {
    title: 'Adonis 101',
    slug: 'adonis-101',
  },
  {
    title: 'Lucid 101',
    slug: 'lucid-101',
  }
]

await user
  .related('posts')
  .updateOrCreateMany(posts, 'slug')

query

Returns an instance of the HasManyQueryBuilder .

Query Builder

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

You can access the relationship query builder as follows:

const user = await User.find(1)

user.related('posts').query() // HasManyQueryBuilder

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 User.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.

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

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