Belongs to

The BelongsTo relationship class manages the belongs to the 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, belongsTo, BelongsTo } from '@ioc:Adonis/Lucid/Orm'
import User from 'App/Models/User'

class Post extends BaseModel {
  @belongsTo(() => User)
  public author: BelongsTo<typeof User>
}

Post.$getRelation('author').relationName
Post.$getRelation('author').type
Post.$getRelation('author').relatedModel()

Methods/Properties

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

type

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

class Post extends BaseModel {
  @belongsTo(() => User)
  public author: BelongsTo<typeof User>
}

Post.$getRelation('author').type // 'belongsTo'

relationName

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

class Post extends BaseModel {
  @belongsTo(() => User)
  public author: BelongsTo<typeof User>
}

Post.$getRelation('author').relationName // 'author'

serializeAs

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

class Post extends BaseModel {
  @belongsTo(() => User, {
    serializeAs: 'user'
  })
  public author: BelongsTo<typeof User>
}

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 Post extends BaseModel {
  @belongsTo(() => User)
  public author: BelongsTo<typeof User>
}

Post.$getRelation('author').model // Post

relatedModel

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

class Post extends BaseModel {
  @belongsTo(() => User)
  public author: BelongsTo<typeof User>
}

Post.$getRelation('author').relatedModel() // 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 Post extends BaseModel {
  @belongsTo(() => User, {
    localKey: 'id', // id column on "User" model
  })
  public author: BelongsTo<typeof User>
}

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

  @belongsTo(() => User, {
    foreignKey: 'userId', // userId column on "Post" model
  })
  public author: BelongsTo<typeof User>
}

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

  @belongsTo(() => User, {
    onQuery(query) {
      query.where('accountStatus', 'active')
    }
  })
  public author: BelongsTo<typeof User>
}

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

  @belongsTo(() => User, {
    onQuery(query) {
      if (!query.isRelatedSubQuery) {
        query.preload('profile')
      }
    }
  })
  public author: BelongsTo<typeof User>
}

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

Post.$getRelation('author').setRelated(user, post)

pushRelated

The pushRelated method pushes the relationship to the existing relationship value array. However, for the belongsTo relationship, the method works similar to setRelated.

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,
    userId: 1,
  },
  Post {
    id: 2,
    userId: 1,
  },
  Post {
    id: 3,
    userId: 3,
  },
  Post {
    id: 4,
    userId: 2,
  },
]

Post.$getRelation('author').setRelatedForMany(posts, users)

client

Returns the reference to the BelongsToQueryClient . 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()
post.title = 'Adonis 101'

Post.$getRelation('author').hydrateForPersistance(post, user)

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

eagerQuery

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

subQuery

Returns an instance of the BelongsToSubQueryBuilder . 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 post = await Post.find(1)

post.related('author') // BelongsToClientContract

associate

Associate the related model with the parent model. For example, associate the user with the post.

const user = await User.find(1)
const post = await Post.find(1)

await post
  .related('author')
  .associate(user)

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

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

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

await trx.commit()

dissociate

The dissociate method removes the relationship by setting the foreign key value to null.

const post = await Post.find(1)
await post.dissociate()

post.userId // null

query

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