> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# distinct

> How many variants of each group of records are included in the results

export const Setting = ({type, default: defaultValue, defaultNote, scope, min, max, formerly}) => {
  const renderedDefault = defaultValue === '' ? '""' : defaultValue;
  const renderedNote = defaultNote ? `(${defaultNote})` : '';
  return <ul>
      <li><strong>Type:</strong> <code>{type}</code></li>
      <li><strong>Default:</strong> <code>{renderedDefault}</code>{renderedNote}</li>
      {min && <li><strong>Min:</strong> <code>{min}</code></li>}
      {max && <li><strong>Max:</strong> <code>{max}</code></li>}
      <li><strong>Scope:</strong> <a href="/doc/api-reference/api-parameters"><code>{scope}</code></a></li>
      {formerly && <li>
          <strong>Deprecated name:</strong> <code>{formerly}</code>
        </li>}
    </ul>;
};

<Setting type="enum<integer> | boolean" default="false" scope="settings,search" />

The `distinct` parameter controls how many variants of a record are shown
when multiple records share the same value for the attribute defined in
[`attributeForDistinct`](/doc/api-reference/api-parameters/attributeForDistinct).

This lets you group and deduplicate search results.

## Options

<ParamField path="false | 0">
  No grouping or deduplication. All matching records are shown.\
  This is the default.
</ParamField>

<ParamField path="true | 1">
  Returns only the most relevant record from each group.
  This is useful when you want to show one result per unique product, article, or listing.

  Only the most relevant variant is shown for each record group.
</ParamField>

<ParamField path="2 | 3 | 4">
  Returns the top 2, 3, or 4 records for each group.

  * Avoid grouping with [promoted records](/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/promote-hits),
    as this can lead to wrong `nbHits` values and broken faceting.
  * When `distinct` is greater than 1:

    * [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) controls the number of **groups**.
    * Up to `hitsPerPage × distinct` total hits can be returned.
    * The response field `nbHits` reflects the **number of groups**, not total records.

  <Warning>
    Don't set `distinct` to values higher than 4,
    as this significantly reduces search performance.
  </Warning>
</ParamField>

## Usage

* `attributeForDistinct` defines how records are grouped.
* `distinct` defines how many records per group are shown.
* If `attributeForDistinct` isn't set, `distinct` is ignored.
* To ensure accurate facet counts when `distinct` is applied,
  use the [`afterDistinct`](/doc/api-reference/api-parameters/attributesForFaceting#param-after-distinct)
  modifier when declaring `attributesForFaceting`.

## Example

<AccordionGroup>
  <Accordion title="Current API clients" defaultOpen="true">
    <CodeGroup>
      ```cs C# theme={"system"}
      var response = await client.SetSettingsAsync(
        "INDEX_NAME",
        new IndexSettings { Distinct = new Distinct(1), AttributeForDistinct = "url" }
      );
      ```

      ```dart Dart theme={"system"}
      final response = await client.setSettings(
        indexName: "INDEX_NAME",
        indexSettings: IndexSettings(
          distinct: 1,
          attributeForDistinct: "url",
        ),
      );
      ```

      ```go Go theme={"system"}
      response, err := client.SetSettings(client.NewApiSetSettingsRequest(
        "INDEX_NAME",
        search.NewEmptyIndexSettings().SetDistinct(search.Int32AsDistinct(1)).SetAttributeForDistinct("url")))
      if err != nil {
        // handle the eventual error
        panic(err)
      }
      ```

      ```java Java theme={"system"}
      UpdatedAtResponse response = client.setSettings(
        "INDEX_NAME",
        new IndexSettings().setDistinct(Distinct.of(1)).setAttributeForDistinct("url")
      );
      ```

      ```js JavaScript theme={"system"}
      const response = await client.setSettings({
        indexName: 'theIndexName',
        indexSettings: { distinct: 1, attributeForDistinct: 'url' },
      });
      ```

      ```kotlin Kotlin theme={"system"}
      var response =
        client.setSettings(
          indexName = "INDEX_NAME",
          indexSettings = IndexSettings(distinct = Distinct.of(1), attributeForDistinct = "url"),
        )
      ```

      ```php PHP theme={"system"}
      $response = $client->setSettings(
          'INDEX_NAME',
          ['distinct' => 1,
              'attributeForDistinct' => 'url',
          ],
      );
      ```

      ```python Python theme={"system"}
      response = client.set_settings(
          index_name="INDEX_NAME",
          index_settings={
              "distinct": 1,
              "attributeForDistinct": "url",
          },
      )
      ```

      ```ruby Ruby theme={"system"}
      response = client.set_settings(
        "INDEX_NAME",
        Algolia::Search::IndexSettings.new(distinct: 1, attribute_for_distinct: "url")
      )
      ```

      ```scala Scala theme={"system"}
      val response = Await.result(
        client.setSettings(
          indexName = "INDEX_NAME",
          indexSettings = IndexSettings(
            distinct = Some(Distinct(1)),
            attributeForDistinct = Some("url")
          )
        ),
        Duration(100, "sec")
      )
      ```

      ```swift Swift theme={"system"}
      let response = try await client.setSettings(
          indexName: "INDEX_NAME",
          indexSettings: IndexSettings(attributeForDistinct: "url", distinct: SearchDistinct.int(1))
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Legacy API clients">
    <CodeGroup>
      ```cs C# theme={"system"}
      IndexSettings settings = new IndexSettings();
      settings.Distinct = 1;
      settings.AttributeForDistinct = "url";

      index.SetSettings(settings);
      ```

      ```go Go theme={"system"}
      res, err := index.SetSettings(search.Settings{
      	Distinct:             opt.DistinctOf(1),
      	AttributeForDistinct: opt.AttributeForDistinct("url"),
      })
      ```

      ```java Java theme={"system"}
      index.setSettings(
        new IndexSettings()
          .setDistinct(Distinct.of(1))
          .setAttributeForDistinct("url")
      );
      ```

      ```js JavaScript theme={"system"}
      index
        .setSettings({
          distinct: 1,
          attributeForDistinct: "url",
        })
        .then(() => {
          // done
        });
      ```

      ```kotlin Kotlin theme={"system"}
      val query = settings {
          distinct = Distinct(1)
          attributeForDistinct = Attribute("url")
      }

      index.setSettings(query)
      ```

      ```php PHP theme={"system"}
      $index->setSettings([
        'distinct' => 1,
        'attributeForDistinct' => 'url'
      ]);
      ```

      ```python Python theme={"system"}
      index.set_settings({"distinct": 1, "attributeForDistinct": "url"})
      ```

      ```ruby Ruby theme={"system"}
      index.set_settings(
        {
          distinct: 1,
          attributeForDistinct: "url"
        }
      )
      ```

      ```scala Scala theme={"system"}
      client.execute {
        setSettings of "myIndex" `with` IndexSettings(
          distinct = Some(Distinct.int(1))
          attributeForDistinct = Some("url")
        )
      }
      ```

      ```swift Swift theme={"system"}
      let settings = Settings()
        .set(\.distinct, to: 1)
        .set(\.attributeForDistinct, to: "url")

      index.setSettings(settings) { result in
        if case .success(let response) = result {
          print("Response: \(response)")
        }
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>