Search-based groups

How to set up search-based Smart Groups to automatically promote items matching specific criteria.

Search-based groups let you automatically promote items that match specific criteria, like brand, category, or custom attributes. You define what to promote (with filters), and Algolia determines which items match, applying its AI-powered ranking to ensure the most relevant results appear.

For sponsored listings powered by retail media platforms or external recommendation engines, see external source groups.

Before you begin

• Your Algolia app must use Algolia’s dynamic scaling infrastructure. If your app uses the classic infrastructure, Algolia needs to migrate it. Check with your Customer Success Manager.
• You need to have access to Merchandising Studio to curate the results.
• Your app needs to have the Smart Groups feature and Composition API enabled, according to your plan. If you think you should have access to these features, but you don’t see them available, contact your Account Manager or Customer Success Manager.
• You need to integrate a new API called the Composition API with InstantSearch for the web or with API clients. For details, see Set up your integration.

Rollout and rollback considerations

• Test your implementation on development and testing instances before going to production.
• For A/B testing, consider using replica indices that you use with compositions with and without inserted groups, and then have A/B analytics associated with these indices. Native composition A/B testing is not supported yet.
• Keep your original Search API implementation alongside your Compositions API implementation. This provides an easy rollback option if the Compositions API doesn’t meet your needs.

Create your groups in the Merchandising Studio

Creating groups involves two steps: creating a composition to establish your dynamic results feed (you only need to do this once) and creating composition rules for defining how to insert smart groups into the results feed.

Create compositions

Compositions help you compose dynamic result feeds with more control.

To create your first composition:

1. Go to the Merchandising Studio and open the Merch tools page.

2. Select the Search all compositions and indices menu and click + Create Composition.

   

3. In the New Composition menu, enter a name for this dynamic results feed, and optionally a description. Select which main index should be associated with this results feed.

   

Create one composition per index. If you have different sites, for example, for different geographical regions, create one composition per site and index, such as “Product results feed - US”. Each composition can have rules for the insertion of groups. If you have 5 sites and one product index each, you need 5 compositions. Give each composition a short, descriptive, and unique name, and select its main source index.

If you have different sorting strategies, you also need one composition for each replica (for example, sorted by price from high to low).

After creating your first composition, you can find it in the Search all compositions and indices menu. To list all your compositions and create new ones, go to the Compositions section in the sidebar and click All Compositions.

Create composition rules

To insert a curated group of results for a specific query, category page or collection, define and publish a composition rule.

1. Use the Index and Compositions selector to select the relevant composition. Go to the Merchandising Studio’s Merch tools > Compositions > Composition Rules page.

   In addition to creating and editing Composition Rules in the Merch tools section, you can also use the Visual Merchandiser as an entry point, with the benefit of managing both Composition and Index Rules in a visual, streamlined workflow. To do this, go to the Merchandising Studio’s Visual Merchandiser, select the relevant Composition and search query, category, or collection and then click Actions on the top right.

2. Click + New Composition Rule.

3. In the compositions rules editor, you can configure where to insert your groups given specific conditions, and based on which filters match the group results.

   1. Specify the conditions for triggering your composition rule, for example, search queries, categories, collections and contexts.

      

      You can select several queries, categories, and collections if you want to inject the same groups for them.

   2. Add the groups you would like to create. Select Algolia Index as the data source, then use filters with ‘and’ as well as ‘or’ operations to curate the items that should appear in the group. Specify the group’s starting position in the results, as well as the number of matching records to include.

      

      To add a group from a collection, filter on the _collections attribute.

   3. Save the group and then the composition rule to apply it.

If not enough records match the filter criteria, a group might have fewer items than you specified. The included records can vary at query-time, based on their real-time attribute values as well as applied ranking criteria and index-level rules.

Creating and managing compositions and composition rules is only available through the Merchandising Studio. It’s not yet supported through the HTTP APIs, API clients, or the Algolia dashboard.

Curate groups

You can curate groups further, that is, change the behavior of the query used to retrieve and rank the group’s items, by applying Index Rules to it (for example, for a group with promoted Adidas items, the group’s sub-query might be query=“shoes” and filter: “brand”=“Adidas”).

To learn more about the difference between Composition Rules and Index Rules, see Composition Rules and Index Rules.

For example, you can pin, hide, or boost items within the group:

1. Go to Merchandising Studio’s Visual Merchandiser.
2. Select the corresponding Composition and Search query/Category/Collection where the group’s Composition Rule is applied.
3. Click Actions > Curate “group name” (or find the group in the visual preview, click the three dots, then select “Curate group”).
4. The Index Rule Visual Editor will open, allowing you to define Consequences (for example pin or hide items) for the group’s sub-query.
5. Publish the Index Rule.

The Index Rule is applied to all queries that trigger its conditions—both in the context of the group and in a direct query (in the preceding example other “shoes” queries with the Adidas filter).
The final results might be different to the ones shown in the Index Rules preview, due to the deduplication between the main query and groups. For example, an item might already be part of a previous group and thus not show in the final results in a later group. You may see more items than the ones shown in the final group, when there are more items that match the criteria than the quantity or length of the group is.

Integrate compositions

Integrating compositions and smart groups involves these steps:

1. In the Algolia dashboard, go to Settings > API Keys and copy your application ID and API key. The API key needs at least search permissions for the index used in your composition.

   Client-generated secured API keys aren’t supported for the Composition API.

2. In the Merchandising Studio, go to Merch tools > Compositions > Composition Rules and select the composition from the “Composition or Index” selector. Copy the composition ID to your clipboard.

   

3. Integrate the frontend using one of the integration methods below to query the Composition API (with API clients or InstantSearch for web).

Indexing remains the same, with your previous indexing mechanism (for example, the Search API or indexing connectors). You might need to add extra attributes for identifying groups if this information isn’t already indexed.

Integrate compositions with API clients

Use the Composition API client in one of the supported programming languages.

Swift is not supported yet. The Shopify, Magento, BigCommerce, and Salesforce CommerceCloud (default) frontend integrations don’t yet support the Compositions API.

Integrate compositions with InstantSearch

Start by replacing the Search API client with the Composition API client.

Compositions require these versions of the InstantSearch libraries:

• React InstantSearch: version 7.15.5 or later
• InstantSearch.js: version 4.78.1 or later
• Vue InstantSearch: version 4.20.6 or later

Compositions have the following limitations:

• InstantSearch iOS and InstantSearch Android aren’t supported.
• You can’t use the index widget.
• Combining Composition API and Search API or Recommend API calls on the same page is not supported.
• The Autocomplete UI library is not yet supported. You can’t show groups in autocomplete menus, but you can launch a composition-based search results page from there.

React InstantSearch

React

import React from "react";
import { compositionClient } from "@algolia/composition";
import { InstantSearch } from "react-instantsearch";

const searchClient = compositionClient(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_SEARCH_API_KEY",
);

function App() {
  return (
    <InstantSearch compositionID="COMPOSITION_ID" searchClient={searchClient}>
      {/* Widgets */}
    </InstantSearch>
  );
}

InstantSearch.js

JavaScript

const search = instantsearch({
  compositionID: "COMPOSITION_ID",
  searchClient: compositionClient("APPID", "APIKEY"),
});

// Add widgets
// ...

search.start();

Vue InstantSearch

Vue

<template>
  <ais-instant-search
    composition-id="COMPOSITION_ID"
    :search-client="searchClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
  import { compositionClient } from '@algolia/composition';

  export default {
    data() {
      return {
        searchClient: compositionClient(
          'ALGOLIA_APPLICATION_ID',
          'ALGOLIA_SEARCH_API_KEY'
        ),
      };
    },
  };
</script>

Facets (including disjunctive faceting)

Retrieving a list of facet values for a facet you’re filtering on is called disjunctive faceting. The Composition API natively supports disjunctive faceting.

When querying the Composition API, you can annotate any facet with the disjunctive modifier to get the correct response in a single API request.

For example:

JavaScript

facets: ["disjunctive(attribute)"];

InstantSearch handles this automatically.

Each request has a limit of 20 disjunctive facets. Using facet display in InstantSearch with more than 20 facets is also not supported.

Events setup

When sending click and conversion events, you still need to send the underlying index name as indexName attribute with your events, not the composition ID. No further changes are needed.

InstantSearch’s out-of-box events tracking mechanism handles passing the underlying index name for you, if you’re using the specified versions of the packages.

Next steps

Curate group results

You can still create index rules for pinning, hiding, boosting, or burying results, or to add banners, in combination with composition rules (for example, in the Visual Merchandiser page, or in Merch tools > Ranking Factors > Rules).

Index rules are triggered for the group subquery used to retrieve the best matching records. For more information about how this subquery is formed, see Composition rules and index rules. You can set up an index rule that triggers for the same query, context, or applied filters, to curate the group results, for example, to pin or hide items. The index rule is applied when the group results are retrieved.

Groups and Dynamic Re-Ranking

If enabled on your index, Dynamic Re-Ranking applies to the main results and group subqueries. In other words, the items included in a group are also re-ranked if Dynamic Re-Ranking is turned on for that subquery.

Groups and sorting

You can set up a composition for your replica index. Then, you can curate the replica feed like a regular results feed.

More than one group

By default, groups insert into the final results feed at the specified start position. You can’t have two groups with the same start position. If the specified start position of a group overlaps with positions already taken up by another group with a higher start position, the group is inserted at the next available positions that are not yet taken up by a preceding group at query time. For example, if you have a group A of 3 products configured for start position 1 and a group B of 3 products for position 2, the final results will have products A.1, A.2, A.3, B.1, B.2, B.3 in the first 6 positions, with the main results starting in position 7.

Deduplication across main and group results

Results are deduplicated across main and group results. If there are results that appear in both the main and the group results, the first result in a group is retained. The other duplicates in later groups and the main results are removed.