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

# Compositions

> Combine results from multiple indices, content types, and data sources into a single response.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const feedDefinition = "Group of items used in a composition. Sources can be search results, recommendations, or external data.";

export const Feed = () => <Tooltip tip="Group of items used in a composition. Sources can be search results, recommendations, or external data." href="/doc/guides/compositions/multifeed-compositions" cta="Multifeed compositions">
    feed
  </Tooltip>;

export const organicResultsDefinition = "These are the search results ranked by relevance and your configuration without compositions.";

export const OrganicResults = () => <Tooltip tip={organicResultsDefinition} cta="Smart Groups" href="/doc/guides/managing-results/compositions/smart-groups">
    organic results
  </Tooltip>;

The Composition API lets you combine results from multiple indices, content types and data sources into a single response. Use it to build federated search, category pages, and dynamic experiences where curated or sponsored content needs to appear alongside <OrganicResults />. Manage compositions in the Algolia dashboard and render them with InstantSearch. Update experiences without changing frontend code.

## What you can do with compositions

* **Compose results from multiple sources:** combine multiple indices, content types and data sources in a single request; no frontend orchestration needed.
* **Inject [Smart Groups](/doc/guides/compositions/smart-groups/smart-groups):** place curated product groups at specific positions within organic results. Inject sponsored content, trending items, brand partnerships and more.
* **Scalable orchestration:** complex orchestration logic lives within the composition. Frontend teams can focus on creating the best possible rendering and experience for their customers.

## When to use compositions

Use the Composition API when you need to return multiple result sets in one request, inject dynamic sponsored results at specific locations, build collections and category pages or federated search experiences.

## Key concepts

<AccordionGroup>
  <Accordion title="Composition">
    A composition combines results from multiple sources into one response, so your frontend can query a single endpoint instead of searching each source separately.
  </Accordion>

  <Accordion title="Feed">
    {feedDefinition}
  </Accordion>

  <Accordion title="Composition rule">
    Defines when and where groups are injected, triggered by a query, catalog, or collection.
  </Accordion>

  <Accordion title="Smart Group">
    A defined set of results matching specific attribute criteria, injected at a chosen position within an organic results feed.
  </Accordion>

  <Accordion title="Category page">
    A product landing page built from a search request with applied filters.
  </Accordion>

  <Accordion title="Collection">
    Curated product listings. You can create a collection by manually selecting records or defining them using conditions.
  </Accordion>

  <Accordion title="Organic results">
    {organicResultsDefinition}
  </Accordion>

  <Accordion title="Search-based groups">
    [Search-based groups](https://algolia.com/doc/guides/compositions/smart-groups/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.
  </Accordion>

  <Accordion title="External source groups">
    [External source groups](https://algolia.com/doc/guides/compositions/smart-groups/external-source-groups) let you specify which items to promote by providing a list of object IDs. These object IDs 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.
  </Accordion>

  <Accordion title="Recommend-based groups">
    [Recommend-based groups](https://algolia.com/doc/guides/compositions/smart-groups/recommend-based-groups) let you populate a group with items returned by an [Algolia Recommend](https://algolia.com/doc/guides/algolia-recommend/overview) model. You configure them through the Composition API by setting the group source to `recommend`.
  </Accordion>
</AccordionGroup>

## Before you begin using the Compositions API

Before using the Composition API, make sure your setup meets these requirements:

* Your Algolia application must use Algolia's [dynamic scaling infrastructure](/doc/guides/scaling/infrastructure/dynamic/dynamic). If your application uses [classic infrastructure](/doc/guides/scaling/infrastructure/classic/servers-clusters), it must be migrated (contact your Algolia customer success manager or the [support team](https://support.algolia.com/hc/en-us/requests/new)).
* You must have access to [Merchandising Studio](/doc/guides/managing-results/rules/merchandising-and-promoting#merchandising-studio) to curate results.
* Your application must have the Composition API and Smart Groups enabled. If you think your plan includes these features but you can't access them, contact your Algolia account manager, customer success manager, or the [support team](https://support.algolia.com/hc/en-us/requests/new).
* [Multifeed compositions](/doc/guides/compositions/multifeed-compositions) require additional access. To request it, contact your Algolia customer success manager.