Indexing System

The Indexing System in Maho maintains denormalized data structures that optimize query performance for catalog operations. While the EAV (Entity-Attribute-Value) model provides flexibility for product and category attributes, it requires complex multi-table joins that become slow at scale. The indexing system pre-calculates and stores this data in optimized index tables, enabling fast product listings, layered navigation, price calculations, and search functionality.

---

Indexer Architecture

Indexers in Maho follow a standardized architecture defined by Mage_Index_Model_Indexer_Abstract. Each indexer is responsible for transforming raw EAV data into flat, searchable structures.

Core Components

Class	Role
Mage_Index_Model_Process	Orchestrates the indexing lifecycle, managing status and execution modes (manual, real_time, schedule). app/code/core/Mage/Index/Model/Process.php30-55
Mage_Index_Model_Indexer_Abstract	Base class for all indexers, defining the interface for event matching and reindexing. app/code/core/Mage/Index/Model/Indexer/Abstract.php19-20
Mage_Index_Model_Event	Captures data changes (save, delete, mass action) to trigger partial indexing. app/code/core/Mage/Index/Model/Process.php111-123

Indexer Registration

Indexers are declared in config.xml under the global/index/indexer node. For example, the Catalog Search Fulltext indexer is defined as:

Sources: app/code/core/Mage/CatalogSearch/etc/config.xml59-65

---

Index Types and Priority

Maho maintains several core indexers. The system uses a priority system to ensure that dependencies (like EAV attributes) are processed before dependent indexes (like Flat tables).

Index Code	Model Class	Purpose
catalog_product_flat	Mage_Catalog_Model_Product_Indexer_Flat	Denormalizes product EAV into a single table per store. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php16-17
catalog_category_flat	Mage_Catalog_Model_Category_Indexer_Flat	Denormalizes category structure for faster tree traversal. app/code/core/Mage/Catalog/Model/Category/Indexer/Flat.php21-22
catalogsearch_fulltext	Mage_CatalogSearch_Model_Indexer_Fulltext	Builds the searchable index for the storefront. app/code/core/Mage/CatalogSearch/etc/config.xml61-63
catalog_url	Mage_Catalog_Model_Indexer_Url	Manages URL rewrites for products and categories. app/code/core/Mage/Catalog/Model/Indexer/Url.php1-20

---

Reindexing Logic

The system supports two primary indexing modes: reindexAll (Full) and processEvent (Partial).

Full Reindexing Flow

A full reindex typically truncates the target index tables and rebuilds them from the source EAV data.

Sources: app/code/core/Mage/Index/Model/Process.php153-200 app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php82-94 app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php103-199 lib/MahoCLI/Commands/IndexReindexProduct.php1-30

Partial Indexing (Change Tracking)

Partial indexing is triggered by the Mage_Index_Model_Event system. When a product is saved, the indexer matches the event and registers the specific ID for processing.

1. Match: matchEvent(Mage_Index_Model_Event $event) determines if the indexer cares about the change based on entity and type. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php105-174
2. Register: _registerEvent() adds specific data (like product_id) to the event object for later processing. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php180-186
3. Process: _processEvent() executes the specific update logic for the changed entity using stored event data. app/code/core/Mage/Index/Model/Indexer/Abstract.php58-59

---

Flat Catalog System (Deprecated)

The Flat Catalog system (Product and Category) creates denormalized tables to avoid expensive EAV joins.

Note: As of Maho 26.5, the Flat Catalog is deprecated and will be removed in a future version. Users are encouraged to use the standard EAV system which has been optimized for modern database engines. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php14-15 app/code/core/Mage/Catalog/Model/Category/Indexer/Flat.php19-21

Implementation Details

• Product Flat: Creates tables named catalog_product_flat_{store_id}. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php16-17
• Category Flat: Creates tables named catalog_category_flat_store_{store_id}. app/code/core/Mage/Catalog/Model/Category/Indexer/Flat.php21-22
• Requirement: Flat catalog is only supported on MySQL. It is automatically disabled for PostgreSQL or SQLite to ensure cross-database compatibility. app/code/core/Mage/Catalog/Helper/Category/Flat.php57-61 app/code/core/Mage/Catalog/Helper/Product/Flat.php108-111

Sources: app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php14-17 app/code/core/Mage/Catalog/Helper/Category/Flat.php57-61 app/code/core/Mage/Catalog/Helper/Product/Flat.php108-111

---

Catalog Search Indexing

The catalogsearch_fulltext indexer is critical for search performance. It aggregates all searchable attributes into a single data_index column.

Data Flow: EAV to Fulltext Index

The search indexer collects data from multiple attributes based on their is_searchable configuration.

Sources: app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php103-199

Search Configuration and Autocomplete

• Search Type: Supports LIKE (1), FULLTEXT (2), or COMBINE (3). Configured via catalog/search/search_type. app/code/core/Mage/CatalogSearch/Model/Fulltext.php27-29 app/code/core/Mage/CatalogSearch/etc/system.xml72-81
• SKU Boost: When enabled via catalog/search/boost_sku_matches, products matching by SKU are prioritized in results. app/code/core/Mage/CatalogSearch/Model/Fulltext.php32 app/code/core/Mage/CatalogSearch/etc/system.xml92-101
• Autocomplete Display: Managed by Mage_CatalogSearch_Block_Autocomplete and suggest.phtml, which can include categories and products. The MahoAutocomplete JavaScript class handles the frontend interaction. app/design/frontend/base/default/template/catalogsearch/suggest.phtml10-22 public/js/maho-autocomplete.js9-100
• Category Search: Autocomplete can include a list of categories if enabled in configuration (catalog/search/enable_category_autosuggest). app/design/frontend/base/default/template/catalogsearch/suggest.phtml13-15 app/code/core/Mage/CatalogSearch/etc/system.xml128-135

Sources: app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php103-199 app/code/core/Mage/CatalogSearch/etc/system.xml46-101 app/code/core/Mage/CatalogSearch/Model/Fulltext.php125-127 public/js/maho-autocomplete.js9-100

---

Performance Optimization

Maho optimizes the indexing process through several strategies:

1. Batch Processing: Mage_CatalogSearch_Model_Resource_Fulltext uses a while(true) loop with _getSearchableProducts to process products in chunks (batches), preventing memory exhaustion during full reindexes. app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php128-132
2. Locking Mechanism: Mage_Index_Model_Process uses a locking mechanism (lock() / unlock()) to prevent concurrent indexing of the same process, which could lead to database deadlocks or data corruption. app/code/core/Mage/Index/Model/Process.php162-185
3. Selective Indexing: The matchEvent logic ensures that only relevant changes trigger a reindex. For example, the Product Flat indexer checks if an attribute is actually used in product listings before matching an attribute save event. app/code/core/Mage/Catalog/Model/Product/Indexer/Flat.php119-146
4. Targeted Reindexing: The reindexEntity method in the abstract indexer allows for reindexing of specific IDs, attempting to use optimized resource-level methods like reindexProductIds when available to avoid full table rebuilds. app/code/core/Mage/Index/Model/Indexer/Abstract.php195-216

Sources: app/code/core/Mage/Index/Model/Process.php153-200 app/code/core/Mage/CatalogSearch/Model/Resource/Fulltext.php128-199 app/code/core/Mage/Index/Model/Indexer/Abstract.php195-216