Implementing Advanced Search with Algolia in GraphCommerce

The need for fast, relevant, and personalized search experiences has become paramount. GraphCommerce, This integration offers developers a robust solution to enhance search capabilities while maintaining the flexibility and performance that GraphCommerce is known for.

In this article, we'll dive deep into the technical aspects of implementing Algolia in GraphCommerce, exploring the architecture, key components, and best practices for leveraging this powerful integration.

The Algolia integration in GraphCommerce is designed with a clear separation between the GraphQL layer and the frontend implementation. This architecture allows for seamless integration with existing GraphCommerce setups while providing the flexibility to customize and extend functionality as needed.

The is composed of five packages:

@graphcommerce/algolia-products
@graphcommerce/algolia-categories
@graphcommerce/algolia-insights
@graphcommerce/algolia-personalization
@graphcommerce/algolia-recommend

Preparation: Search Overlay UI

Algolia goes hand-in-hand with a proper search UI. We've got a separate 'Magento Search Overlay' package that adds a search overlay experience to GraphCommerce. This search overlay is not dependent on Algolia so you can use it with default Magento. So before starting, install the @graphcommerce/magento-search-overlay package first.

Installation and configuration of Algolia for GraphCommerce

Preparation

To integrate Magento's product catalog with GraphCommerce, you need to set up your Algolia indexes. This is typically done using the Magento 2 Algolia module, which handles the synchronization of product and category data.

Setup the fields that you want to index in algolia Stores > configuration > Algolia Search > Products > Products
Configure your aggregations/filters, make sure that the aggregation fields are also indexed in step 2 Stores > Configuration > Algolia Search > Instant Search Results Page > Facets
Make sure the aggregations fields are made filterable(Use in layerd Navigation), so the attributeList query can retrieve the labels. Stores > Products > Attributes
To configure sorting options, enable Virtual Replica's. Stores > Configuration > Algolia Search > Instant Search Results Page > Use Virtual Replica

@graphcommerce/algolia-products

After this package is installed and configured the search is automatically replaced by Algolia's search.

This package is responsible for integrating Algolia's search functionality into GraphCommerce's GraphQL layer. It includes several key components:

Search Result Mapping: Converts Algolia search hits to Magento-compatible product objects.
Facet Handling: Transforms Algolia facets into Magento-style aggregations for consistent filtering.
Query Input Preparation: Prepares search inputs to align with Algolia's query structure.

Find current version of your @graphcommerce/next-ui in your package.json. And run yarn add @graphcommerce/algolia-products@9.0.0 (replace 9.0.0 with the same version as the @graphcommerce/next-ui)

To enable Algolia in your GraphCommerce project, you'll need to add the necessary configuration to your graphcommerce.config.js file:

module.exports = {
  // Other configuration...
  algolia: {
    // Configure your Algolia application ID. [Algolia API Keys Dashboard](https://www.algolia.com/account/api-keys)
    applicationId: '',

    // Configure your Search API Key. [Algolia API Keys Dashboard](https://www.algolia.com/account/api-keys)
    // Make sure the API key has the following ACL: search, listIndexes and settings [Lookup here](https://dashboard.algolia.com/account/api-keys/restricted)
    searchOnlyApiKey: '',

    // Stores > Configuration > Algolia Search > Credentials and Basic Setup > Index name prefix
    indexNamePrefix: 'SAME_AS_MAGENTO',

    // By default the catalog will not use algolia. Set this to true to enable Algolia for the catalog.
    catalogEnabled: true,
  },
}

When writing your own product queries, you can set the engine to algolia to use Algolia's search.

query AlgoliaProducts {
  products(filter: { engine: { eq: "algolia" } }) {
    items {
      name
    }
  }
}

See the algoliaHitToMagentoProduct for all the fields that are returned.

@graphcommerce/algolia-categories

This package is responsible for integrating Algolia's category search functionality into GraphCommerce's GraphQL layer.

We currenly do not support replacing the whole category tree with Algolia's categories, because only a reduced set of fields are indexed to algolia.

When writing your own category queries, you can set the engine to algolia to use Algolia's search.

query AlgoliaCategories {
  categories(filters: { engine: { eq: "algolia" } }) {
    items {
      name
      breadcrumbs {
        category_name
      }
    }
  }
}

See the algoliaHitToMagentoCategory for all the fields that are returned.

@graphcommerce/algolia-insights

This package implements Algolia's insights features, which are used to track user interactions and improve search relevance. These events are crucial for enabling features like NeuralSearch, Dynamic Re-Ranking, Query Categorization, Analytics, A/B Testing, Recommend, and Personalization.

When installed the feature is automatically enabled.
Browse the site and verify that events are being logged in the Algolia dashboard. You can check this in the Event Debugger: Data Sources > Events > Debugger.

The events as described in Algolia's event types page are sent to Algolia from the codebase.

The event flow implemented is as follows:

When a user sees a product on the screen (IntersectionObserver) the viewedObjectIDs/viewedObjectIDsAfterSearch is send.
When a user views a list of products the viewedFilters/clickedFilters are send.
When a user clicks on a product the clickedObjectIDs/clickedObjectIDsAfterSearch is send.
When a user adds a product to the cart the addedToCartObjectIDs/addedToCartObjectIDsAfterSearch is send. We automatically track where each item in the cart originated form. We track every item in the cart and match them to the original query that was used to find them.
When a user purchases a product the purchasedObjectIDs/purchasedObjectIDsAfterSearch is send. We automatically track where each item in the purchase originated form. We track every item in the purchase and match them to the original query that was used to find them.

Note: The convertedObjectIds/convertedObjectIDsAfterSearch are not implemented, they are a simplified version of the addedToCartObjectIDs/addedToCartObjectIDsAfterSearch

The useSendAlgoliaEvent hook in @graphcommerce/algolia-insights is responsible for sending these events to Algolia.

@graphcommerce/algolia-personalization

This package requires insights to be sent to Algolia for them to be able to create personalized queries. Once you've collected several events, set up personalization strategies in the Algolia dashboard under Enhance > Personalization.

This package implements Algolia's personalization features, including: Personalized search results and User token management for consistent identification

Note: This package is optional because this will increase the amount of API calls send to Algolia which can increase your costs when viewing lists of products that otherwise are static like related products, category queries etc.

This package requires insights to be sent to Algolia for them to be able to create recommendations. Once you've collected several events, set up recommendation strategies in the Algolia dashboard under Recommend > Models.

This package implements Algolia's recommendation features, including:

Related products
Frequently bought together
Similar looking items

The recommend package can replace various sections of Magento's default fields. So this can be a drop-in replacement. You can configure which fields to replace by updating your graphcommerce.config.js:

module.exports = {
  algolia: {
    lookingSimilar: 'UPSELL_PRODUCTS',
    frequentlyBoughtTogether: 'CROSSSELL_PRODUCTS',
    relatedProducts: 'RELATED_PRODUCTS',
  },
}

Besides this the features are also available as separate fields on products:

query AlgoliaProducts {
  products(filter: { engine: { eq: "algolia" } }) {
    items {
      name
      algolia_looking_similar {
        name
      }
      algolia_related_products {
        name
      }
      algolia_frequently_bought_together {
        name
      }
    }
  }
}

Multi-store and Multi-language Support

The Algolia integration in GraphCommerce supports multi-store and multi-language setups out of the box. It uses the indexes created by the Magento 2 Algolia module.

Additional Configuration

Navigate to Stores > Configuration > Algolia Search > Instant Search Results Page
Set Number of values per facet to 1000 or a value that is high enough to fetch everyting at once.

Visibility

By default Algolia will index all products will have fields like, however those fields are NOT filterable.

visibility_search: 1
visibility_catalog: 1

To properly support the visibility filter the visibility attribute needs to be added to the index:

Navigate to Stores > Configuration > Algolia Search > Instant Search Results Page
Add visibility to Facets and set it to Filter only

Suggestions

Create a query suggestions index in your Algolia dashboard: Query Suggestions based on your products indexes.
The name of the index will be auto-completed as: ${index}_query_suggestions.
Do this for all product indexes.

const config = {
  algolia: {
    /*
     * To enable Algolia suggestions, please provide the Suffix that is used for your suggestions index.
     * For the index `magento2_demo_en_US_query_suggestions` this would be `_query_suggestions`
     */
    suggestionsSuffix: '_query_suggestions,
  },
}

⚠️ Warning: This does not use the Magento 2 Algolia suggestions feature. That feature only syncs Magento's suggestions to Algolia and doesn't use the Algolia Suggestions feature.

Navigate to Stores > Configuration > Algolia Search > Credentials and Basic Setup\
Set Enable Query Suggestions Index to No.
Cleanup remaining indexes in the indices overview

Sorting Options

To configure sorting options for your Algolia-powered search, you need to enable Virtual Replicas in your Magento 2 Algolia module configuration:

Navigate to Stores > Configuration > Algolia Search > Instant Search Results Page
Enable the "Use Virtual Replica" option

This allows you to define different sorting options, each of which will be treated as a separate (virtual) index in Algolia.

Customer Group Pricing

const config = {
  algolia: {
    customerGroupPricingEnabled: true,
  },
}

To enable customer group pricing, make sure customers groups prices are mapped to algolia. Stores > Configuration > Algolia Search > Advanced > Enable Customer Groups.

⚠️ Warning: Magento needs to be configured the same as customerGroupPricingEnabled, else sorting index selection will not work properly for customer group pricing.

⚠️ Warning: Catalog price rules for a specific customer group do not seem to be indexed. It seems only: [Product] > Advanced Pricing > Customer Group Price gets indexed.

⚠️ Warning: The GraphQL API does not expose the customer group_id by default. To make this functionality work, an additional REST API call is made when loggin the customer in. This means a somewhat slower (few hundred ms) when the Customer is loaded.

Customization

By default algoliaFacetsToAggregations and algoliaHitToMagentoProduct are split into it's own functions so plugins can be easily written.

Conclusion

The Algolia integration in GraphCommerce offers a powerful toolset for implementing advanced search and discovery features in your e-commerce application. By leveraging the separation of concerns between the GraphQL layer and frontend implementation, you can create a flexible, performant, and feature-rich search experience.

As you implement and customize the Algolia integration, remember to focus on performance, user experience, and data privacy. Regularly analyze search analytics and user behavior to continually refine and improve your search implementation.

For more information and detailed documentation, visit the GraphCommerce GitHub repository and Algolia's developer documentation. Happy coding!