DevExtreme Angular - CustomStore Methods

This section describes the methods used to access data associated with the CustomStore.

byKey(key)

Gets a data item with a specific key.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the data item is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

jQuery
JavaScript
// The key consists of a single data field
var singleKeyStore = new DevExpress.data.CustomStore({
    key: "field1",
    // ...
});

// Gets the data item with "field1" being equal to 1
singleKeyStore.byKey(1)
    .done(function (dataItem) {
        // Process the "dataItem" here
    })
    .fail(function (error) {
        // Handle the "error" here
    });

// The key consists of several data fields
var compositeKeyStore = new DevExpress.data.CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

// Gets the data item with both "field1" and "field2" being equal to 1
compositeKeyStore.byKey({
    field1: 1,
    field2: 1
}).done(function (dataItem) {
    // Process the "dataItem" here
})
.fail(function (error) {
    // Handle the "error" here
});
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    singleKeyStore: CustomStore;
    compositeKeyStore: CustomStore;

    constructor() {
        // The key consists of a single data field
        this.singleKeyStore = new CustomStore({
            key: "field1",
            // ...
        });
        // Gets the data item with "field1" being equal to 1
        this.singleKeyStore.byKey(1).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // The key consists of several data fields
        this.compositeKeyStore = new CustomStore({
            key: [ "field1", "field2" ],
            // ...
        });
        // Gets the data item with both "field1" and "field2" being equal to 1
        this.compositeKeyStore.byKey({
            field1: 1,
            field2: 1
        }).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

export default {
    mounted() {
        // Gets the data item with "field1" being equal to 1
        singleKeyStore.byKey(1).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Gets the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.byKey({
            field1: 1,
            field2: 1
        }).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

class App extends React.Component {
    constructor(props) {
        super(props);

        // Gets the data item with "field1" being equal to 1
        singleKeyStore.byKey(1).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Gets the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.byKey({
            field1: 1,
            field2: 1
        }).then(
            (dataItem) => { /* Process the "dataItem" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    }
    // ...
}
export default App;

clearRawDataCache()

Deletes data from the cache. Takes effect only if the cacheRawData option is true.

jQuery
var store = new DevExpress.data.CustomStore({
    // CustomStore is configured here
    cacheRawData: true
});

store.clearRawDataCache();
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor( ... ) {
        this.store = new CustomStore({
            // CustomStore is configured here
            cacheRawData: true
        });
        this.store.clearRawDataCache();
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
    cacheRawData: true
});

export default {
    mounted() {
        store.clearRawDataCache();
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
    cacheRawData: true
});

class App extends React.Component {
    constructor(props) {
        super(props);
        store.clearRawDataCache();
    }
    // ...
}
export default App;

insert(values)

Adds a data item to the store.

Parameters:
values:

Object

A data item.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after a data item is added. It is a native Promise or a jQuery.Promise when you use jQuery.

In the following code, dataObj is a data object added to the database and returned from the server. If the server returns nothing or the store works with local data, dataObj contains the data object passed to the insert method.

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // CustomStore is configured here
});

store.insert({ id: 1, name: "John Doe" })
     .done(function (dataObj, key) {
         // Process the key and data object here
     })
     .fail(function (error) {
         // Handle the "error" here
     });
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // CustomStore is configured here
        });
        this.store.insert({ id: 1, name: "John Doe" })
            .then(
                (dataObj) => { /* Process the data object here */ },
                (error) => { /* Handle the "error" here */ }
            );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

export default {
    mounted() {
        store.insert({ id: 1, name: "John Doe" })
            .then(
                (dataObj) => { /* Process the data object here */ },
                (error) => { /* Handle the "error" here */ }
            );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

class App extends React.Component {
    constructor(props) {
        super(props);

        store.insert({ id: 1, name: "John Doe" })
            .then(
                (dataObj) => { /* Process the data object here */ },
                (error) => { /* Handle the "error" here */ }
            );
    }
    // ...
}
export default App;
NOTE
The data item's key value should be unique, otherwise, the insertion will fail.

key()

Gets the key property (or properties) as specified in the key option.

Return Value: any

The key option's value.

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // ...
    key: "ProductID"
});

var keyProps = store.key(); // returns "ProductID"
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // ...
            key: "ProductID"
        });
        let keyProps = this.store.key(); // returns "ProductID"
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // ...
    key: 'ProductID'
});

export default {
    mounted() {
        this.keyProps = store.key(); // returns "ProductID"
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // ...
    key: 'ProductID'
});

class App extends React.Component {
    constructor(props) {
        super(props);

        this.keyProps = store.key(); // returns "ProductID"
    }
    // ...
}
export default App;

keyOf(obj)

Gets a data item's key value.

Parameters:
obj:

Object

A data item.

Return Value: any

The data item's key value.

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // ...
    key: "id"
});

var key = store.keyOf({ id: 1, name: "John Doe" }); // returns 1
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // ...
            key: "id"
        });
        let key = this.store.keyOf({ id: 1, name: "John Doe" }); // returns 1
    };
}
Vue
App.vue
// ...
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // ...
    key: 'id'
});

export default {
    mounted() {
        this.key = store.keyOf({ id: 1, name: "John Doe" }); // returns 1
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // ...
    key: 'id'
});

class App extends React.Component {
    constructor(props) {
        super(props);

        this.keyProps = store.keyOf({ id: 1, name: "John Doe" }); // returns 1
    }
    // ...
}
export default App;

load()

Starts loading data.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

load(options)

Starts loading data.

Parameters:
options:

LoadOptions

Data processing settings.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // CustomStore is configured here
});

store.load(options)
     .done(function (data) {
         // Process "data" here
     })
     .fail(function (error) {
         // Handle the "error" here
     });
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
import DevExpress from "devextreme/bundles/dx.all";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // CustomStore is configured here
        });
        let options: DevExpress.data.LoadOptions = {
            // Data processing settings are specified here
        };
        this.store.load(options)
            .then(
                (data) => { /* Process "data" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

export default {
    mounted() {
        let options = {
            // Data processing settings are specified here
        };
        store.load(options)
            .then(
                (data) => { /* Process "data" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

class App extends React.Component {
    constructor(props) {
        super(props);

        let options = {
            // Data processing settings are specified here
        };
        store.load(options)
            .then(
                (data) => { /* Process "data" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    }
    // ...
}
export default App;

off(eventName)

Detaches all event handlers from a single event.

Parameters:
eventName:

String

The event's name.

Return Value:

CustomStore

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

CustomStore

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to an event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

CustomStore

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to events.

Parameters:
events:

Object

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

CustomStore

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

push(changes)

Pushes data changes to the store and notifies the DataSource.

Parameters:
changes:

Array<any>

Data changes to be pushed.

There are three possible data change types:

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // CustomStore is configured here
});

store.push([{ type: "insert", data: data }]);
store.push([{ type: "update", data: data, key: key }]);
store.push([{ type: "remove", key: key }]);
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // CustomStore is configured here
        });
        this.store.push([{ type: "insert", data: data }]);
        this.store.push([{ type: "update", data: data, key: key }]);
        this.store.push([{ type: "remove", key: key }]);
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

export default {
    mounted() {
        store.push([{ type: "insert", data: data }]);
        store.push([{ type: "update", data: data, key: key }]);
        store.push([{ type: "remove", key: key }]);
    }
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

class App extends React.Component {
    constructor(props) {
        super(props);

        store.push([{ type: "insert", data: data }]);
        store.push([{ type: "update", data: data, key: key }]);
        store.push([{ type: "remove", key: key }]);
    }
    // ...
}
export default App;

The DataSource does not automatically sort, group, filter, or otherwise shape pushed data. If it should, enable the reshapeOnPush option. We also recommend specifying the pushAggregationTimeout to reduce the number of updates and recalculations.

When data is grouped or paginated, the widget bound to the DataSource ignores inserted data items until data is reshaped. Disable grouping and paging or enable reshapeOnPush for the inserted data items to appear immediately after they are pushed. The DataGrid and TreeList widgets have individual grouping and paging options. Use them instead of the corresponding DataSource options.

IMPORTANT
This method does not modify the remote data source. It is used to push changes from the remote data source to the store without reloading all data.

DataGrid Real-Time Updates Demo DataGrid SignalR Demo Chart SignalR Demo DataGrid Collaborative Editing Demo

See Also

remove(key)

Removes a data item with a specific key from the store.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the data item is removed. It is a native Promise or a jQuery.Promise when you use jQuery.

jQuery
JavaScript
// The key consists of a single data field
var singleKeyStore = new DevExpress.data.CustomStore({
    key: "field1",
    // ...
});

// Removes the data item with "field1" being equal to 1
singleKeyStore.remove(1)
    .done(function (key) {
        // Process the "key" here
    })
    .fail(function (error) {
        // Handle the "error" here
    });

// The key consists of several data fields
var compositeKeyStore = new DevExpress.data.CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

// Removes the data item with both "field1" and "field2" being equal to 1
compositeKeyStore.remove({
    field1: 1,
    field2: 1
}).done(function (key) {
    // Process the "key" here
})
.fail(function (error) {
    // Handle the "error" here
});
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    singleKeyStore: CustomStore;
    compositeKeyStore: CustomStore;

    constructor() {
        // The key consists of a single data field
        this.singleKeyStore = new CustomStore({
            key: "field1",
            // ...
        });
        // Removes the data item with "field1" being equal to 1
        this.singleKeyStore.remove(1)
            .then(
                (key) => { /* Process the "key" here */ },
                (error) => { /* Handle the "error" here */ }
            );

        // The key consists of several data fields
        this.compositeKeyStore = new CustomStore({
            key: [ "field1", "field2" ],
            // ...
        });
        // Removes the data item with both "field1" and "field2" being equal to 1
        this.compositeKeyStore.remove({
            field1: 1,
            field2: 1
        }).then(
            (key) => { /* Process the "key" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

export default {
    mounted() {
        // Removes the data item with "field1" being equal to 1
        singleKeyStore.remove(1).then(
            (key) => { /* Process the "key" here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Removes the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.remove({
            field1: 1,
            field2: 1
        }).then(
            (key) => { /* Process the "key" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

class App extends React.Component {
    constructor(props) {
        super(props);

        // Removes the data item with "field1" being equal to 1
        singleKeyStore.remove(1).then(
            (key) => { /* Process the "key" here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Removes the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.remove({
            field1: 1,
            field2: 1
        }).then(
            (key) => { /* Process the "key" here */ },
            (error) => { /* Handle the "error" here */ }
        );
    }
    // ...
}
export default App;

totalCount(options)

Gets the total count of items the load() function returns.

Parameters:
obj:

Object

Filtering and grouping options.

Object structure:
Name Type Description
filter

Object

A filtering expression; described in the Filtering section.
group

Object

A grouping expression; described in the Grouping section.
Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the total item count is obtained. It is a native Promise or a jQuery.Promise when you use jQuery.

jQuery
JavaScript
var store = new DevExpress.data.CustomStore({
    // CustomStore is configured here
});

store.totalCount()
     .done(function (count) {
         // Process the "count" here
     })
     .fail(function (error) {
         // Handle the "error" here
     });
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    store: CustomStore;
    constructor() {
        this.store = new CustomStore({
            // CustomStore is configured here
        });
        this.store.totalCount()
            .then(
                (count) => { /* Process the "count" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

export default {
    mounted() {
        store.totalCount()
            .then(
                (count) => { /* Process the "count" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

const store = new CustomStore({
    // CustomStore is configured here
});

class App extends React.Component {
    constructor(props) {
        super(props);

        store.totalCount()
            .then(
                (count) => { /* Process the "count" here */ },
                (error) => { /* Handle the "error" here */ }
            );
    }
    // ...
}
export default App;

update(key, values)

Updates a data item with a specific key.

Parameters:
key:

Object

|

String

|

Number

A data item's key value.

values:

Object

An object with new values for the data item.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the data item is updated. It is a native Promise or a jQuery.Promise when you use jQuery.

In the following code, dataObj is a data object updated in the database and returned from the server. If the server returns nothing or the store works with local data, dataObj contains the data object passed to the update method.

jQuery
JavaScript
// The key consists of a single data field
var singleKeyStore = new DevExpress.data.CustomStore({
    key: "field1",
    // ...
});

// Updates the data item with "field1" being equal to 1
singleKeyStore.update(1, { name: "John Smith" })
    .done(function (dataObj, key) {
        // Process the key and data object here
    })
    .fail(function (error) {
        // Handle the "error" here
    });

// The key consists of several data fields
var compositeKeyStore = new DevExpress.data.CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

// Updates the data item with both "field1" and "field2" being equal to 1
compositeKeyStore.update(
    { field1: 1, field2: 1 },
    { name: "John Smith" }
).done(function (dataObj, key) {
    // Process the key and data object here
})
.fail(function (error) {
    // Handle the "error" here
});
Angular
TypeScript
import CustomStore from "devextreme/data/custom_store";
// ...
export class AppComponent {
    singleKeyStore: CustomStore;
    compositeKeyStore: CustomStore;

    constructor() {
        // The key consists of a single data field
        this.singleKeyStore = new CustomStore({
            key: "field1",
            // ...
        });
        // Updates the data item with "field1" being equal to 1
        this.singleKeyStore.update(1, { name: "John Smith" })
            .then(
                (dataObj) => { /* Process the data object here */ },
                (error) => { /* Handle the "error" here */ }
            );

        // The key consists of several data fields
        this.compositeKeyStore = new CustomStore({
            key: [ "field1", "field2" ],
            // ...
        });
        // Updates the data item with both "field1" and "field2" being equal to 1
        this.compositeKeyStore.update(
            { field1: 1, field2: 1 },
            { name: "John Smith" }
        ).then(
            (dataObj) => { /* Process the data object here */ },
            (error) => { /* Handle the "error" here */ }
        );
    };
}
Vue
App.vue
<script>
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

export default {
    mounted() {
        // Updates the data item with "field1" being equal to 1
        singleKeyStore.update(1, { name: "John Smith" }).then(
            (dataObj) => { /* Process the data object here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Updates the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.update(
            { field1: 1, field2: 1 },
            { name: "John Smith" }
        ).then(
            (dataObj) => { /* Process the data object here */ },
            (error) => { /* Handle the "error" here */ }
        );
    },
    // ...
}
</script>
React
App.js
// ...
import CustomStore from 'devextreme/data/custom_store';

// The key consists of a single data field
const singleKeyStore = new CustomStore({
    key: "field1",
    // ...
});

// The key consists of several data fields
const compositeKeyStore = new CustomStore({
    key: [ "field1", "field2" ],
    // ...
});

class App extends React.Component {
    constructor(props) {
        super(props);

        // Updates the data item with "field1" being equal to 1
        singleKeyStore.update(1, { name: "John Smith" }).then(
            (dataObj) => { /* Process the data object here */ },
            (error) => { /* Handle the "error" here */ }
        );

        // Updates the data item with both "field1" and "field2" being equal to 1
        compositeKeyStore.update(
            { field1: 1, field2: 1 },
            { name: "John Smith" }
        ).then(
            (dataObj) => { /* Process the data object here */ },
            (error) => { /* Handle the "error" here */ }
        );
    }
    // ...
}
export default App;