Skip to main content

$distinct

Functionality​

Definition​

The $distinct endpoint enables you to return a collection containing the distinct values for a query on a specific attribute. You can specify only one attribute in the dataclass for this operation. This parameter works best with attributes of type String, but it can also be used with any attribute type that can contain multiple values.

Syntax​

To retrieve distinct values for an attribute, use the following format:

GET /rest/{{dataClass}}/{{attribute}}?$filter="{{filterExpression}}"&$distinct=true

You can also use $skip and $top/$limit parameters to navigate the selection before it's placed in an array.

Combining with Other Parameters​

The $distinct parameter can be combined with other parameters to refine the query:

  • $filter: Narrow down the data set before retrieving distinct values.

  • $orderby: Sort the distinct values before returning them.

  • $top/$limit and $skip: Limit the number of distinct records and skip a certain number of distinct records.

  • $expand: Include related data along with distinct values.

  • $attributes: Specify which attributes to include in the response with distinct values.

  • $method=entityset: Create an entity set based on distinct results and save it in the server's cache.

Use Cases​

Retrieve Distinct Values for a String Attribute​

Request:

GET /rest/Users/Name?$filter="Name=J@"&$distinct=true

Response:

[
    "John",
    "James"
]

Retrieve Distinct Values with Pagination​

Request:

GET /rest/Users/Name?$filter="Name=J*"&$distinct=true&$skip=1&$top=1

Response:

[
    "John"
]

Retrieve Distinct Values for a Numerical Attribute​

Request:

GET /rest/Employee/salary?$distinct=true

Response:

[
    50000,
    60000,
    70000
]

Retrieve Distinct Values for an Object Attribute's Property​

Request:

GET /rest/Employee/address.city?$distinct=true

Response:

[
    "New York",
    "Los Angeles",
    "Chicago"
]

Best Practices​

  • Specify Only Necessary Filters: Use the $filter parameter to limit the dataset to relevant entries, which helps in optimizing performance and reducing payload size.

  • Combine with Pagination: Use $skip and $top/$limit to manage large result sets effectively and implement pagination.

  • Handle Errors Gracefully: Implement proper error handling to manage cases where the distinct operation cannot be performed or data cannot be retrieved.