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 features that aren’t available with direct indexing. These include pre-indexing transformations, up-to-date Collections, and visibility into 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 stays off by default. Until you turn it on, the extension continues to index directly to Algolia.

​
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 the records sent and the result of each operation.
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, 8.4, or 8.5.
  • Adobe Commerce or Magento Open Source 2.4 or later.
  • The Algolia AI Search & Discovery extension, version 3.19 or later. Version 3.19 introduced support for routing indexing through Ingestion.
  • 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 a local table that caches the Ingestion pipeline for each store and index. Caching the pipeline prevents the extension from resolving it for 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 causes a silent failure. Records still reach the index in your application’s home region, so indexing looks like it’s working. But the connector configuration ends up stranded in the wrong region’s control plane, invisible in your dashboard. That 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. It’s what the extension 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 creates any missing pipeline resources. The module caches the resolved task 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 removes resources it created. The algolia:ingestion:init command resolves standard indices, such as products, categories, pages, and Query Suggestions, in advance. Other section indices resolve on first push instead.

​
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.
Ingestion sometimes writes index settings, such as the facet attributes a transformation manages. When it does, 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 fails, for example if you disable the task in the Algolia dashboard.
  • Enabled (default): the operation falls back to direct indexing, so indexing keeps working instead of stopping.
  • Disabled: the operation raises an error instead of falling back.
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 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 you delete a task, the extension detects this 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 you enable logging, 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. Resolve and cache the standard index pipelines for each store. Running the command again doesn’t recreate pipelines that are already cached.
Display the cached pipeline per store and index, including the task ID and creation date. 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. Check 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. Use it to confirm the resources in a region. For example, use it to diagnose a region mismatch without going through your store.
Last modified on September 16, 2026