API Reference / API Parameters / distinct
Type: integer | boolean
Engine default: 0 (no distinct)
Parameter syntax
'distinct' => 0|1|2|3

Can be used in these methods:

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, on a TV series site, 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 1 (de-duplication), only the most relevant episode is shown. The others aren’t displayed.
  • If distinct is set to N > 1 (grouping), the N most relevant episodes for every show are displayed.

Usage notes

  • For distinct to work, configure the distinct attribute in attributeForDistinct. If it isn’t configured, distinct will be accepted at query time but silently ignored.
  • A 0 value disables de-duplication and grouping.
  • When using grouping (distinct > 1):
    • The hitsPerPage parameter controls the number of returned groups. For example, on a job search site, if hitsPerPage=10 and distinct=3, up to 30 records will be returned—10 companies and up to 3 jobs per company. This behavior allows you to implement pagination with grouping.
    • The nbHits attribute in the response contains the number of groups.
  • Don’t use grouping (distinct > 1) with promoted records. If you do, the value for nbHits will be wrong and faceting won’t work correctly.
  • 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 as not specifying distinct at all
  • Don’t set <%= parameter_link(‘facetingAfterDistinct’) to true if you don’t have the same facet values in all records sharing the same distinct key (you would get inconsistent results).

Examples

Set default distinct mode

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

Did you find this page helpful?