Skip to main content
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 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.
  • Collections that stay up to date. Sending record updates through the pipeline keeps your Collections 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 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

1

Install with Composer

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.
2

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.
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.

​
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. 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

The Region setting must match the true region of your Algolia application. This is the single most important setting to get right.
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 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 command. Any additional section indices resolve lazily the first time they’re pushed.

​
Collections support

Enabling Ingestion is what makes backend 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.
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.

​
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.
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.

​
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:
Display the cached pipeline per store and index, including the task ID and when it was created. This command is read-only:
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:

​
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.
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.
Last modified on June 30, 2026