CorvidReference

WixDataAggregate

Provides functionality for performing aggregations on collection data.

The aggregation functionality of the Data API allows you to perform calculations on your collection data, as whole or on groups of items that you define, to retrieve meaningful summaries. You can also add filtering and sorting to your aggregations to retrieve exactly what you need.

The examples below use a sample collection, named PopulationData, with the following data:

 City,          Population, State,  Year
 Buffalo,       292000,     NY,     2000
 Buffalo,       261000,     NY,     2010
 Los Angeles,   3703000,    CA,     2000
 Los Angeles,   3796000,    CA,     2010
 Miami,         362000,     FL,     2000
 Miami,         401000,     FL,     2010
 New York,      8015000,    NY,     2000
 New York,      8192000,    NY,     2010
 Orlando,       195000,     FL,     2000
 Orlando,       240000,     FL,     2010
 San Diego      1228000,    CA,     2010
 San Diego      1306000,    CA,     2012
 San Francisco, 777000,     CA,     2000
 San Francisco, 805000,     CA,     2010

For more information, see Working with Aggregations and Groupings in the Data API.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Table of Contents

FUNCTIONS

?
Perform actions on an object.
ascending( )Adds a sort to an aggregation, sorting by the items or groups by the specified properties in ascending order.
avg( )Refines a WixDataAggregate to only contain the average value from each aggregation group.
count( )Refines a WixDataAggregate to contain the item count of each group in the aggregation.
descending( )Adds a sort to an aggregation, sorting by the items or groups by the specified properties in descending order.
filter( )Filters out items from being used in an aggregation.
group( )Groups items together in an aggregation.
having( )Filters out groups from being returned from an aggregation.
limit( )Limits the number of items or groups the aggregation returns.
max( )Refines a WixDataAggregate to only contain the maximum value from each aggregation group.
min( )Refines a WixDataAggregate to only contain the minimum value from each aggregation group.
run( )Runs the aggregation and returns the results.
skip( )Sets the number of items or groups to skip before returning aggregation results.
sum( )Refines a WixDataAggregate to contain the sum from each aggregation group.

ascending( )

Adds a sort to an aggregation, sorting by the items or groups by the specified properties in ascending order.

Description

The ascending() function refines a WixDataAggregate to sort the resulting items or groups in ascending order. If you specify more than one property, ascending() sorts the results in ascending order by each property in the order they are listed.

You can sort the following types:

  • Number: Sorts numerically.
  • Date: Sorts by date and time.
  • String: Sorts lexicographically, so "abc" comes after "XYZ".
  • Reference: Compares by the ID of the referenced item as a String.

If a property contains a number as a String, that value will be sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function ascending(propertyName: ...string): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The properties used in the sort.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add an ascending sort to an aggregation

let newAggregate = aggregate.ascending("state", "city");

Create an aggregation, add an ascending sort, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .avg("population")
  .ascending("populationAvg")
  .run()
  .then( (results) => {
    let items = results.items;        // see below
    let numItems = results.length;    // 6
    let hasNext = results.hasNext();  // false
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationAvg": 4226500,
 *     "state": "NY",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationAvg": 4153500,
 *     "state": "NY",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationAvg": 1969000,
 *     "state": "CA",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationAvg": 2240000,
 *     "state": "CA",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationAvg": 320500,
 *     "state": "FL",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationAvg": 278500,
 *     "state": "FL",
 *     "year": 2000
 *   }
 * ]
 */

avg( )

Refines a WixDataAggregate to only contain the average value from each aggregation group.

Description

The avg() function refines a WixDataAggregate to contain the average value from the specified property for each aggregated group or from the whole collection if no group is defined.

When the aggregation is run, the returned WixDataAggregateResult object contains an item for each group with the following key:value pairs:

  • If a value was passed for the optional projectedName, the key is named using that value. Otherwise, the key is named using the following format: "propertyNameAvg", where propertyName is the name of the specified property.
  • The value is the average of the values found in the specified property.

Averages can only be calculated on properties of type Number.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function avg(propertyName: string, [projectedName: string]): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The property in which to find the average value.
projectedName(Optional)
string
The name of the property in the aggregation results containing the average value.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add an avg aggregation

let newAggregate = aggregate.avg("population");

Add an avg aggregation with a projected name for the results

let newAggregate = aggregate.max("population", "avgPopulation");

Create an aggregation, add an avg aggregation, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .avg("population")
  .run()
  .then( (results) => {
    let items = results.items;        // see below
    let numItems = results.length;    // 6
    let hasNext = results.hasNext();  // false
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationAvg": 4153500,
 *     "state": "NY",
 *     "year": 2000},
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationAvg": 278500,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationAvg": 2240000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationAvg": 320500,
 *     "state": "FL",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationAvg": 2300500,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationAvg": 4226500,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation, add an avg aggregation with a projected name for the results, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .avg("population", "averagePopulation")
  .run()
  .then( (results) => {
    let items = results.items;        // see below
    let numItems = results.length;    // 6
    let hasNext = results.hasNext();  // false
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "averagePopulation": 4153500,
 *     "state": "NY",
 *     "year": 2000},
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "averagePopulation": 278500,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "averagePopulation": 2240000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "averagePopulation": 320500,
 *     "state": "FL",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "averagePopulation": 2300500,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "averagePopulation": 4226500,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

count( )

Refines a WixDataAggregate to contain the item count of each group in the aggregation.

Description

The count() function refines a WixDataAggregate to contain the item count in each of the aggregate's groups.

When the aggregation is run, the returned WixDataAggregateResult object contains items with the following additional key:value pair:

  • The key is named "count".
  • The value is the count of items aggregated in the group.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function count(): WixDataAggregate
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a sum aggregation

let newAggregate = aggregate.count();

Create an aggregation, add a sum aggregation, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .count()
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "count": 2,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "count": 2,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "count": 2,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "count": 2,
 *     "state": "FL",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "count": 2,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "count": 2,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

descending( )

Adds a sort to an aggregation, sorting by the items or groups by the specified properties in descending order.

Description

The descending() function refines a WixDataAggregate to sort the resulting items or groups in descending order. If you specify more than one property, descending() sorts the results in descending order by each property in the order they are listed.

You can sort the following types:

  • Number: Sorts numerically.
  • Date: Sorts by date and time.
  • String: Sorts lexicographically, so "abc" comes after "XYZ".
  • Reference: Compares by the ID of the referenced item as a String.

If a property contains a number as a String, that value will be sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function descending(propertyName: ...string): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The properties used in the sort.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a descending sort to an aggregation

let newAggregate = aggregate.descending("state", "city");

Create an aggregation, add a descending sort, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .avg("population")
  .descending("populationAvg")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY","year": 2010},
 *     "populationAvg": 4226500,
 *     "state": "NY",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "NY","year": 2000},
 *     "populationAvg": 4153500,
 *     "state": "NY",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "CA","year": 2010},
 *     "populationAvg": 1969000,
 *     "state": "CA",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationAvg": 2240000,
 *     "state": "CA",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationAvg": 320500,
 *     "state": "FL",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationAvg": 278500,
 *     "state": "FL",
 *     "year": 2000
 *   }
 * ]
 */

filter( )

Filters out items from being used in an aggregation.

Description

The filter() function refines a WixDataAggregate so that it only includes items from the aggregate's collection which match the specified filter criteria.

To create a filter, use the wix-data filter() function.

Filtering using filter() takes place before grouping is performed on the aggregation. To filter grouped results, use the having() function.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function filter(filter: WixDataFilter): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
filter
The filter to use to filter out items from being used in the aggregation.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Filter out items in an aggregation

let filter = wixData.filter().eq("year", 2010);

let newAggregate = aggregate.filter(filter);

Filter out items in an aggregation and run the aggregation

import wixData from 'wix-data';

// ...

let filter = wixData.filter().eq("year", 2010);

wixData.aggregate("PopulationData")
  .filter(filter)
  .max("population", "maxPopulation")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 1
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

// items is: [{"_id":"0","maxPopulation":8192000}]

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

group( )

Groups items together in an aggregation.

Description

The group() function refines a WixDataAggregate so that its items are grouped by the specified property or properties.

You can perform aggregations on the groups using the following functions:

To filter grouped results, use the having() function.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function group(propertyName: ...string): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The property or properties to group on.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Group items in an aggregation

let newAggregate = aggregate.group("state");

Group items by multiple fields in an aggregation

let newAggregate = aggregate.group("state", "year");

Group items in an aggregation and run the aggregation

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state")
  .max("population")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 3
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {"_id": "FL", "populationMax": 401000},
 *   {"_id": "CA", "populationMax": 3796000},
 *   {"_id": "NY", "populationMax": 8192000}
 * ]
 */

Group items in an aggregation and run the aggregation

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .max("population")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationMax": 8015000,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationMax": 362000,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationMax": 8192000,
 *     "state": "NY",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationMax": 3796000,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationMax": 3703000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationMax": 401000,
 *     "state": "FL",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

having( )

Filters out groups from being returned from an aggregation.

Description

The having() function refines a WixDataAggregate so that it only includes groups from the aggregate's grouping which match the specified filter criteria.

To create a filter, use the wix-data filter() function.

Filtering using having() takes place after grouping is performed on the aggregation. To filter items before grouping, use the filter() function.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function having(filter: WixDataFilter): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
filter
The filter to use to filter out groups from being returned from the aggregation.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Filter out groups in an aggregation

let having = wixData.filter().gt("maxPopulation", 1000000);

let newAggregate = aggregate.having(having);

Filter out groups in an aggregation and run the aggregation

import wixData from 'wix-data';

// ...

let having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .group("city", "state")
  .max("population", "maxPopulation")
  .having(having)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 3
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"city": "San Diego", "state": "CA"},
 *     "maxPopulation": 1306000,
 *     "city": "San Diego",
 *     "state": "CA"
 *   }, {
 *     "_id": {"city": "New York", "state": "NY"},
 *     "maxPopulation": 8192000,
 *     "city": "New York",
 *     "state": "NY"
 *   }, {
 *     "_id": {"city": "Los Angeles", "state": "CA"},
 *     "maxPopulation": 3796000,
 *     "city": "Los Angeles",
 *     "state": "CA"
 *   }
 * ]
 */

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

limit( )

Limits the number of items or groups the aggregation returns.

Description

The limit() function defines the number of results an aggregation returns in each page. Only one page of results is retreived at a time. The next() function is used to navigate the pages of a query result.

By default, limit is set to 50.

The maximum value that limit() can accept is 1000.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function limit(limit: number): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
limit
number
The number of items or groups to return.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a limit to an aggregation

let newAggregate = aggregate.limit(3);

Create an aggregate, add a limit, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .max("population")
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 3
      let hasNext = results.hasNext();  // true
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationMax":8015000,
 *     "state": "NY",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationMax":362000,
 *     "state": "FL",
 *     "year": 2000
 *   }, {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationMax":3703000,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

max( )

Refines a WixDataAggregate to only contain the maximum value from each aggregation group.

Description

The max() function refines a WixDataAggregate to contain the maximum value from the specified property for each aggregated group or from the whole collection if no group is defined.

When the aggregation is run, the returned WixDataAggregateResult object contains an item for each group with the following key:value pairs:

  • If a value was passed for the optional projectedName, the key is named using that value. Otherwise, the key is named using the following format: "propertyNameMax", where propertyName is the name of the specified property.
  • The value is the maximum value found in the specified property.

The following types of properties can be compared to determine a maximum value:

  • Number: Compares numerically.
  • Date and Time: Compares JavaScript Date objects.
  • Text: Compares lexicographically, so "text" is greater than "Text".
  • Rich Text: Compares HTML source as text.
  • URL: Compares as text.
  • Image: Compares image source as text.
  • Video: Compares video source as text.
  • Document: Compares document source as text.
  • Reference: Compares by the ID of the referenced item as a String.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function max(propertyName: string, [projectedName: string]): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The property in which to find the maximum value.
projectedName(Optional)
string
The name of the property in the aggregation results containing the maximum value.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a max aggregation

let newAggregate = aggregate.max("population");

Add a max aggregation with a projected name for the results

let newAggregate = aggregate.max("population", "maxPopulation");

Create an aggregation, add a max aggregation, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .max("population")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationMax": 8015000,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationMax": 362000,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationMax": 3703000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationMax": 401000,
 *     "state": "FL",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationMax": 3796000,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationMax": 8192000,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation, add a max aggregation with a projected name for the results, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .max("population", "maximumPopulation")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "maximumPopulation": 8015000,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "maximumPopulation": 362000,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "maximumPopulation": 3703000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "maximumPopulation": 401000,
 *     "state": "FL",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "maximumPopulation": 3796000,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "maximumPopulation": 8192000,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

min( )

Refines a WixDataAggregate to only contain the minimum value from each aggregation group.

Description

The min() function refines a WixDataAggregate to contain the minimum value from the specified property for each aggregated group or from the whole collection if no group is defined.

When the aggregation is run, the returned WixDataAggregateResult object contains an item for each group with the following key:value pairs:

  • If a value was passed for the optional projectedName, the key is named using that value. Otherwise, the key is named using the following format: "propertyNameMin", where propertyName is the name of the specified property.
  • The value is the minimum value found in the specified property.

The following types of properties can be compared to determine a minimum value:

  • Number: Compares numerically.
  • Date and Time: Compares JavaScript Date objects.
  • Text: Compares lexicographically, so "text" is greater than "Text".
  • Rich Text: Compares HTML source as text.
  • URL: Compares as text.
  • Image: Compares image source as text.
  • Video: Compares video source as text.
  • Document: Compares document source as text.
  • Reference: Compares by the ID of the referenced item as a String.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function min(propertyName: string, [projectedName: string]): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The property in which to find the minimum value.
projectedName(Optional)
string
The name of the property in the aggregation results containing the minimum value.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a min aggregation

let newAggregate = aggregate.min("population");

Add a min aggregation with a projected name for the results

let newAggregate = aggregate.min("population", "minPopulation");

Create an aggregation, add a max aggregation, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .min("population")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationMin": 292000,
 *     "state": "NY",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationMin": 195000,
 *     "state": "FL",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationMin": 261000,
 *     "state": "NY",
 *     "year":2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationMin": 805000,
 *     "state": "CA",
 *     "year":2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationMin": 777000,
 *     "state": "CA",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationMin": 240000,
 *     "state": "FL",
 *     "year":2010
 *   }
 * ]
 */

Create an aggregation, add a min aggregation with a projected name for the results, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .min("population", "minimumPopulation")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "minimumPopulation": 292000,
 *     "state": "NY",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "minimumPopulation": 195000,
 *     "state": "FL",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "minimumPopulation": 261000,
 *     "state": "NY",
 *     "year":2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "minimumPopulation": 805000,
 *     "state": "CA",
 *     "year":2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "minimumPopulation": 777000,
 *     "state": "CA",
 *     "year":2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "minimumPopulation": 240000,
 *     "state": "FL",
 *     "year":2010
 *   }
 * ]
 */

run( )

Runs the aggregation and returns the results.

Description

The run() function returns a Promise that resolves to the results found by the aggregation and some information about the results.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function run(): Promise<WixDataAggregateResult>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.

Fulfilled - A Promise that resolves to the results of the aggregation. Rejected - Error that caused the aggregation to fail.

Examples

Perform an aggregation

aggregate.run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();  
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

skip( )

Sets the number of items or groups to skip before returning aggregation results.

Description

The skip() function defines the number of results to skip in the aggregation results before returning new aggregation results.

For example, if you perform an aggregation on a collection and 10 groups match your aggregation, but you set skip to 3, the results returned will skip the first 3 groups that match and return the 4th through 10th items.

By default, skip is set to 0.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function skip(skip: number): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
skip
number
The number of items or groups to skip in the aggregation results before returning the results.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a skip to an aggregation

let newAggregate = aggregate.skip(10);

Create an aggregate, add a skip, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .max("population")
  .skip(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 3
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationMax":401000,
 *     "state": "FL",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationMax":3796000,
 *     "state": "CA",
 *     "year": 2010
 *   }, {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationMax":8192000,
 *     "state": "NY",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation with filtering and grouping and run it

import wixData from 'wix-data';

// ...

const filter = wixData.filter().eq("year", 2010);
const having = wixData.filter().gt("maxPopulation", 1000000);

wixData.aggregate("PopulationData")
  .filter(filter)
  .group("state")
  .max("population", "maxPopulation")
  .having(having)
  .descending("maxPopulation")
  .skip(5)
  .limit(3)
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;
      let numItems = results.length;
      let hasNext = results.hasNext();
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

sum( )

Refines a WixDataAggregate to contain the sum from each aggregation group.

Description

The sum() function refines a WixDataAggregate to contain the sum of the values from the specified property for each aggregated group or from the whole collection if no group is defined.

When the aggregation is run, the returned WixDataAggregateResult object contains an item for each group with the following key:value pairs:

  • If a value was passed for the optional projectedName, the key is named using that value. Otherwise, the key is named using the following format: "propertyNameSum", where propertyName is the name of the specified property.
  • The value is the sum of the values found in the specified property.

Sums can only be calculated on properties of type Number.

Note

Aggregations can only be used on collections you have created. They cannot be used on Wix App Collections.

Syntax

function sum(propertyName: string, [projectedName: string]): WixDataAggregate
PARAMETERS
?
Values that you pass to a function.
propertyName
string
The property in which to find the sum.
projectedName(Optional)
string
The name of the property in the aggregation results containing the sum.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
A WixDataAggregate object representing the refined aggregation.

Examples

Add a sum aggregation

let newAggregate = aggregate.sum("population");

Add a sum aggregation with a projected name for the results

let newAggregate = aggregate.sum("population", "sumPopulation");

Create an aggregation, add a sum aggregation, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .sum("population")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "populationSum": 8307000,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "populationSum": 557000,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "populationSum": 8453000,
 *     "state": "NY",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "populationSum": 4601000,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "populationSum": 4480000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "populationSum": 641000,
 *     "state": "FL",
 *     "year": 2010
 *   }
 * ]
 */

Create an aggregation, add a sum aggregation with a projected name for the results, and run it

import wixData from 'wix-data';

// ...

wixData.aggregate("PopulationData")
  .group("state", "year")
  .sum("population", "totalPopulation")
  .run()
  .then( (results) => {
    if (results.items.length > 0) {
      let items = results.items;        // see below
      let numItems = results.length;    // 6
      let hasNext = results.hasNext();  // false
    } else {
      // handle case where no matching items found
    }
  } )
  .catch( (error) => {
    let errorMsg = error.message;
    let code = error.code;
  } );

/* Given the sample data above, items is:
 * [
 *   {
 *     "_id": {"state": "NY", "year": 2000},
 *     "totalPopulation": 8307000,
 *     "state": "NY",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2000},
 *     "totalPopulation": 557000,
 *     "state": "FL",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "NY", "year": 2010},
 *     "totalPopulation": 8453000,
 *     "state": "NY",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2010},
 *     "totalPopulation": 4601000,
 *     "state": "CA",
 *     "year": 2010
 *   },
 *   {
 *     "_id": {"state": "CA", "year": 2000},
 *     "totalPopulation": 4480000,
 *     "state": "CA",
 *     "year": 2000
 *   },
 *   {
 *     "_id": {"state": "FL", "year": 2010},
 *     "totalPopulation": 641000,
 *     "state": "FL",
 *     "year": 2010
 *   }
 * ]
 */