Methods

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

aggregate(seed, step, finalize)

Calculates a custom summary for the items in the current Query.

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: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 the items in the current Query.

Parameters:
step: function

A function called for each item.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 for the current Query, if each Query item has a numeric type.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 item value for the current Query.

Parameters:
getter: Object

A getter for calculating the current value.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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.

For information on getters, refer to the Getters and Setters section of the Data Layer article.

count()

Returns the total count of items in the current Query.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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

enumerate()

Executes the Query.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 the current Query data.

Parameters:
criteria: Array

A filter expression.

Return Value: Object

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();

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

groupBy(getter)

Groups the current Query data.

Parameters:
getter: Object

The getter by which to group the data.

Return Value: Object

This 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();

For more information on group expressions, refer to the Grouping section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

max()

Finds the item with the maximum value in the Query.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 the item with the maximum getter value.

Parameters:
getter: Object

The required getter.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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.

For information on getters, refer to the Getters and Setters section of the Data Layer article.

min()

Finds the item with the minimum value in the Query.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved when the operation is completed.

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 the item with the minimum getter value.

Parameters:
getter: Object

The required getter.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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.

For information on getters, refer to the Getters and Setters section of the Data Layer article.

select(getter)

Applies the specified transformation to each item.

Parameters:
getter: Object

The getter specifying the transformation rules.

Return Value: Object

This Query object.

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();

For the information on getters, refer to the Getters and Setters section of the Data Layer article.

slice(skip, take)

Limits the data item count.

Parameters:
skip: Number

Specifies the count of the items to skip.

take: Number

Optional. Specifies the count of the items to pick out. If this argument is not specified, all non-skipped items will be picked out.

Return Value: Object

The current 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 current Query data.

Parameters:
getter: Object

The getter by which to sort the data.

Return Value: Object

This 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();

For more information on sort expressions, refer to the Sorting section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

sortBy(getter, desc)

Sorts current Query data.

Parameters:
getter: Object

The getter by which to sort the data.

desc: Boolean

Specifies whether to sort items in descending or ascending order.

Return Value: Object

This 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();

For more information on sorting expressions, refer to the Sorting section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

sum()

Calculates the sum of item values in the current Query.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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 item getter values in the current Query.

Parameters:
getter: Object

The required getter.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the operation is completed.

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.

For information on getters, refer to the Getters and Setters section of the Data Layer article.

thenBy(getter)

Adds one more sorting condition to the current Query.

Parameters:
getter: Object

The getter by which to sort the items.

Return Value: Object

The current 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 the Query items sorted by category and then by name property values.

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

For more information on sort expressions, refer to the Sorting section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

thenBy(getter, desc)

Adds one more sorting condition to the current Query.

Parameters:
getter: Object

The getter by which to sort the items.

desc: Boolean

Specifies whether to sort items in descending or ascending order.

Return Value: Object

This 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", desc: true)
    .toArray();

For more information on sort expressions, refer to the Sorting section of the Data Layer article. For information on getters, refer to the Getters and Setters section of the Data Layer article.

toArray()

Returns the array of current Query items.

Return Value: Array

The array of 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.