API Reference / API Parameters / distinct

Jan. 14, 2021

distinct

Type: integer | boolean

Engine default: 0 (no distinct)

Parameter syntax

'distinct' => 0|1|2|3

distinct: 0|1|2|3

distinct: 0|1|2|3

'distinct': 0|1|2|3

distinct = 0|1|2|3

distinct: Distinct = Distinct(0|1|2|3)

new JSONObject()
  .put("distinct", 0|1|2|3)

IndexSettings settings = new IndexSettings();
settings.Distinct = 0|1|2|3;

.setDistinct(Distinct.of(0|1|2|3))

opt.DistinctOf(0|1|2|3)

distinct = Some(Distinct.int(0|1|2|3))

Can be used in these methods:
search, setSettings, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, set_settings, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, setSettings, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, set_settings, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, setSettings, searchForFacetValues, generateSecuredApiKey, addAPIKey, updateAPIKey search, setSettings, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey searchAsync, setSettingsAsync, searchForFacetValues Search, SetSettings, SearchForFacetValues, GenerateSecuredApiKey, AddApiKey, UpdateApiKey Search, setSettings, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, SetSettings, SearchForFacetValues, GenerateSecuredAPIKey, AddAPIKey, UpdateAPIKey search, setSettings, search into facet values, generateSecuredApiKey, add key, update key

See code examples

About this parameter

Enables de-duplication or grouping of results.

Distinct functionality is based on one attribute, as defined in attributeForDistinct. Using this attribute, you can limit the number of returned records that contain the same value in that attribute.

For example, if the distinct attribute is show_name and several hits (episodes) have the same value for show_name (for example “game of thrones”)

if distinct is set to 1 (de-duplication):
- then only the most relevant episode is kept (with respect to the ranking formula); the others are not returned. The direct effect of this is to remove redundant records from your results.
if distinct is set to N > 1 (grouping):
- then the N most relevant episodes for every show are kept, with similar consequences.

Usage notes:

For this setting to work, you need to set the distinct attribute in attributeForDistinct.
When set to 1, you enable de-duplication, in which only the most relevant result is returned for all records that have the same value in the distinct attribute. This is similar to the SQL distinct keyword.
When set to N (where N > 1), you enable grouping, in which most N hits will be returned with the same value for the distinct attribute.
If no distinct attribute is configured, distinct will be accepted at query time but silently ignored.
A 0 value disables de-duplication and grouping.
When using grouping (when distinct > 1):
- the hitsPerPage parameter controls the number of groups that are returned. In the case of jobs and associated companies, if hitsPerPage=10 and distinct=3, up to 30 records will be returned - 10 companies and at most 3 jobs per company. This behavior makes it easy to implement pagination with grouping.
- the nbHits attribute in the response contains the number of groups.
Keep in mind
- Distinct is a computationally expensive operation on large data sets, especially if distinct > 1
- distinct(true) is the same as distinct(1)
- distinct(false) is the same as distinct(0), which is the same thing as not specifying distinct at all

Examples

Set default distinct mode

Copy

1
2
3
4
5
$index->setSettings([
  'distinct' => 0
  // 'distinct' => 1
  // 'distinct' => 2
]);

1
2
3
4
5
6
7
8
9
10
let settings = Settings()
  .set(\.distinct, to: 0)
//.set(\.distinct, to: 1)
//.set(\.distinct, to: 2)

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
IndexSettings settings = new IndexSettings();
settings.Distinct = 0;
// settings.Distinct = 1;
// settings.Distinct = 2;
// settings.distinct = 3;

index.SetSettings(settings);

1
2
3
4
5
6
7
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    distinct = Some(Distinct.int(0))
    // distinct = Some(Distinct.int(1))
    // distinct = Some(Distinct.int(2))
  )
}

Override default distinct mode for the current search

Copy

1
2
3
4
5
$results = $index->search('query', [
  'distinct' => 1
  // 'distinct' => 0
  // 'distinct' => 2
]);

1
2
3
4
5
6
7
8
9
10
let query = Query("query")
  .set(\.distinct, to: 1)
  //.set(\.distinct, to: 0)
  //.set(\.distinct, to: 2)

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
index.search(
      new Query("query").setDistinct(Distinct.of(1))
      // new Query("query").setDistinct(Distinct.of(0))
      // new Query("query").setDistinct(Distinct.of(2))
);

1
2
3
4
5
6
7
8
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    distinct = Some(Distinct.int(1))
    // distinct = Some(Distinct.int(0))
    // distinct = Some(Distinct.int(2))
  )
}

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

distinct

About this parameter

Usage notes:

Examples

Set default distinct mode

Override default distinct mode for the current search

Did you find this page helpful?

On this page