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

Can be used in these methods:

About this parameter

Deduplicate or group results.

With distinct, you can limit the number of duplicate records: those with the same attributeForDistinct value.

The distinct attribute can be one of the following values:

  • Deduplication. distinct is 1 or true. Only the most relevant variant is shown for each group.
  • Grouping. distinct is a number N greater than 1. For each group, the N most relevant variants are shown.
  • No deduplication (default). distinct is 0 or false. All matching results are shown.

Usage notes

The distinct attribute works in combination with attributeForDistinct:

  • attributeForDistinct establishes groups: all records with the same value of attributeForDistinct are treated as a group.
  • distinct determines how many variants per group are included in the search results.

If attributeForDistinct isn’t set, no error is generated and the distinct setting is ignored.


If you’re using distinct in combination with faceting, use the afterDistinct modifier when declaring your attributesForFaceting. This lets Algolia compute faceting after deduplication, which results in accurate facet counts.


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.

When using grouping:

  • The hitsPerPage parameter controls the number of returned groups. For example, if hitsPerPage=10 and distinct=3, up to 30 records are returned: 10 distinct groups with up to 3 variants per group. This lets you implement pagination with grouping.
  • The nbHits attribute in the response contains the number of groups.

Don’t set distinct to values higher than 4. High distinct values makes your search a lot slower.


Set a default distinct mode

The following example uses setSettings to deduplicate records for all searches: For all records with the same value for the url attribute, only 1 record is shown.

  'distinct' => 1,
  'attributeForDistinct' => 'url'

The following example overrides the default behavior and turns off deduplication: all matching records are shown.

$results = $index->search('query', [
  'distinct' => 0
Did you find this page helpful?