distinct( )

Returns the distinct values that match the query, without duplicates.

Description

The distinct() function returns a Promise that resolves to:

The distinct values found in the specified field when running the query.
Additional information about the results, such as the number of values that match the query.

Unlike find(), which returns all item objects that match the query, distinct() returns matching field values, and eliminates duplicate field values from the query result. You cannot use find() and distinct() together.

For an item to be resolved as distinct, only the specified field must be distinct. Other fields for that item in the collection are not evaluated when resolving the promise.

The Promise is rejected if distinct() is called with incorrect permissions or if any of the functions used to refine the query is invalid.

Note: Only site visitors with Data Read permissions can retrieve and view data. You can override the permissions by setting the suppressAuth option to true.

Syntax

function distinct(propertyName: string, [options: WixDataQueryOptions]): Promise<WixDataQueryResult>

distinct Parameters

NAME

TYPE

DESCRIPTION

propertyName

string

The property whose value will be compared for distinct values.

options

Optional

WixDataQueryOptions

An object containing options to use when processing this operation.

Returns

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

Return Type:

Promise<WixDataQueryResult>

Was this helpful?

Get distinct values from a query

This example demonstrates how to run a distinct() on a query() that was previously built and stored in a variable.

Copy Code

1query.distinct("state")
2  .then((results) => {
3    if(results.items.length > 0) {
4      let items = results.items;
5      let firstItem = items[0];
6      let totalCount = results.totalCount;
7      let pageSize = results.pageSize;
8      let currentPage = results.currentPage;
9      let totalPages = results.totalPages;
10      let hasNext = results.hasNext();
11      let hasPrev = results.hasPrev();
12      let length = results.length;
13      let query = results.query;
14    } else {
15      // handle case where no matching items found
16    }
17  })
18  .catch((error) => {
19    let errorMsg = error.message;
20    let code = error.code;
21  });
22

Create a distinct query and run it

This example demonstrates how to build a query() and then run distinct() on it.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.query("myCollection")
6  .distinct("state")
7  .then((results) => {
8    if(results.items.length > 0) {
9      let items = results.items;
10      let firstItem = items[0];
11      let totalCount = results.totalCount;
12      let pageSize = results.pageSize;
13      let currentPage = results.currentPage;
14      let totalPages = results.totalPages;
15      let hasNext = results.hasNext();
16      let hasPrev = results.hasPrev();
17      let length = results.length;
18      let query = results.query;
19    } else {
20      // handle case where no matching items found
21    }
22  })
23  .catch((error) => {
24    let errorMsg = error.message;
25    let code = error.code;
26  });
27

Create a query, add functions to the query, and find distinct values

This example demonstrates how to build a query(), chain additional functions such as eq() and gt() to the query, and then run the distinct().

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.query("myCollection")
6  .eq("status", "active")
7  .gt("age", 25)
8  .distinct("state")
9  .then((results) => {
10    if (results.items.length > 0) {
11      let items = results.items;
12      let firstItem = items[0];
13      let totalCount = results.totalCount;
14      let pageSize = results.pageSize;
15      let currentPage = results.currentPage;
16      let totalPages = results.totalPages;
17      let hasNext = results.hasNext();
18      let hasPrev = results.hasPrev();
19      let length = results.length;
20      let query = results.query;
21    } else {
22      // handle case where no matching items found
23    }
24  })
25  .catch((error) => {
26    let errorMsg = error.message;
27    let code = error.code;
28  });
29

Create a distinct query with options and run it

This example demonstrates how to build a query() and then run distinct() bypassing permission checks. Note that the options parameter can only be used in backend code.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let options = {
6    "suppressAuth": true
7};
8
9wixData.query("myCollection")
10  .distinct("state", options)
11  .then((results) => {
12    if(results.items.length > 0) {
13      let items = results.items;
14      let firstItem = items[0];
15    } else {
16      // handle case where no matching items found
17    }
18  })
19  .catch((error) => {
20    let errorMsg = error.message;
21    let code = error.code;
22  });
23