Get started

Before you begin

• Your Algolia app will need to be hosted in Algolia’s dynamic scaling infrastructure. If your app is using the classic infrastructure, it needs to be migrated by Algolia. 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 or category page, 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.

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, and contexts.

      

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

   2. Add the groups you would like to create. You can 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 overall results, as well as the number of matching records to include.

      

   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.

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 are not yet supported for the Composition API, that is, you can’t restrict the usage to specific indices or rate limits.

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 these programming languages:

• C#
• Dart
• Go
• Java
• JavaScript
• Kotlin
• PHP
• Python
• Ruby
• Scala

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. Then follow the instructions below depending on your flavor of InstantSearch.

Compositions have the following limitations:

• InstantSearch iOS and InstantSearch Android are not 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 (starting v7.15.5)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import React from 'react';
import { compositionClient } from '@algolia/composition';
import { InstantSearch } from 'react-instantsearch';

const searchClient = compositionClient(
  'YourApplicationId',
  'YourSearchOnlyAPIKey'
);

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

InstantSearch.js (starting v4.78.1)

1
2
3
4
5
6
7
8
9
10
11
12
const search = instantsearch({
  compositionID: 'COMPOSITION_ID',
  searchClient: compositionClient(
    'APPID',
    'APIKEY'
  ),
});

// Add widgets
// ...

search.start();

Vue InstantSearch (starting v4.20.6)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<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(
          'YourApplicationID',
          'YourSearchOnlyAPIKey'
        ),
      };
    },
  };
</script>

Facets (incl. disjunctive faceting)

Retrieving a list of facet values for a facet you’re filtering on is called disjunctive faceting. The Composition API has native support for 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:

1
2
3
facets: [
  'disjunctive(attribute)'
]

InstantSearch handles this automatically for you.

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.

Multiple groups

By default, groups are inserted in 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.