> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# QueryDistinctValues

# Package: cms

# Namespace: DataItemService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-distinct-values.md

## Permission Scopes:
Read Data Items: SCOPE.DC-DATA.READ

## Introduction

Retrieves a list of distinct values for a given field in all items that match a query, without duplicates.


As with the [Query Data Items](https://dev.wix.com/api/rest/wix-data/wix-data/data-items/query-data-items) method, this method retrieves items based on the filtering, sorting, and paging preferences you provide.
However, the Query Distinct Values method doesn't return all of the full items that match the query.
Rather, it returns all unique values of the field you specify in `fieldName` for items that match the query.
If more than one item has the same value for that field, that value appears only once.

Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).

---

## REST API

### Schema

```
 Method: queryDistinctValues
 Description: Retrieves a list of distinct values for a given field in all items that match a query, without duplicates.   As with the [Query Data Items](https://dev.wix.com/api/rest/wix-data/wix-data/data-items/query-data-items) method, this method retrieves items based on the filtering, sorting, and paging preferences you provide. However, the Query Distinct Values method doesn't return all of the full items that match the query. Rather, it returns all unique values of the field you specify in `fieldName` for items that match the query. If more than one item has the same value for that field, that value appears only once.  Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).
 URL: https://www.wixapis.com/wix-data/v2/items/query-distinct-values
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId
 Method parameters: 
   param name: consistentRead | type: consistentRead | description: Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about [Wix Data and eventual consistency](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency).  Default: `false` 
   param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection to query. | required: true
   param name: fieldName | type: fieldName | description: Item field name for which to return all distinct values. 
   param name: filter | type: filter | description: Filter object in the following format:  `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }`.  Examples of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`.  **Note:** The values you provide for each field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: `"someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}`. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-types-in-wix-data.md). 
   param name: language | type: language | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. If provided, the result text is returned in the specified language. **Note:** Translation for the specified language must be enabled for the collection in [Wix Multilingual](https://www.wix.com/app-market/wix-multilingual).  If not provided, result text is not translated. 
   param name: order | type: SortOrder   
      - enum:
           ASC - 
           DESC - 
    - ONE-OF: 
     - name: paging | type: Paging | description: Paging options to limit and skip the number of items. 
        - name: limit | type: integer | description: Number of items to load. 
        - name: offset | type: integer | description: Number of items to skip in the current sort order. 
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. 
        - name: limit | type: integer | description: Number of items to load. 
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. 
   param name: publishPluginOptions | type: PublishPluginOptions   
        - name: includeDraftItems | type: boolean | description: Whether to include draft items.  When `true`, both published and draft items are affected. Default: `false`. 
   param name: returnTotalCount | type: returnTotalCount | description: Whether to return the total count in the response for a query with offset paging. When `true`, the `pagingMetadata` object in the response contains a `total` field.  Default: `false` 
 Return type: QueryDistinctValuesResponse
  - name: distinctValues | type: array<Value> | description: List of distinct values contained in the field specified in `fieldName`. 
     - ONE-OF: 
        - name: nullValue | type:  | description:  
        - name: numberValue | type: number | description:  
        - name: stringValue | type: string | description:  
        - name: boolValue | type: boolean | description:  
        - name: structValue | type: object | description:  
        - name: listValue | type: ListValue | description:  
           - name: values | type: array<Value> | description:  
  - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: offset | type: integer | description: Offset that was requested. 
     - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. 
     - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. 
     - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. 
        - name: next | type: string | description: Cursor pointing to next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results. 


```

### Examples

### Query filtered distinct cities sorted in ascending order, calculate the total count of the result set.
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/query-distinct-values' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "fieldName": "city",
    "filter": {
        "state": "California"
    },
    "order": "ASC",
    "returnTotalCount": true
}'
```

### Query distinct cities
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/items/query-distinct-values' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "cities",
    "fieldName": "city"
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.cms.DataItemService.queryDistinctValues(dataCollectionId, fieldName, options)
 Description: Retrieves a list of distinct values for a given field in all items that match a query, without duplicates.   As with the [Query Data Items](https://dev.wix.com/api/rest/wix-data/wix-data/data-items/query-data-items) method, this method retrieves items based on the filtering, sorting, and paging preferences you provide. However, the Query Distinct Values method doesn't return all of the full items that match the query. Rather, it returns all unique values of the field you specify in `fieldName` for items that match the query. If more than one item has the same value for that field, that value appears only once.  Learn more about [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, fieldName
 Method parameters: 
   param name: dataCollectionId | type: string | description: GUID of the collection to query. | required: true
   param name: fieldName | type: string | description: Item field name for which to return all distinct values. | required: true
   param name: options | type: WixDataDistinctOptions  none 
        - name: filter | type: object | description: Filter object in the following format:  `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }`.  Examples of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`.  **Note:** The values you provide for each field must adhere to that field's type. For example, when filtering by a field whose type is Date and Time, use an object in the following format: `"someDateAndTimeFieldKey": { "$date": "YYYY-MM-DDTHH:mm:ss.sssZ"}`. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-types-in-wix-data.md). 
        - name: order | type: SortOrder | description: Sort order. 
             - enum: ASC, DESC
        - name: returnTotalCount | type: boolean | description: Whether to return the total count in the response for a query with offset paging. When `true`, the `pagingMetadata` object in the response contains a `total` field.  Default: `false` 
        - name: consistentRead | type: boolean | description: Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about [Wix Data and eventual consistency](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency).  Default: `false` 
        - name: language | type: string | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. If provided, the result text is returned in the specified language. **Note:** Translation for the specified language must be enabled for the collection in [Wix Multilingual](https://www.wix.com/app-market/wix-multilingual).  If not provided, result text is not translated. 
        - name: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. 
        - name: suppressHooks | type: boolean | description: Prevents hooks from running for the operation. Can only be used in the [backend code of a Wix site](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/about-the-site-backend.md). 
        - name: appOptions | type: object | description: Options for [querying Wix app collections](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-app-collections/querying-wix-app-collections.md). 
        - name: paging | type: Paging | description: none 
           - name: limit | type: integer | description: none 
           - name: offset | type: integer | description: none 
        - name: cursorPaging | type: CursorPaging | description: none 
           - name: cursor | type: string | description: Cursor token pointing to a page of results. 
           - name: limit | type: integer | description: Maximum number of items to return. 
 Return type: PROMISE<QueryDistinctValuesResponse>
  - name: distinctValues | type: array<Value> | description: List of distinct values contained in the field specified in `fieldName`. 
     - ONE-OF: 
        - name: nullValue | type:  | description:  
        - name: numberValue | type: number | description:  
        - name: stringValue | type: string | description:  
        - name: boolValue | type: boolean | description:  
        - name: structValue | type: object | description:  
        - name: listValue | type: ListValue | description:  
           - name: values | type: array<Value> | description:  
  - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: offset | type: integer | description: Offset that was requested. 
     - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. 
     - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. 
     - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. 
        - name: next | type: string | description: Cursor pointing to next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results. 


```

### Examples

### distinct
```javascript
import { items } from '@wix/data';

async function distinct(dataCollectionId,fieldName,options) {
  const response = await items.distinct(dataCollectionId,fieldName,options);
};
```

### distinct (with elevated permissions)
```javascript
import { items } from '@wix/data';
import { auth } from '@wix/essentials';

async function myDistinctMethod(dataCollectionId,fieldName,options) {
  const elevatedDistinct = auth.elevate(items.distinct);
  const response = await elevatedDistinct(dataCollectionId,fieldName,options);
}
```

### distinct (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { items } from '@wix/data';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { items },
  // Include the auth strategy and host as relevant
});


async function distinct(dataCollectionId,fieldName,options) {
  const response = await myWixClient.items.distinct(dataCollectionId,fieldName,options);
};
```

---