Has one

The HasOne relationship class manages the has one 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, hasOne, HasOne } from '@ioc:Adonis/Lucid/Orm'
import Profile from 'App/Models/Profile'

class User extends BaseModel {
  @hasOne(() => Profile)
  public profile: HasOne<typeof Profile>
}

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

Methods/Properties

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

type

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

class User extends BaseModel {
  @hasOne(() => Profile)
  public profile: HasOne<typeof Profile>
}

User.$getRelation('profile').type // 'hasOne'

relationName

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

class User extends BaseModel {
  @hasOne(() => Profile)
  public profile: HasOne<typeof Profile>
}

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

serializeAs

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

class User extends BaseModel {
  @hasOne(() => Profile, {
    serializeAs: 'userProfile'
  })
  public profile: HasOne<typeof Profile>
}

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 {
  @hasOne(() => Profile)
  public profile: HasOne<typeof Profile>
}

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

relatedModel

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

class User extends BaseModel {
  @hasOne(() => Profile)
  public profile: HasOne<typeof Profile>
}

User.$getRelation('profile').relatedModel() // Profile

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

  @hasOne(() => Profile, {
    localKey: 'id', // id column on "User" model
  })
  public profile: HasOne<typeof Profile>
}

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 {
  @hasOne(() => Profile, {
    foreignKey: 'userId', // userId column on "Profile" model
  })
  public profile: HasOne<typeof Profile>
}

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

  @hasOne(() => Profile, {
    onQuery(query) {
      query.where('visibility', 'public')
    }
  })
  public profile: HasOne<typeof Profile>
}

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

  @hasOne(() => Profile, {
    onQuery(query) {
      if (!query.isRelatedSubQuery) {
        query.preload('socialAccounts')
      }
    }
  })
  public profile: HasOne<typeof Profile>
}

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 profile = new Profile()

User.$getRelation('profile').setRelated(user, profile)

pushRelated

The pushRelated method pushes the relationship to the existing relationship value array. However, for hasOne, 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 profiles = [
  Profile {
    user_id: 1,
  },
  Profile {
    user_id: 2,
  },
  Profile {
    user_id: 3,
  }
]

User.$getRelation('profile').setRelatedForMany(users, profiles)

client

Returns the reference to the HasOneQueryClient . 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 profile = new Profile()
User.$getRelation('profile').hydrateForPersistance(user, profile)

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

eagerQuery

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

subQuery

Returns an instance of the HasOneSubQueryBuilder . 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('profile') // HasOneClientContract

create

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

const profile = await user
  .related('profile')
  .create({
    email: 'virk@adonisjs.com',
    avatarUrl: 'profile.jpg',
  })

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('profile').create()

await trx.commit()

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 profile = new Profile()
profile.email = 'virk@adonisjs.com'
profile.avatarUrl = 'foo.jpg'

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

firstOrCreate

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

You can also use this method to ensure that the user always has a single profile.

await user
  .related('profile')
  .firstOrCreate({}, {
    email: 'virk@adonisjs.com',
    avatarUrl: 'profile.jpg',
  })

updateOrCreate

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

await user
  .related('profile')
  .updateOrCreate({}, {
    email: 'virk@adonisjs.com',
    avatarUrl: 'profile.jpg',
  })

query

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