Methods

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

aggregate(seed, step, finalize)

Calculates a custom summary for all data items.

Parameters:
seed:

Object

The initial value.

step:

function

A function called for each item.

finalize:

function

A function invoked after the operation is finished.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The step function takes on two arguments. The first argument is an accumulator value changed on each step function execution. The step function should return the updated value of this argument. The second argument is a value of the current item. The finalize function takes on the resulting accumulator value, and should return the desired value.

The following example demonstrates how to calculate the average value for the Query items.

Suppose that each item of the Query is an object that provides the price numeric property, among other properties. To calculate the average price value, calculate the total price and divide it by the item count.

In this case, the seed argument specifies the initial value of the total price, which will be increased within the step function called for each item. The finalize function will divide the total price by the item count.

JavaScript
var count = 0;
DevExpress.data.query(inputArray)
    .aggregate(
        0, 
        function(total) {
            return total + itemData;
            count++;
        },
        function(total) {
            return total / count;
        }
     )
    .done(function(result) {
        // 'result' holds the desired value
    });

The average value calculation is an example of this function's usage. However, note that this functionality is already implemented in the avg() and avg(getter) methods.

aggregate(step)

Calculates a custom summary for all data items.

Parameters:
step:

function

A function called for each item.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The step function takes on two arguments. The first argument is an accumulator value changed on each step function execution. The step function should return the updated value of this argument.

NOTE
The accumulator value is initialized to the value of the first item. Therefore, the step function is called only for the second item, and subsequent items.

The following example demonstrates how to calculate the total value for the Query items. Suppose that each item of the Query is an object providing the price numeric property, among other properties.

JavaScript
var total = 0;
DevExpress.data.query(inputArray)
    .aggregate(
        function(total, itemData) {
            total += itemData;
        }
    )
    .done(function(result) {
        // 'result' holds the desired value
    });

The total value calculation is a demonstrative example of this function's usage. However, note that this functionality is already implemented in the sum() and sum(getter) methods.

avg()

Calculates the average item value. Takes effect only if data is a numeric array.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

If a Query item is an object, you should transform it to a numeric type with the select(getter) method, or use the avg(getter) method instead of avg().

The following example demonstrates how to calculate the average value of the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .select("price")
    .avg()
    .done(function(result) {
        // 'result' holds the desired value
    });

avg(getter)

Calculates the average getter value.

Parameters:
getter:

Object

The getter to be used for calculating the average value.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The following example demonstrates how to calculate the average value of the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .avg("price")
    .done(function(result) {
        // 'result' holds the desired value
    });

If a Query item is a numeric value, use the avg() method instead of this one.

count()

Gets the total item count.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
var data = DevExpress.data.query(inputArray)
    .count()
    .done(function(result) {
        // 'result' holds the desired value
    });

enumerate()

Executes the Query.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

JavaScript
DevExpress.data.query("http://www.example.com/service.url", queryOptions)
    .enumerate()
    .done(function(result) {
        // 'result' holds the got array
    });

This method is an alternate to the toArray() method. The same result, but different form.

filter(criteria)

Filters data items using a filter expression.

Parameters:
criteria:

Array<any>

A filter expression; described in the Filtering section.

Return Value:

Query

The Query object.

The following example demonstrates how to get an array of the Query items whose price value is lower than 500.

JavaScript
var data = DevExpress.data.query(inputArray).filter("price", "<", 500).toArray();

filter(predicate)

Filters data items using a custom function.

Parameters:
predicate:

function

A function that accepts a data item and returns a Boolean value indicating whether the resulting array includes the item.

Return Value:

Query

The Query object.

The following example demonstrates how to get an array of the Query items whose price value is lower than 500.

JavaScript
var data = DevExpress.data.query(inputArray).filter(function(item){
    if(item.price < 500)
        return true;
    return false;
}).toArray();

For information on filtering, refer to the Filtering section of the Data Layer article.

groupBy(getter)

Groups data items.

Parameters:
getter:

Object

The getter to be used for grouping data.

Return Value:

Query

The Query object.

The following example demonstrates how to get an array of the Query items grouped by the name property value.

JavaScript
var data = DevExpress.data.query(inputArray)
    .groupBy("name")
    .toArray();
See Also

max()

Finds a data item with the maximum value. Takes effect only if data is a numeric array.

Return Value:

Promise<Number | Date> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

If a Query item is an object, you should transform it to a numeric type with the select(getter) method, or use the max(getter) method instead of max().

The following example demonstrates how to get the maximum value from the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .select(function(itemData) {
        return itemData.price;
    })
    .max()
    .done(function(result) {
        // 'result' holds the desired value
    });

max(getter)

Finds a data item with the maximum getter value.

Parameters:
getter:

Object

The getter.

Return Value:

Promise<Number | Date> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The following example demonstrates how to get the maximum value from the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .max("price")
    .done(function(result) {
        // 'result' holds the desired value
    });

If a Query item is a numeric value, use the max() method instead of this one.

min()

Finds a data item with the minimum value. Takes effect only if data is a numeric array.

Return Value:

Promise<Number | Date> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

If a Query item is an object, you should transform it to a numeric type with the select(getter) method, or use the min(getter) method instead of min().

The following example demonstrates how to get the minimum value from the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .select(function(itemData) {
        return itemData.price;
    })
    .min()
    .done(function(result) {
        // 'result' holds the desired value
    });

min(getter)

Finds a data item with the minimum getter value.

Parameters:
getter:

Object

The getter.

Return Value:

Promise<Number | Date> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The following example demonstrates how to get the minimum value from the price property values of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .max("price")
    .done(function(result) {
        // 'result' holds the desired value
    });

If a Query item is a numeric value, use the min() method instead of this one.

select(getter)

Selects data using a getter.

Parameters:
getter:

Object

The getter.

Return Value:

Query

This Query object with transformed data.

The following example demonstrates how to get an array of price values of initial Query items.

JavaScript
var data = DevExpress.data.query(inputArray).select("price").toArray();

slice(skip, take)

Limits the number of data items.

Parameters:
skip:

Number

The number of items to be skipped.

take:

Number

| undefined

Optional. The number of items to pick out.

Return Value:

Query

The Query object.

The following example demonstrates how to pick 5 to 15 items from the Query.

JavaScript
var data = DevExpress.data.query(inputArray).slice(5, 10).toArray();

sortBy(getter)

Sorts data items.

Parameters:
getter:

Object

The getter to be used for sorting data.

Return Value:

Query

The Query object.

The following example demonstrates how to get an array of the Query items sorted by the name property value.

JavaScript
var data = DevExpress.data.query(inputArray).sortBy("name").toArray();
See Also

sortBy(getter, desc)

Sorts data items in the specified sort order.

Parameters:
getter:

Object

The getter to be used for sorting data.

desc:

Boolean

Specifies whether to sort items in descending or ascending order.

Return Value:

Query

The Query object.

The following example demonstrates how to get an array of the Query items sorted by the name property value in the descending order.

JavaScript
var data = DevExpress.data.query(inputArray)
    .sortBy("name", true)
    .toArray();
See Also

sum()

Calculates the sum of item values.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

If a Query item is an object, you should transform it to a numeric type with the select(getter) method, or use the sum(getter) method instead of sum().

The following example demonstrates how to calculate the total price value of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .select("price")
    .sum()
    .done(function(result) {
        // 'result' holds the desired value
    });

sum(getter)

Calculates the sum of getter values.

Parameters:
getter:

Object

The getter to be used for calculating the sum.

Return Value:

Promise<Number> (jQuery or native)

A Promise that is resolved after the operation is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

The following example demonstrates how to calculate the total price value of the Query items.

JavaScript
DevExpress.data.query(inputArray)
    .sum("price")
    .done(function(result) {
        // 'result' holds the desired value
    });

If a Query item is a numeric value, use the sum() method instead of this one.

thenBy(getter)

Adds one more sorting expression to the Query.

Parameters:
getter:

Object

The getter to be used for sorting data items.

Return Value:

Query

The Query object.

This method can only follow the sortBy(getter), sortBy(getter, desc), thenBy(getter, desc), or another thenBy(getter) method.

The following example demonstrates how to get an array of Query items sorted by category and then by name property values:

JavaScript
var data = DevExpress.data.query(inputArray)
    .sortBy("category")
    .thenBy("name")
    .toArray();
See Also

thenBy(getter, desc)

Adds one more sorting expression to the Query. The sort order depends on the second argument.

Parameters:
getter:

Object

The getter to be used for sorting data items.

desc:

Boolean

Specifies whether to sort items in descending or ascending order.

Return Value:

Query

The Query object.

This method can only follow the sortBy(getter), sortBy(getter, desc), thenBy(getter) or the other thenBy(getter, desc) methods.

The following example demonstrates how to get an array of the Query items sorted by category and then by name property values in the descending order:

JavaScript
var data = DevExpress.data.query(inputArray)
    .sortBy("category")
    .thenBy("name", true)
    .toArray();
See Also

toArray()

Gets data items.

Return Value:

Array<any>

The data items.

JavaScript
var data = DevExpress.data.query(inputArray).sortBy("lastName").toArray();

This method is an alternative to the enumerate() method and is executed synchronously. Only the array query supports it.