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

# Algolia Ingestion

> Route Magento indexing through Algolia's Ingestion Platform for pre-indexing transformations, up-to-date Collections, and run and event observability.

Algolia Ingestion is an optional companion module for the Algolia AI Search & Discovery extension.
When enabled, it routes your indexing operations through Algolia's
[Ingestion Platform](/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/overview)
instead of writing directly to your Algolia indices.

Routing through Ingestion unlocks platform capabilities that aren't available on the direct write path:
pre-indexing transformations, up-to-date Collections, and observability of every indexing operation.

The module is available starting with version 3.19 of the extension.
It's a separate package, so it isn't part of the core install.
Ingestion is turned off by default: until you turn it on, the extension keeps writing directly to Algolia
and the module stays out of the way.

## What you get

* **Pre-indexing transformations.**
  Reshape records with JavaScript before they land in the index.
  You author and manage these in the Algolia dashboard.
  See [Transform your data with code](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data-with-code).
* **Collections that stay up to date.**
  Sending record updates through the pipeline keeps your
  [Collections](/doc/guides/solutions/ecommerce/browse/tutorials/collections#ensure-collections-remain-up-to-date)
  current as your catalog changes, instead of waiting for the periodic reindex.
  The backend hooks that maintain Collections only run on the Ingestion path.
  With direct indexing, they're never called.
* **Observability.**
  Every indexing operation appears in the Ingestion runs and events views,
  so you can inspect exactly what was sent and what happened to it.

If you're new to the underlying concepts, the
[push connector](/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push)
documentation explains how Algolia models data ingestion as a pipeline.
This page focuses on installing, configuring, and using it from the extension.

## Requirements

* PHP 8.3 or later (8.3, 8.4, and 8.5 are supported).
* Adobe Commerce or Magento Open Source 2.4 or later.
* The Algolia AI Search & Discovery extension, version 3.19 or later.
  The send path that Ingestion plugs into was introduced in 3.19.
* Algolia credentials already configured for the extension.
  Ingestion reuses the same application ID and Admin API key.

## Install the module

<Steps>
  <Step title="Install with Composer">
    ```sh icon="square-terminal" theme={"system"}
    composer require algolia/algoliasearch-ingestion-magento-2
    php bin/magento module:enable Algolia_Ingestion
    php bin/magento setup:upgrade
    php bin/magento setup:di:compile
    php bin/magento cache:flush
    ```

    `setup:upgrade` creates the local table that caches the Ingestion pipeline for each store and index,
    so the extension doesn't have to resolve it on every operation.
  </Step>

  <Step title="Enable Algolia Ingestion">
    Go to **Stores > Configuration > Algolia Search > Indexing Manager > Algolia Ingestion**
    and set **Enable Algolia Ingestion** to **Yes** for the scopes that should use it.
  </Step>
</Steps>

<Note>
  Configure your Algolia credentials at
  **Stores > Configuration > Algolia Search > Credentials and Basic Setup** before enabling Ingestion.
  The module reuses the same application ID and Admin API key as the extension.
</Note>

## Configure

All settings live under
**Stores > Configuration > Algolia Search > Indexing Manager > Algolia Ingestion**.
You can set each one at the default, website, or store view level,
so you can enable Ingestion for some stores and not others.

| Setting                                  | Default      | Description                                                                                            |
| ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| **Enable Algolia Ingestion**             | No           | Routes indexing through the Ingestion Platform. When off, indexing is sent directly to Algolia.        |
| **Region**                               | America (US) | The Ingestion Platform region: America (US) or Europe (EU). This must match your application's region. |
| **Fallback to direct indexing on error** | Yes          | If a push fails, fall back to direct indexing instead of raising an error.                             |

Changing your credentials or region automatically clears the cached pipeline,
so the next indexing operation re-resolves against the new target.

## Set the correct region

<Warning>
  The **Region** setting must match the true region of your Algolia application.
  This is the single most important setting to get right.
</Warning>

The Ingestion Platform derives its host from the region string alone and never validates it
against your application. A mismatch is a silent failure: records still reach the index in your
application's home region, so indexing appears to work, but the connector configuration is stranded
in the wrong region's control plane. It's invisible in your dashboard, which means you can't attach
transformations or inspect runs and events for it.

If you run stores against applications in different regions,
set the region per store scope and confirm each store's connector appears in the matching regional dashboard.

## How indexing flows through the pipeline

The Ingestion Platform models indexing as a pipeline:

```
Source ──► Task ──► Transformation ──► Destination
(push)                   (optional)           (search index)
```

* **Source** receives records pushed from your store.
* **Task** binds a source to a destination and is what the extension actually pushes to.
* **Transformation** is optional JavaScript that reshapes records before they're indexed.
* **Destination** is the target Algolia index, paired with the credentials to write to it.

You don't have to build this pipeline by hand. For each store and index, the module resolves a task:
it first checks its local cache, then looks for an existing pipeline in your Algolia application,
and finally creates whatever pieces are missing. The resolved task is cached locally so later
operations skip the lookup. The module tracks whether it created a pipeline or reused one you already
own, so the cleanup command only ever removes resources it created.

Standard indices (products, categories, pages, and Query Suggestions) are resolved up front by the
[`algolia:ingestion:init`](#cli-commands) command. Any additional section indices resolve lazily the
first time they're pushed.

## Collections support

Enabling Ingestion is what makes backend
[Collections](/doc/guides/solutions/ecommerce/browse/tutorials/collections) work with the extension.
Collections rely on transformation hooks that run as records pass through the Ingestion pipeline.
On the direct write path those hooks are never called, so Collections aren't populated from the backend.

Define your transformations and Collections in the Algolia dashboard.
The module handles delivery to the pipeline. The transformation logic lives in Algolia.

<Note>
  When Ingestion writes index settings (such as the facet attributes a transformation manages),
  version 3.19 of the extension preserves those externally managed settings on the next reindex
  instead of overwriting them.
</Note>

## Fallback behavior

The **Fallback to direct indexing on error** setting controls what happens when a push can't be delivered,

for example if the task has been disabled in the Algolia dashboard.

* **Enabled (default):** the operation falls back to direct indexing, so indexing never silently stops.
* **Disabled:** the error is raised and the operation fails loudly.

Keep fallback enabled unless you specifically want indexing to fail when the pipeline is unavailable.

## When a task is disabled in Algolia

You can disable a task in the Algolia dashboard at any time, without changing anything in your store.
The extension treats a disabled task as a deliberate choice, not as a broken or missing pipeline:

* It keeps its link to the task, so indexing resumes on its own once you re-enable the task.
  You don't need to run a command or clear a cache.
* It won't recreate the task or quietly reroute your data through a different one.
* What happens to indexing in the meantime depends on your **Fallback to direct indexing on error** setting.
  With fallback on (the default), records keep reaching Algolia through direct indexing.
  With fallback off, indexing operations fail until you re-enable the task.

A disabled task is different from a deleted one.
If a task is deleted, the extension notices it no longer exists and rebuilds the pipeline on the next operation.
A disabled task still exists, so the extension leaves it untouched and waits for you to re-enable it.

<Tip>
  When logging is enabled, the extension writes a warning to `var/log/algolia.log`
  reminding you to re-enable the task in the Algolia dashboard.
</Tip>

## CLI commands

The module adds three commands under the `algolia:ingestion:` namespace.
Each takes an optional list of store IDs. With none supplied, the command operates on all enabled stores.

Warm the pipeline cache for the standard indices on each store. It's idempotent, so indices that are
already cached are skipped:

```sh icon="square-terminal" theme={"system"}
php bin/magento algolia:ingestion:init        # all enabled stores
php bin/magento algolia:ingestion:init 1 2    # only stores 1 and 2
```

Display the cached pipeline per store and index, including the task ID and when it was created.
This command is read-only:

```sh icon="square-terminal" theme={"system"}
php bin/magento algolia:ingestion:status
```

Clear the local pipeline cache so the next operation re-resolves it.
By default this changes nothing in Algolia. Add `--api-cleanup` to also remove the matching
Algolia-side resources. The command previews the plan first and only deletes resources the module owns.
Use `--force` to skip the confirmation prompt:

```sh icon="square-terminal" theme={"system"}
php bin/magento algolia:ingestion:reset                 # clear cache for all stores (prompts)
php bin/magento algolia:ingestion:reset 2               # clear cache for store 2
php bin/magento algolia:ingestion:reset --api-cleanup   # preview, then tear down owned resources
php bin/magento algolia:ingestion:reset 2 --api-cleanup --force
```

## Logging and troubleshooting

Enable logging at
**Stores > Configuration > Algolia Search > Credentials and Basic Setup > Enable Logging**
and watch `var/log/algolia.log` for push responses, retries, and fallback events.
For more on diagnosing indexing issues, see
[Logging and debugging](/doc/integration/magento-2/customize/logging-and-debugging).

<Tip>
  The module ships with a Postman collection for the Ingestion API.
  It's the fastest way to confirm which resources exist in a given region's control plane,
  for example when diagnosing a region mismatch, without going through your store.
</Tip>