Deduplicate results with distinct

The distinct feature deduplicates search results by grouping that share the same attribute value, so your search results show one representative record per group instead of every matching record. This is useful when:

Handling item variations: if you sell t-shirts and every t-shirt has 10 color variants, show one color variant per design instead of all 10. This helps users discover more products (instead of variants of the same product). You can still show the available colors in the product details.
Indexing long documents: if you split a page into one record per section, a query might return multiple chunks from the same page. With distinct, only the best-matching chunk appears per page or section.

Deduplicate results with distinct

To deduplicate search results, configure both:

attributeForDistinct: the attribute Algolia uses to group records.
distinct: how many records to show from each group.

For example, if you set the url attribute as attributeForDistinct, Algolia groups records with the same url value. If you set distinct to true, Algolia returns only the best matching record from each group. You can also set distinct to a number to return more than one record from each group.

Choose an attribute for grouping

Choose an attribute that has the same value for all records you want to group together. Use an identifier instead of a display value if names, titles, or other aspects can change. For example:

For product variants, use a product identifier such as product_id, design, or sku_group.
For job openings, use company.
For long documents, use url, page_id, or section_id.

To define groups of records based on queries or matching filters, see Smart Groups.

Flatten your records

To use distinct and attributeForDistinct effectively, flatten your records:

Create one record for each searchable item.
Repeat the grouping attribute in each record.

The following example shows the difference between nested and flat record structures.

Nested records

JSON

[
  {
    "objectID": "design-1",
    "name": "Algolia Logo T-Shirt",
    "variants": [
      {
        "color": "red",
        "size": "S",
        "sku": "algolia-logo-red-s"
      },
      {
        "color": "blue",
        "size": "M",
        "sku": "algolia-logo-blue-m"
      }
    ]
  }
]

With this structure, when a query matches one variant, Algolia returns the whole t-shirt design with all its variants. Each record represents a design, not an individual variant. If you want users to search for specific variants, or if you want to show the best matching variant for each design, this structure doesn’t support that use case.

Flattened records

Instead of nested records, create one record for each variant and repeat the design information in each record:

JSON

[
  {
    "objectID": "algolia-logo-red-s",
    "design": "design-1",
    "name": "Algolia Logo T-Shirt",
    "color": "red",
    "size": "S",
    "sku": "algolia-logo-red-s"
  },
  {
    "objectID": "algolia-logo-blue-m",
    "design": "design-1",
    "name": "Algolia Logo T-Shirt",
    "color": "blue",
    "size": "M",
    "sku": "algolia-logo-blue-m"
  }
]

Each flattened record represents a single t-shirt variant. The design attribute identifies variants that belong to the same design, which you can use as the attribute for distinct.

Handle item variations

Consider a shop that sells t-shirts and sweatshirts in different designs and colors. To deduplicate variants by design, create one record for each color variant. The inventory has:

Two t-shirt designs: A and B
Two sweatshirt designs: C and D

Each design comes in different colors.

Diagram that shows t-shirts and sweatshirts grouped by design, with several color variants for each.

Each record contains the type, design, color, and thumbnail image:

JSON

[
  {
    "type": "t-shirt",
    "design": "B",
    "color": "blue",
    "thumbnail_url": "tshirt-B-blue.png"
  },
  {
    "type": "sweatshirt",
    "design": "C",
    "color": "red",
    "thumbnail_url": "sweatshirt-C-red.png"
  }
]

You can add all possible color variations to each record. This makes all variants available for display in your UI, for example, as color swatches below the product thumbnail.

JSON

[
  {
    "type": "t-shirt",
    "design": "B",
    "color": "blue",
    "thumbnail_url": "tshirt-B-blue.png",
    "color_variants": ["orange", "teal", "yellow", "red", "green"]
  },
  {
    "type": "t-shirt",
    "design": "B",
    "color": "orange",
    "thumbnail_url": "tshirt-B-orange.png",
    "color_variants": ["blue", "teal", "yellow", "red", "green"]
  }
]

Having one record per variation lets you add granular custom ranking attributes, such as number_of_sales. Use distinct with design as the attributeForDistinct to show fewer variants per design, so users can browse a wider range of designs.

Configure distinct in the dashboard

After flattening your records, configure distinct to group variants.

Go to the Algolia dashboard and select your Algolia .
On the left sidebar, select Search.
Select your Algolia index.
On the Configuration tab, select Relevance essentials > Searchable attributes.
Click Add a Searchable Attribute and add design, type, and color attributes.
Go to Search behavior > Deduplication and Grouping.
In the Distinct menu, select true.
In the Attribute for Distinct menu, select the design attribute.
Save your changes.

Now, the results include only one color variant per design. To control which variant appears in the results, add an attribute such as number_of_sales and use it in your custom ranking.

Screenshot of search results showing one clothing variant for each design, with color swatches below each item.

Configure distinct with the API

Before deduplicating results, restrict which attributes are searchable. For example, searching the thumbnail_url and color_variants attributes can match queries that aren’t relevant. Set only design, type, and color as searchableAttributes.

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    SearchableAttributes = new List<string> { "design", "type", "color" },
  }
);

Next, use the setSettings method to set design as attributeForDistinct.

To deduplicate all following search requests, set distinct to true with setSettings.

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings { AttributeForDistinct = "design", Distinct = new Distinct(true) }
);

After setting attributeForDistinct, you can also set distinct as a search method parameter:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { Distinct = new Distinct(true) })
);

This deduplicates results only for the current search.