#

API Docs for: v3.8.1
Show: Inherited Protected Private Deprecated

# DS.BelongsToReference Class

Extends DS.Reference
Defined in: `addon/-private/system/references/belongs-to.js:7`
Module: ember-data

A BelongsToReference is a low-level API that allows users and addon author to perform meta-operations on a belongs-to relationship.

- Index
- Methods

## Item Index

### Methods

- id
- link
- load
- meta
- push
- reload
- remoteType
- value

## Methods

### `id`

() String

Defined in `addon/-private/system/references/belongs-to.js:28`

The `id` of the record that this reference refers to. Together, the `type()` and `id()` methods form a composite key for the identity map. This can be used to access the id of an async relationship without triggering a fetch that would normally happen if you attempted to use `record.get('relationship.id')`.

Example

    // models/blog.js
    export default DS.Model.extend({
       user: DS.belongsTo({ async: true })
     });

    let blog = store.push({
       data: {
         type: 'blog',
         id: 1,
         relationships: {
           user: {
             data: { type: 'user', id: 1 }
           }
         }
       }
     });
    let userRef = blog.belongsTo('user');

    // get the identifier of the reference
    if (userRef.remoteType() === "id") {
       let id = userRef.id();
     }

#### Returns:

String:

The id of the record in this belongsTo relationship.

### `link`

() String

Inherited from DS.Reference: `addon/-private/system/references/reference.ts:88`

The link Ember Data will use to fetch or reload this belongs-to relationship. Example ```javascript // models/blog.js export default DS.Model.extend({ user: DS.belongsTo({ async: true }) }); let blog = store.push({ data: { type: 'blog', id: 1, relationships: { user: { links: { related: '/articles/1/author' } } } } }); let userRef = blog.belongsTo('user'); // get the identifier of the reference if (userRef.remoteType() === "link") { let link = userRef.link(); } ```

#### Returns:

String: The link Ember Data will use to fetch or reload this belongs-to relationship.

### `load`

(

- `options`

)
Promise

Defined in `addon/-private/system/references/belongs-to.js:207`

Loads a record in a belongs to relationship if it is not already loaded. If the relationship is already loaded this method does not trigger a new load.

Example

    // models/blog.js
    export default DS.Model.extend({
       user: DS.belongsTo({ async: true })
     });

    let blog = store.push({
       data: {
         type: 'blog',
         id: 1,
         relationships: {
           user: {
             data: { type: 'user', id: 1 }
           }
         }
       }
     });
    let userRef = blog.belongsTo('user');

    userRef.value(); // null

    userRef.load().then(function(user) {
       userRef.value() === user
     });

You may also pass in an options object whose properties will be fed forward. This enables you to pass `adapterOptions` into the request given to the adapter via the reference.

Example

    userRef.load({ adapterOptions: { isPrivate: true } }).then(function(user) {
      userRef.value() === user;
    });

    export default ApplicationAdapter.extend({
      findRecord(store, type, id, snapshot) {
        // In the adapter you will have access to adapterOptions.
        let adapterOptions = snapshot.adapterOptions;
      }
    });

#### Parameters:

- `options` Object

  the options to pass in.

#### Returns:

Promise:

a promise that resolves with the record in this belongs-to relationship.

### `meta`

() Object

Inherited from DS.Reference: `addon/-private/system/references/reference.ts:136`

The meta data for the belongs-to relationship. Example ```javascript // models/blog.js export default DS.Model.extend({ user: DS.belongsTo({ async: true }) }); let blog = store.push({ data: { type: 'blog', id: 1, relationships: { user: { links: { related: { href: '/articles/1/author', meta: { lastUpdated: 1458014400000 } } } } } } }); let userRef = blog.belongsTo('user'); userRef.meta() // { lastUpdated: 1458014400000 } ```

#### Returns:

Object: The meta information for the belongs-to relationship.

### `push`

(

- `objectOrPromise`

)
Promise

Defined in `addon/-private/system/references/belongs-to.js:78`

`push` can be used to update the data in the relationship and Ember Data will treat the new data as the conanical value of this relationship on the backend.

Example

    // models/blog.js
    export default DS.Model.extend({
       user: DS.belongsTo({ async: true })
     });

    let blog = store.push({
       data: {
         type: 'blog',
         id: 1,
         relationships: {
           user: {
             data: { type: 'user', id: 1 }
           }
         }
       }
     });
    let userRef = blog.belongsTo('user');

    // provide data for reference
    userRef.push({
       data: {
         type: 'user',
         id: 1,
         attributes: {
           username: "@user"
         }
       }
     }).then(function(user) {
       userRef.value() === user;
     });

#### Parameters:

- `objectOrPromise` Object | Promise

  a promise that resolves to a JSONAPI document object describing the new value of this relationship.

#### Returns:

Promise:

A promise that resolves with the new value in this belongs-to relationship.

### `reload`

(

- `options`

)
Promise

Defined in `addon/-private/system/references/belongs-to.js:269`

Triggers a reload of the value in this relationship. If the remoteType is `"link"` Ember Data will use the relationship link to reload the relationship. Otherwise it will reload the record by its id.

Example

    // models/blog.js
    export default DS.Model.extend({
       user: DS.belongsTo({ async: true })
     });

    let blog = store.push({
       data: {
         type: 'blog',
         id: 1,
         relationships: {
           user: {
             data: { type: 'user', id: 1 }
           }
         }
       }
     });
    let userRef = blog.belongsTo('user');

    userRef.reload().then(function(user) {
       userRef.value() === user
     });

You may also pass in an options object whose properties will be fed forward. This enables you to pass `adapterOptions` into the request given to the adapter via the reference. A full example can be found in the `load` method.

Example

    userRef.reload({ adapterOptions: { isPrivate: true } })

#### Parameters:

- `options` Object

  the options to pass in.

#### Returns:

Promise:

a promise that resolves with the record in this belongs-to relationship after the reload has completed.

### `remoteType`

() String

Inherited from DS.Reference: `addon/-private/system/references/reference.ts:41`

This returns a string that represents how the reference will be looked up when it is loaded. If the relationship has a link it will use the "link" otherwise it defaults to "id". Example ```app/models/post.js export default DS.Model.extend({ comments: DS.hasMany({ async: true }) }); ``` ```javascript let post = store.push({ data: { type: 'post', id: 1, relationships: { comments: { data: [{ type: 'comment', id: 1 }] } } } }); let commentsRef = post.hasMany('comments'); // get the identifier of the reference if (commentsRef.remoteType() === "ids") { let ids = commentsRef.ids(); } else if (commentsRef.remoteType() === "link") { let link = commentsRef.link(); } ```

#### Returns:

String: The name of the remote type. This should either be "link" or "ids"

### `value`

() DS.Model

Defined in `addon/-private/system/references/belongs-to.js:147`

`value()` synchronously returns the current value of the belongs-to relationship. Unlike `record.get('relationshipName')`, calling `value()` on a reference does not trigger a fetch if the async relationship is not yet loaded. If the relationship is not loaded it will always return `null`.

Example

    // models/blog.js
    export default DS.Model.extend({
       user: DS.belongsTo({ async: true })
     });

    let blog = store.push({
       data: {
         type: 'blog',
         id: 1,
         relationships: {
           user: {
             data: { type: 'user', id: 1 }
           }
         }
       }
     });
    let userRef = blog.belongsTo('user');

    userRef.value(); // null

    // provide data for reference
    userRef.push({
       data: {
         type: 'user',
         id: 1,
         attributes: {
           username: "@user"
         }
       }
     }).then(function(user) {
       userRef.value(); // user
     });

#### Returns:

DS.Model:

the record in this relationship