Class Store

adapterFor (modelName) public

Defined in ../store/addon/-private/system/core-store.ts:3271

modelName

String

returns

Adapter

Returns an instance of the adapter for a given type. For example, adapterFor('person') will return an instance of App.PersonAdapter.

If no App.PersonAdapter is found, this method will look for an App.ApplicationAdapter (the default adapter for your entire application).

If no App.ApplicationAdapter is found, it will return the value of the defaultAdapter.

createRecord (modelName, inputProperties) Model

Defined in ../store/addon/-private/system/core-store.ts:563

modelName

String

inputProperties

Object

a hash of properties to set on the newly created record.

returns

Model

record

Create a new record in the current store. The properties passed to this method are set on the newly created record.

To create a new instance of a Post:

store.createRecord('post', {
  title: 'Ember is awesome!'
});

To create a new instance of a Post that has a relationship with a User record:

let user = this.store.peekRecord('user', 1);
store.createRecord('post', {
  title: 'Ember is awesome!',
  user: user
});

deleteRecord (record)

Defined in ../store/addon/-private/system/core-store.ts:659

record

Model

For symmetry, a record can be deleted via the store.

Example

let post = store.createRecord('post', {
  title: 'Ember is awesome!'
});

store.deleteRecord(post);

findAll (modelName, options) Promise

Defined in ../store/addon/-private/system/core-store.ts:2106

Available since v1.13.0

modelName

String

options

Object

returns

Promise

promise

findAll asks the adapter's findAll method to find the records for the given type, and returns a promise which will resolve with all records of this type present in the store, even if the adapter only returns a subset of them.

import Route from '@ember/routing/route';

export default class AuthorsRoute extends Route {
  model(params) {
    return this.store.findAll('author');
  }
}

When the returned promise resolves depends on the reload behavior, configured via the passed options hash and the result of the adapter's shouldReloadAll method.

Reloading

If { reload: true } is passed or adapter.shouldReloadAll evaluates to true, then the returned promise resolves once the adapter returns data, regardless if there are already records in the store:

store.push({
  data: {
    id: 'first',
    type: 'author'
  }
});

// adapter#findAll resolves with
// [
//   {
//     id: 'second',
//     type: 'author'
//   }
// ]
store.findAll('author', { reload: true }).then(function(authors) {
  authors.getEach('id'); // ['first', 'second']
});

If no reload is indicated via the above mentioned ways, then the promise immediately resolves with all the records currently loaded in the store.

Background Reloading

Optionally, if adapter.shouldBackgroundReloadAll evaluates to true, then a background reload is started. Once this resolves, the array with which the promise resolves, is updated automatically so it contains all the records in the store:

import Adapter from '@ember-data/adapter';

export default class ApplicationAdapter extends Adapter {
  shouldReloadAll(store, snapshotsArray) {
    return false;
  },

  shouldBackgroundReloadAll(store, snapshotsArray) {
    return true;
  }
});

// ...

store.push({
  data: {
    id: 'first',
    type: 'author'
  }
});

let allAuthors;
store.findAll('author').then(function(authors) {
  authors.getEach('id'); // ['first']

  allAuthors = authors;
});

// later, once adapter#findAll resolved with
// [
//   {
//     id: 'second',
//     type: 'author'
//   }
// ]

allAuthors.getEach('id'); // ['first', 'second']

If you would like to force or prevent background reloading, you can set a boolean value for backgroundReload in the options object for findAll.

import Route from '@ember/routing/route';

export default class PostEditRoute extends Route {
  model() {
    return this.store.findAll('post', { backgroundReload: false });
  }
}

If you pass an object on the adapterOptions property of the options argument it will be passed to you adapter via the snapshotRecordArray

import Route from '@ember/routing/route';

export default class PostsRoute extends Route {
  model(params) {
    return this.store.findAll('post', {
      adapterOptions: { subscribe: false }
    });
  }
}

import MyCustomAdapter from './custom-adapter';

export default class UserAdapter extends MyCustomAdapter {
  findAll(store, type, sinceToken, snapshotRecordArray) {
    if (snapshotRecordArray.adapterOptions.subscribe) {
      // ...
    }
    // ...
  }
}

See peekAll to get an array of current records in the store, without waiting until a reload is finished.

Retrieving Related Model Records

If you use an adapter such as Ember's default JSONAPIAdapter that supports the JSON API specification and if your server endpoint supports the use of an 'include' query parameter, you can use findAll() to automatically retrieve additional records related to those requested by supplying an include parameter in the options object.

For example, given a post model that has a hasMany relationship with a comment model, when we retrieve all of the post records we can have the server also return all of the posts' comments in the same request:

import Route from '@ember/routing/route';

export default class PostsRoute extends Route {
  model() {
    return this.store.findAll('post', { include: 'comments' });
  }
}

Multiple relationships can be requested using an include parameter consisting of a comma-separated list (without white-space) while nested relationships can be specified using a dot-separated sequence of relationship names. So to request both the posts' comments and the authors of those comments the request would look like this:

import Route from '@ember/routing/route';

export default class PostsRoute extends Route {
  model() {
    return this.store.findAll('post', { include: 'comments,comments.author' });
  }
}

See query to only get a subset of records from the server.

findRecord (modelName, id, options, preload) Promise

Defined in ../store/addon/-private/system/core-store.ts:768

Available since v1.13.0

modelName

String

id

(String|Integer)

options

Object

preload

Object

- optional set of attributes and relationships passed in either as IDs or as actual models

returns

Promise

promise

This method returns a record for a given type and id combination.

The findRecord method will always resolve its promise with the same object for a given type and id.

The findRecord method will always return a promise that will be resolved with the record.

Example

import Route from '@ember/routing/route';

export default class PostRoute extends Route {
  model(params) {
    return this.store.findRecord('post', params.post_id);
  }
}

If the record is not yet available, the store will ask the adapter's find method to find the necessary data. If the record is already present in the store, it depends on the reload behavior when the returned promise resolves.

Preloading

You can optionally preload specific attributes and relationships that you know of by passing them via the passed options.

For example, if your Ember route looks like /posts/1/comments/2 and your API route for the comment also looks like /posts/1/comments/2 if you want to fetch the comment without fetching the post you can pass in the post to the findRecord call:

store.findRecord('comment', 2, { preload: { post: 1 } });

If you have access to the post model you can also pass the model itself:

store.findRecord('post', 1).then(function (myPostModel) {
  store.findRecord('comment', 2, { post: myPostModel });
});

Reloading

The reload behavior is configured either via the passed options hash or the result of the adapter's shouldReloadRecord.

If { reload: true } is passed or adapter.shouldReloadRecord evaluates to true, then the returned promise resolves once the adapter returns data, regardless if the requested record is already in the store:

store.push({
  data: {
    id: 1,
    type: 'post',
    revision: 1
  }
});

// adapter#findRecord resolves with
// [
//   {
//     id: 1,
//     type: 'post',
//     revision: 2
//   }
// ]
store.findRecord('post', 1, { reload: true }).then(function(post) {
  post.get('revision'); // 2
});

If no reload is indicated via the above mentioned ways, then the promise immediately resolves with the cached version in the store.

Background Reloading

Optionally, if adapter.shouldBackgroundReloadRecord evaluates to true, then a background reload is started, which updates the records' data, once it is available:

// app/adapters/post.js
import ApplicationAdapter from "./application";

export default class PostAdapter extends ApplicationAdapter {
  shouldReloadRecord(store, snapshot) {
    return false;
  },

  shouldBackgroundReloadRecord(store, snapshot) {
    return true;
  }
});

// ...

store.push({
  data: {
    id: 1,
    type: 'post',
    revision: 1
  }
});

let blogPost = store.findRecord('post', 1).then(function(post) {
  post.get('revision'); // 1
});

// later, once adapter#findRecord resolved with
// [
//   {
//     id: 1,
//     type: 'post',
//     revision: 2
//   }
// ]

blogPost.get('revision'); // 2

If you would like to force or prevent background reloading, you can set a boolean value for backgroundReload in the options object for findRecord.

import Route from '@ember/routing/route';

export default class PostEditRoute extends Route {
  model(params) {
    return this.store.findRecord('post', params.post_id, { backgroundReload: false });
  }
}

If you pass an object on the adapterOptions property of the options argument it will be passed to your adapter via the snapshot

import Route from '@ember/routing/route';

export default class PostEditRoute extends Route {
  model(params) {
    return this.store.findRecord('post', params.post_id, {
      adapterOptions: { subscribe: false }
    });
  }
}

import MyCustomAdapter from './custom-adapter';

export default class PostAdapter extends MyCustomAdapter {
  findRecord(store, type, id, snapshot) {
    if (snapshot.adapterOptions.subscribe) {
      // ...
    }
    // ...
  }
}

See peekRecord to get the cached version of a record.

Retrieving Related Model Records

If you use an adapter such as Ember's default JSONAPIAdapter that supports the JSON API specification and if your server endpoint supports the use of an 'include' query parameter, you can use findRecord() or findAll() to automatically retrieve additional records related to the one you request by supplying an include parameter in the options object.

For example, given a post model that has a hasMany relationship with a comment model, when we retrieve a specific post we can have the server also return that post's comments in the same request:

import Route from '@ember/routing/route';

export default class PostRoute extends Route {
  model(params) {
    return this.store.findRecord('post', params.post_id, { include: 'comments' });
  }
}

In this case, the post's comments would then be available in your template as model.comments.

Multiple relationships can be requested using an include parameter consisting of a comma-separated list (without white-space) while nested relationships can be specified using a dot-separated sequence of relationship names. So to request both the post's comments and the authors of those comments the request would look like this:

import Route from '@ember/routing/route';

export default class PostRoute extends Route {
  model(params) {
    return this.store.findRecord('post', params.post_id, { include: 'comments,comments.author' });
  }
}

Retrieving Specific Fields by Type

If your server endpoint supports the use of a 'fields' query parameter, you can use pass those fields through to your server. At this point in time, this requires a few manual steps on your part.

1. Implement buildQuery in your adapter.

buildQuery(snapshot) {
  let query = this._super(...arguments);

  let { fields } = snapshot.adapterOptions;

  if (fields) {
    query.fields = fields;
  }

  return query;
}

2. Then pass through the applicable fields to your findRecord request.

Given a post model with attributes body, title, publishDate and meta, you can retrieve a filtered list of attributes.

import Route from '@ember/routing/route';
export default Route.extend({
  model(params) {
    return this.store.findRecord('post', params.post_id, { adapterOptions: { fields: { post: 'body,title' } });
  }
});

Moreover, you can filter attributes on related models as well. If a post has a belongsTo relationship to a user, just include the relationship key and attributes.

import Route from '@ember/routing/route';
export default Route.extend({
  model(params) {
    return this.store.findRecord('post', params.post_id, { adapterOptions: { fields: { post: 'body,title', user: 'name,email' } });
  }
});

getReference (modelName, id) RecordReference

Defined in ../store/addon/-private/system/core-store.ts:1444

Available since v2.5.0

modelName

String

id

String|Integer

returns

RecordReference

Get the reference for the specified record.

Example

let userRef = store.getReference('user', 1);

// check if the user is loaded
let isLoaded = userRef.value() !== null;

// get the record of the reference (null if not yet available)
let user = userRef.value();

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

// load user (via store.find)
userRef.load().then(...)

// or trigger a reload
userRef.reload().then(...)

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

hasRecordForId (modelName, id) Boolean

Defined in ../store/addon/-private/system/core-store.ts:1576

modelName

String

id

(String|Integer)

returns

Boolean

This method returns true if a record for a given modelName and id is already loaded in the store. Use this function to know beforehand if a findRecord() will result in a request or that it will be a cache hit.

Example

store.hasRecordForId('post', 1); // false
store.findRecord('post', 1).then(function() {
  store.hasRecordForId('post', 1); // true
});

modelFor (modelName) Model

Defined in ../store/addon/-private/system/ds-model-store.ts:138

modelName

String

returns

Model

Returns the model class for the particular modelName.

The class of a model might be useful if you want to get a list of all the relationship names of the model, see relationshipNames for example.

normalize (modelName, payload) Object

Defined in ../store/addon/-private/system/core-store.ts:3210

modelName

String

The name of the model type for this payload

payload

Object

returns

Object

The normalized payload

normalize converts a json payload into the normalized form that push expects.

Example

socket.on('message', function(message) {
  let modelName = message.model;
  let data = message.data;
  store.push(store.normalize(modelName, data));
});

peekAll (modelName) RecordArray

Defined in ../store/addon/-private/system/core-store.ts:2367

Available since v1.13.0

modelName

String

returns

RecordArray

This method returns a filtered array that contains all of the known records for a given type in the store.

Note that because it's just a filter, the result will contain any locally created records of the type, however, it will not make a request to the backend to retrieve additional records. If you would like to request all the records from the backend please use store.findAll.

Also note that multiple calls to peekAll for a given type will always return the same RecordArray.

Example

let localPosts = store.peekAll('post');

peekRecord (modelName, id) Model|null

Defined in ../store/addon/-private/system/core-store.ts:1501

Available since v1.13.0

modelName

String

id

String|Integer

returns

Model|null

record

Get a record by a given type and ID without triggering a fetch.

This method will synchronously return the record if it is available in the store, otherwise it will return null. A record is available if it has been fetched earlier, or pushed manually into the store.

See findRecord if you would like to request this record from the backend.

Note: This is a synchronous method and does not return a promise.

let post = store.peekRecord('post', 1);

post.get('id'); // 1

push (data)

Defined in ../store/addon/-private/system/core-store.ts:2718

data

Object

returns

the record(s) that was created or updated.

Push some data for a given type into the store.

This method expects normalized JSON API document. This means you have to follow JSON API specification with few minor adjustments:

• record's type should always be in singular, dasherized form
• members (properties) should be camelCased

Your primary data should be wrapped inside data property:

store.push({
  data: {
    // primary data for single record of type `Person`
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Daniel',
      lastName: 'Kmak'
    }
  }
});

Demo.

data property can also hold an array (of records):

store.push({
  data: [
    // an array of records
    {
      id: '1',
      type: 'person',
      attributes: {
        firstName: 'Daniel',
        lastName: 'Kmak'
      }
    },
    {
      id: '2',
      type: 'person',
      attributes: {
        firstName: 'Tom',
        lastName: 'Dale'
      }
    }
  ]
});

Demo.

There are some typical properties for JSONAPI payload:

• id - mandatory, unique record's key
• type - mandatory string which matches model's dasherized name in singular form
• attributes - object which holds data for record attributes - attr's declared in model
• relationships - object which must contain any of the following properties under each relationships' respective key (example path is relationships.achievements.data):
  • links
  • data - place for primary data
  • meta - object which contains meta-information about relationship

For this model:

import Model, { attr, hasMany } from '@ember-data/model';

export default class PersonRoute extends Route {
  @attr('string') firstName;
  @attr('string') lastName;

  @hasMany('person') children;
}

To represent the children as IDs:

{
  data: {
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Tom',
      lastName: 'Dale'
    },
    relationships: {
      children: {
        data: [
          {
            id: '2',
            type: 'person'
          },
          {
            id: '3',
            type: 'person'
          },
          {
            id: '4',
            type: 'person'
          }
        ]
      }
    }
  }
}

Demo.

To represent the children relationship as a URL:

{
  data: {
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Tom',
      lastName: 'Dale'
    },
    relationships: {
      children: {
        links: {
          related: '/people/1/children'
        }
      }
    }
  }
}

If you're streaming data or implementing an adapter, make sure that you have converted the incoming data into this form. The store's normalize method is a convenience helper for converting a json payload into the form Ember Data expects.

store.push(store.normalize('person', data));

This method can be used both to push in brand new records, as well as to update existing records.

pushPayload (modelName, inputPayload)

Defined in ../store/addon/-private/system/core-store.ts:3002

modelName

String

Optionally, a model type used to determine which serializer will be used

inputPayload

Object

Push some raw data into the store.

This method can be used both to push in brand new records, as well as to update existing records. You can push in more than one type of object at once. All objects should be in the format expected by the serializer.

import RESTSerializer from '@ember-data/serializer/rest';

export default class ApplicationSerializer extends RESTSerializer;

let pushData = {
  posts: [
    { id: 1, postTitle: "Great post", commentIds: [2] }
  ],
  comments: [
    { id: 2, commentBody: "Insightful comment" }
  ]
}

store.pushPayload(pushData);

By default, the data will be deserialized using a default serializer (the application serializer if it exists).

Alternatively, pushPayload will accept a model type which will determine which serializer will process the payload.

import RESTSerializer from '@ember-data/serializer/rest';

 export default class ApplicationSerializer extends RESTSerializer;

import JSONSerializer from '@ember-data/serializer/json';

export default JSONSerializer;

store.pushPayload(pushData); // Will use the application serializer
store.pushPayload('post', pushData); // Will use the post serializer

query (modelName, query, options) Promise

Defined in ../store/addon/-private/system/core-store.ts:1881

Available since v1.13.0

modelName

String

query

Any

an opaque query to be used by the adapter

options

Object

optional, may include `adapterOptions` hash which will be passed to adapter.query

returns

Promise

promise

This method delegates a query to the adapter. This is the one place where adapter-level semantics are exposed to the application.

Each time this method is called a new request is made through the adapter.

Exposing queries this way seems preferable to creating an abstract query language for all server-side queries, and then require all adapters to implement them.

If you do something like this:

store.query('person', { page: 1 });

The request made to the server will look something like this:

GET "/api/v1/person?page=1"

If you do something like this:

store.query('person', { ids: [1, 2, 3] });

The request made to the server will look something like this:

GET "/api/v1/person?ids%5B%5D=1&ids%5B%5D=2&ids%5B%5D=3"
decoded: "/api/v1/person?ids[]=1&ids[]=2&ids[]=3"

This method returns a promise, which is resolved with an AdapterPopulatedRecordArray once the server returns.

queryRecord (modelName, query, options) Promise

Defined in ../store/addon/-private/system/core-store.ts:1971

Available since v1.13.0

modelName

String

query

Any

an opaque query to be used by the adapter

options

Object

optional, may include `adapterOptions` hash which will be passed to adapter.queryRecord

returns

Promise

promise which resolves with the found record or `null`

This method makes a request for one record, where the id is not known beforehand (if the id is known, use findRecord instead).

This method can be used when it is certain that the server will return a single object for the primary data.

Each time this method is called a new request is made through the adapter.

Let's assume our API provides an endpoint for the currently logged in user via:

// GET /api/current_user
{
  user: {
    id: 1234,
    username: 'admin'
  }
}

Since the specific id of the user is not known beforehand, we can use queryRecord to get the user:

store.queryRecord('user', {}).then(function(user) {
  let username = user.get('username');
  console.log(`Currently logged in as ${username}`);
});

The request is made through the adapters' queryRecord:

import Adapter from '@ember-data/adapter';
import $ from 'jquery';

export default class UserAdapter extends Adapter {
  queryRecord(modelName, query) {
    return $.getJSON('/api/current_user');
  }
}

Note: the primary use case for store.queryRecord is when a single record is queried and the id is not known beforehand. In all other cases store.query and using the first item of the array is likely the preferred way:

// GET /users?username=unique
{
  data: [{
    id: 1234,
    type: 'user',
    attributes: {
      username: "unique"
    }
  }]
}

store.query('user', { username: 'unique' }).then(function(users) {
  return users.get('firstObject');
}).then(function(user) {
  let id = user.get('id');
});

This method returns a promise, which resolves with the found record.

If the adapter returns no data for the primary data of the payload, then queryRecord resolves with null:

// GET /users?username=unique
{
  data: null
}

store.queryRecord('user', { username: 'unique' }).then(function(user) {
  console.log(user); // null
});

serializerFor (modelName) Serializer public

Defined in ../store/addon/-private/system/core-store.ts:3373

modelName

String

the record to serialize

returns

Serializer

Returns an instance of the serializer for a given type. For example, serializerFor('person') will return an instance of App.PersonSerializer.

If no App.PersonSerializer is found, this method will look for an App.ApplicationSerializer (the default serializer for your entire application).

if no App.ApplicationSerializer is found, it will attempt to get the defaultSerializer from the PersonAdapter (adapterFor('person')).

If a serializer cannot be found on the adapter, it will fall back to an instance of JSONSerializer.

unloadAll (modelName)

Defined in ../store/addon/-private/system/core-store.ts:2404

modelName

String

This method unloads all records in the store. It schedules unloading to happen during the next run loop.

Optionally you can pass a type which unload all records for a given type.

store.unloadAll();
store.unloadAll('post');

unloadRecord (record)

Defined in ../store/addon/-private/system/core-store.ts:692

record

Model

For symmetry, a record can be unloaded via the store. This will cause the record to be destroyed and freed up for garbage collection.

Example

store.findRecord('post', 1).then(function(post) {
  store.unloadRecord(post);
});