Skip to main content
Algolia Smart Groups give you precise control over how search results are organized and displayed. You can place groups of items that match specific criteria at specific positions in your search results. Smart Groups streamline curation by applying rules-based results placement logic to entire groups of items, eliminating the need to manually manage individual product positions in your search experience. You can populate Smart Groups in two ways:
  • Search-based groups: you define criteria (like brand or category) and Algolia automatically selects matching items from your index.
  • External source groups: you provide specific objectIDs from an external system (like a retail media platform or recommendation engine).
Both approaches give you precise control over where promoted items appear in results, while automatically handling deduplication, pagination, and faceting.

​
Use cases

​
Monetize with sponsored listings (external source groups)

With external source groups, you can integrate retail media platforms to display sponsored products based on real-time bids from brand partners. This creates a new revenue stream beyond direct product sales. For example, on a search for “running shoes,” you could display two sponsored products from brands bidding through your retail media platform at positions 1 and 5, while showing regular search results on the rest of the page.
Retail media platforms (RMPs), such as Criteo, CitrusAd, and Zitcha, manage sponsored product campaigns, handle ad inventories, bidding, targeting, and reporting. RMPs provide APIs to fetch sponsored products for a search query or category, which you can then inject into your search results at specific positions.

​
Monetize your results grid (search-based groups)

With search-based groups, you can highlight products and content from a preferred brand or partner. Sample scenario: you want to promote a group of products based on a contract with a particular brand, to feature them in top positions on high-grossing categories or queries. For example, for your Footwear category, you can create a group filtered by the brand = Adidas, with 2 items, placed at position 5 in the results grid.

​
Highlight new, trending, on-sale, high-margin results (search-based groups)

Sample scenario: you want to highlight a group of results in promotion, on-sale, new, trending, highly rated, or high-margin products to optimize performance towards your business goals, such as increasing conversion of best sellers or new products or products with high margins. For your Dresses category, you create a group filtered by the attribute = High margin, with 4 items, placed at position 5 in the results grid.

​
Create visual experiences by grouping results (search-based groups)

With Smart Groups, you can create visually cohesive experiences by grouping products or results that share similarities. Sample scenario: you want to highlight autumn colors given the time of year in some categories. For your Women category, you create:
  • A group filtered by the attribute color = brown, with 4 items, placed at position 1 in the results grid
  • A group filtered by attribute color = cream, with 4 items placed at position 5 in the results grid
You can define up to 3 groups per composition. You can mix search-based groups with external source groups in the same composition.

​
Choose your approach

The following table compares search-based groups and external source groups to help you choose the right approach:
Search-based groupsExternal source groups
Best fit when• You have longer-running campaigns or partnerships with specific brands
• You want to apply Algolia’s AI-ranking to choose the most relevant sponsored results for specific queries or categories
• You don’t have a retail media platform (RMP)		• You have an RMP for bidding, reporting, and payments
• You prefer a real-time, bidding-based approach for selecting sponsored results

​
Key concepts

An entity in Algolia that helps you compose results with more control, including to insert groups into regular results. You can think of a composition as a dynamic results feed.
Any ranked results list of search or browse results you have on your website or app. For example, you might have UK product results feeds, a UK content results feed, a UK help results feed, and equivalents for your French website.
A rule that defines when and where to insert Smart Groups, for a given search query, category page, collection, or matching context.
A smart group is a group of results that match certain criteria, inserted in a specific position into the results feed. The API refers to a group as injectedItem.
Search-based groups use Algolia filters to automatically select items that match your criteria. You define what to promote (like brand:Adidas AND in_stock:true), and Algolia finds which items match.Algolia’s AI-powered ranking determines which matching items are most relevant to the user’s query, ensuring promoted items still feel natural in the context of their search.Learn more about search-based groups
External source groups let you specify which items to promote by providing a list of ObjectIDs. These ObjectIDs come from an external system like:
  • Retail media platforms
  • Custom bidding or campaign management systems
Your backend calls the external source, receives objectIDs, then passes them to Algolia’s Composition API. Algolia handles injection, deduplication, and optional re-ranking by relevance.Learn more about external source groups

​
Composition rules and index rules

Index rules apply to both the main results (organic results before group injection) and the group results. Both main and group results are based on subqueries to retrieve and rank the best matching or most relevant records. Each subquery can trigger index rules. A group subquery is based on the top-level query and filters and context of the conditions of the main results query, plus (AND) the filters specified in the group’s applied filters. Explain how sub-requests work Composition rules have higher precedence than index-level rules. For example, if you have an index-level rule to pin a record to position 3 and a group injected also at position 3, the group and its items is placed at position 3 and up (depending on the number of items in the group). The pinned item is placed in the next available position after the group.
You can curate results (for example pin, hide, or further boost certain items) within a group using index rules that apply to the corresponding sub-query. To learn more, see Curate groups.

​
Difference between Smart Groups and pinning and boosting

Pinning records with index-level rules requires you to pin items one-by-one statically. You need to keep your pins up-to-date over time, for example, when an item goes out of stock. In comparison, group injections let you pin a group of items dynamically based on certain attribute criteria. Since it’s based on a subquery search, the most relevant matching product items get selected, and you don’t need to manually keep the items up-to-date. Boosting records with index-level rules is less specific than Smart Groups for controlling how items are placed and their specific positions.

​
Next steps

⌘I