DocumentationCommerceLive Search Guide

Set up for success with Live Search

Last update: Thu Oct 10 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

Adobe Commerce Live Search and Catalog Service work together to provide a performant, relevant, and intuitive search solution to allow your customers to find exactly what they need, fast. Specifically, Catalog Service surfaces your catalog data for SaaS services, such as Live Search to use.

This article provides step-by-step instructions for implementing Live Search with Catalog Service.

IMPORTANT
When it comes to site search, Adobe Commerce gives you options. Be sure to read Boundaries and Limits before implementing, to ensure that Live Search is a fit for your business needs.

Audience

This article is intended for the developer or systems integrator on your team who is responsible for installing and configuring your Adobe Commerce instance.

Requirements

Supported platforms

  • Adobe Commerce on Cloud (ECE) : 2.4.4+
  • Adobe Commerce on-prem (EE) : 2.4.4+

Workflow overview

At a high level, onboarding Live Search requires that you:

  1. Install the Live Search extension
  2. Configure the API keys
  3. Sync your catalog data
  4. Verify that the catalog data was exported
  5. Configure the data
  6. Test the connection
  7. Verify that events are capturing data
  8. Customize your storefront

1. Install the Live Search extension

Live Search is installed as an extension from Adobe Marketplace through Composer. After you install and configure Live Search, Adobe Commerce begins sharing search and catalog data with SaaS services. At this point, Admin users can set up, customize, and manage search facets, synonyms, and merchandising rules.

NOTE
As of Live Search 3.0.2, the Catalog Service extension is bundled in with the Live Search installation.

  1. Confirm that cron jobs and indexers are running.

    note important
    IMPORTANT
    Due to the Elasticsearch 7 end-of-support announcement for August 2023, it is recommended that all Adobe Commerce customers migrate to the OpenSearch 2.x search engine. For information about migrating your search engine during a product upgrade, see Migrating to OpenSearch in the Upgrade Guide.

  2. Download the live-search package from the Adobe Marketplace.

  3. Run the following from the command line:

    code language-bash 
    composer require magento/live-search

    If you are adding the Live Search extension to a new Adobe Commerce installation, run the following command to disable OpenSearch and related modules temporarily, and install Live Search. Then, proceed to step 4.

    code language-bash 
       bin/magento module:disable Magento_Elasticsearch Magento_Elasticsearch7 Magento_OpenSearch Magento_ElasticsearchCatalogPermissions Magento_InventoryElasticsearch Magento_ElasticsearchCatalogPermissionsGraphQl

    If you are adding the Live Search extension to an existing Adobe Commerce installation, run the following to disable the Live Search modules that serve storefront search results. Then, proceed to step 4:

    code language-bash 
       bin/magento module:disable Magento_LiveSearchAdapter Magento_LiveSearchStorefrontPopover Magento_LiveSearchProductListing

    Elasticsearch continues to manage search requests from the storefront while the Live Search service synchronizes catalog data and indexes products in the background.

  4. Run the following:

    code language-bash 
    bin/magento setup:upgrade

  5. Verify that the following indexers are set to “Update by Schedule”:

    • Product Feed
    • Product Variant Feed
    • Catalog Attributes Feed
    • Product Prices Feed
    • Scopes Website Data Feed
    • Scopes Customer Groups Data Feed
    • Categories Feed
    • Category Permissions Feed

  6. If you are installing Live Search on a new Commerce instance, you are done and can skip to the 2. Configure API keys section. If you are installing Live Search to an existing Commerce instance, proceed to the next step.

  7. Run the following commands to enable the Live Search extension, disable OpenSearch, and run setup.

    code language-bash 
    bin/magento module:enable Magento_LiveSearchAdapter Magento_LiveSearchStorefrontPopover  Magento_LiveSearchProductListing
    code language-bash 
    bin/magento module:disable Magento_Elasticsearch Magento_Elasticsearch6 Magento_Elasticsearch7 Magento_ElasticsearchCatalogPermissions Magento_InventoryElasticsearch
Magento_ElasticsearchCatalogPermissionsGraphQl
    code language-bash 
    bin/magento setup:upgrade

Install the Live Search beta

IMPORTANT
The following feature is in beta. To participate in the beta, send an email request to commerce-storefront-services.

This beta supports three new capabilities in the productSearch query:

  • Layered search - Search within another search context - With this capability, you can undertake up to two layers of search for your search queries. For example:

    • Layer 1 search - Search for “motor” on “product_attribute_1”.
    • Layer 2 search - Search for “part number 123” on “product_attribute_2”. This example searches for “part number 123” within the results for “motor”.

    Layered search is available for both startsWith search indexation and contains search indexation as described below:

  • startsWith search indexation - Search using startsWith indexation. This new capability allows:

    • Searching for products where the attribute value starts with a particular string.
    • Configuring an “ends with” search so shoppers can search for products where the attribute value ends with a particular string. To enable an “ends with” search, the product attribute needs to be ingested in reverse and the API call should also be a reversed string.

  • contains search indexation -Search an attribute using contains indexation. This new capability allows:

    • Searching for a query within a larger string. For example, if a shopper searches for the product number “PE-123” in the string “HAPE-123”.

      • Note: This search type is different from the existing phrase search, which performs an autocomplete search. For example, if your product attribute value is “outdoor pants”, a phrase search returns a response for “out pan”, but does not return a response for “oor ants”. A contains search, however, does return a response for “oor ants”.

These new conditions enhance the search query filtering mechanism to refine search results. These new conditions do not affect the main search query.

You can implement these new conditions on your search results page. For example, you can add a new section on the page where the shopper can further refine their search results. You can allow shoppers to select specific product attributes, such as “Manufacturer”, “Part Number”, and “Description”. From there, they search within those attributes using the contains or startsWith conditions. See the Admin guide for a list of searchable attributes.

  1. To install the beta, add the following dependency to your project:

    code language-bash 
    composer require magento/module-live-search-search-types:"^1.0.0-beta1"

  2. Commit and push the changes to your composer.json and composer.lock files to your cloud project. Learn more.

    This beta adds Search types checkboxes for Autocomplete, Contains, and Starts with in the Admin. It also updates the productSearch GraphQL API to include these new search capabilities.

  3. In the Admin, set a product attribute to be searchable and specify the search capability for that attribute, such as Contains (default) or Starts with. You can specify a maximum of six attributes to be enabled for Contains and six attributes to be enabled for Starts with. For beta, be aware that the Admin does not enforce this restriction but it is enforced in API searches.

    Specify search capability

  4. See the developer documentation to learn how to update your Live Search API calls using the new contains and startsWith search capabilities.

Field descriptions

Field
Description
Autocomplete
Enabled by default and cannot be modified. With Autocomplete you can use contains in the search filter. Here, the search query in contains returns an autocomplete type search response. Adobe recommends you use this type of search for description fields, which typically have more than 50 characters.
Contains
Enables a true “text contained in a string” search instead of an autocomplete search. Use contains in the search filter. Refer to the Limitations for more information.
Starts with
Lets you query strings which start with a particular value. Use startsWith in the search filter.

2. Configure API keys

The Adobe Commerce API key and its associated private key are required to connect Live Search to an installation of Adobe Commerce. The API key is generated and maintained in the account of the Commerce license holder, who can share it with the developer or systems integrator. The developer can then create and manage the SaaS Data Spaces on behalf of the license holder. If you already have a set of API keys, you do not need to regenerate them.

Learn how to configure your API keys in the Commerce Services Connector article.

3. Sync your catalog data synchronize-catalog-data

Live Search moves catalog data to Adobe’s SaaS infrastructure. The data is indexed and search results are delivered from this index directly to the storefront. Depending on the size and complexity, indexing can take from 30 minutes to a couple of hours.

To begin the initial sync of your catalog data to SaaS services, run the following commands in this order:

bin/magento saas:resync --feed productattributes
bin/magento saas:resync --feed products
bin/magento saas:resync --feed scopesCustomerGroup
bin/magento saas:resync --feed scopesWebsite
bin/magento saas:resync --feed prices
bin/magento saas:resync --feed productoverrides
bin/magento saas:resync --feed variants
bin/magento saas:resync --feed categories
bin/magento saas:resync --feed categoryPermissions

When you run these commands, the initial sync of your catalog data to SaaS services begins.

WARNING
While the data is indexed and synchronized, the search and category browse operations are not available in the storefront. Depending on the size of your catalog, the process can take at least an hour from the time cron runs to synchronize your data to SaaS services.

Monitor sync progress

You can view the data that is synchronized and shared using the Data Management Dashboard. This dashboard provides valuable insights into the availability of product data for your storefront, ensuring it can be promptly displayed to your shoppers.

Data Management Dashboard

You can also run sync commands and troubleshoot the synchronization process using the Commerce CLI and the data export extension logs.

Future product updates

After the initial synchronization, it can take up to 15 minutes for incremental product updates to become available to storefront search. To learn more, see Streaming Product Updates in the Indexing documentation.

4. Verify that the data was exported verify-export

To check if your catalog data has been exported from Adobe Commerce and synced with Live Search, you have a few options:

  • Look for entries in the following tables:

    • cde_products_feed
    • cde_product_attributes_feed
    note note
    NOTE
    If you get a table does not exist error, look for entries in the catalog_data_exporter_products and catalog_data_exporter_product_attributes tables. These table names are used in Live Search versions earlier than 4.2.1.

  • Use the GraphQL playground with the default query to verify the following:

    • The returned product count is close to what you expect for the store view.
    • Facets are returned.

For additional help, see Live Search catalog not synchronized in the Support Knowledge Base.

5. Configure the data

Getting your product data configured correctly ensures good search results for your customers. In this section, you enable the product listing widgets and assign categories.

Enable product listing widgets

When you install Live Search 4.0.0+, product listing widgets are enabled by default. When widgets are enabled, a different UI component is used for the search results page and the category browse product listing page. This UI component makes direct calls to the Catalog Service API, which results in faster response times.

If you have a Live Search version older than 4.0.0+, you must manually enable the Product Listing Widget.

  1. From the Admin, go to Stores > Settings > Configuration.

  2. Under Live Search, select Storefront Features.

  3. Set Enable Product Listing Widgets to Yes.

    Enable Product Listing Widgets

When you change this configuration, the message Page cache is invalidated appears. You need to flush the Magento Cache to save your change.

  1. Access the Cache Management page by doing one of the following:

    • Click the Cache Management link in the message above the workspace.
    • On the Admin sidebar, go to System > Tools > Cache Management.

  2. Select the Configuration Cache Type and click Flush Magento Cache.

    Changes to the storefront are immediate after you flush the cache.

Assign categories

Products returned in Live Search must be assigned to a category. In Luma, for example, products are put into categories such as “Men”, “Women”, and “Gear”. Subcategories are also set up for “Tops”, “Bottoms”, and “Watches”. These category assignments improve granularity when filtering.

6. Test the connection test-connection

With your catalog data now in SaaS, test to make sure product data is returned in the following scenarios:

  • The Search box returns results correctly
  • Category browse returns results correctly
  • Facets are available as filters on search results pages

If everything works correctly, Live Search is installed, connected, and ready to use.

If you encounter problems in the storefront, check the var/log/system.log file for API communication failures or errors on the services side.

To allow Live Search through a firewall, add commerce.adobe.io to the allowlist.

7. Verify that events are capturing data

Ensure that the storefront events deployed to your site are working. This is especially important for headless implementations.

  • Review the events that are required for Live Search.
  • Ensure that the Live Search dashboard is displaying data from your non-production environment(s).
  • Verify event collection. While this page is in the Product Recommendations guide, the verification steps apply to Live Search as well.

8. Customize for your storefront

You have installed the Live Search extension, synced, validated, and configured your data. The next step is to ensure that the Live Search widgets conform to your store’s look and feel.

You can style the popover and PLP widgets by defining custom CSS rules as needed. See Styling Popover Elements and product listing page widget.

If you wish to extend the functionality of the widgets, the source code for each is available in a public repo.
In this scenario, you can customize the JavaScript for your own needs and then host your custom code on your CDN. This custom script communicates with the Live Search service and returns the results like normal, allowing you to control the functionality of the widget.

Updating Live Search update

Before updating Live Search, run the following from the command line to check the version of Live Search that is installed:

composer show magento/module-live-search | grep version

To update Live Search, run the following from the command line:

composer update magento/live-search --with-dependencies

To update to a major version such as from 3.1.1 to 4.0.0, edit the project’s root Composer .json file as follows:

  1. If your currently installed magento/live-search version is 3.1.1 or below, and you are upgrading to version 4.0.0 or higher, run the following command before the upgrade:

    code language-bash 
    bin/magento module:enable Magento_AdvancedSearch

    For information about the currently installed magento/live-search version, run the following command:

    code language-bash 
    composer show magento/live-search

  2. Open the root composer.json file and search for magento/live-search.

  3. In the require section, update the version number as follows:

    code language-json 
    "require": {
   ...
   "magento/live-search": "^4.0",
   ...
 }

  4. Save composer.json. Then, run the following from the command line:

    code language-bash 
    composer update magento/live-search --with-dependencies

Uninstalling Live Search uninstall

To uninstall Live Search, refer to Uninstall modules.

Live Search packages packages

The Live Search extension consists of the following packages:

Package
Description
module-live-search
Allows merchants to configure their search settings for faceting, synonyms, query rules, and so on, and provides access to a read-only GraphQL playground to test queries from the Admin.
module-live-search-adapter
Routes search requests from the storefront to the Live Search service and renders the results in the storefront.
- Category browse - Routes requests from the storefront top navigation to the search service.
- Global search - Routes requests from the quick search box in the upper-right of the storefront to the Live Search service.
module-live-search-storefront-popover
A “search as you type” popover replaces the standard quick search and returns data and thumbnails of top search results.

Live Search dependencies dependencies

The Composer metapackage to install the Live Search extension includes the following module dependencies.

  • magento/module-saas-catalog
  • magento/module-saas-category
  • magento/module-saas-category-permissions
  • magento/module-saas-product-override
  • magento/module-saas-product-variant
  • magento/module-saas-price
  • magento/module-saas-scopes
  • magento/module-bundle-product-data-exporter
  • magento/module-catalog-inventory-data-exporter
  • magento/module-catalog-url-rewrite-data-exporter
  • magento/module-configurable-product-data-exporter
  • magento/module-parent-product-data-exporter
  • magento/module-gift-card-product-data-exporter
  • magento/module-bundle-product-override-data-exporter
  • data-services
  • services-id

Advanced concepts

The following sections provide more advanced topics when using Live Search and Catalog Service.

Endpoint

Live Search communicates through the endpoint at https://catalog-service.adobe.io/graphql.

As Live Search does not have access to the complete product database, the Live Search GraphQL and Commerce core GraphQL APIs do not have complete parity.

Adobe recommends calling the SaaS APIs directly — specifically the Catalog Service endpoint.

  • Gain performance and reduce processor load by bypassing the Commerce database/Graphql process
  • Take advantage of the Catalog Service federation to call Live Search, Catalog Service, and Product Recommendations from a single endpoint.

For some use cases, it maybe better to call Catalog Service for product details and similar cases. See refineProduct for more information.

If you have a custom headless implementation, check out the Live Search reference implementations:

Automatic collection of user interaction data does not work by default when you do not use the standard components like the Search Adapter, Luma widgets, or AEM CIF Widgets. Adobe Sensei uses this collected data for intelligent merchandising and performance tracking. To resolve this issue, you need to develop a custom solution to implement this data collection in a headless manner.

The latest version of Live Search already uses Catalog Service.

Language support

Live Search widgets support the following languages:

Language
Region
Language Code
Magento Locale
Bulgarian
Bulgaria
bg_BG
bg_BG
Catalan
Spain
ca_ES
ca_ES
Czech
Czech Republic
cs_CZ
cs_CZ
Danish
Denmark
da_DK
da_DK
German
Germany
de_DE
de_DE
Greek
Greece
el_GR
el_GR
English
United Kingdom
en_GB
en_GB
English
United States
en_US
en_US
Spanish
Spain
es_ES
es_ES
Estonian
Estonia
et_EE
et_EE
Basque
Spain
eu_ES
eu_ES
Persian
Iran
fa_IR
fa_IR
Finnish
Finland
fi_FI
fi_FI
French
France
fr_FR
fr_FR
Galician
Spain
gl_ES
gl_ES
Hindi
India
hi_IN
hi_IN
Hungarian
Hungary
hu_HU
hu_HU
Indonesian
Indonesia
id_ID
id_ID
Italian
Italy
it_IT
it_IT
Korean
South Korea
ko_KR
ko_KR
Lithuanian
Lithuania
lt_LT
lt_LT
Latvian
Latvia
lv_LV
lv_LV
Norwegian
Norway Bokmal
nb_NO
nb_NO
Dutch
Netherlands
nl_NL
nl_NL
Polish
Poland
pl_PL
pl_PL
Portuguese
Brazil
pt_BR
pt_BR
Portuguese
Portugal
pt_PT
pt_PT
Romanian
Romania
ro_RO
ro_RO
Russian
Russia
ru_RU
ru_RU
Swedish
Sweden
sv_SE
sv_SE
Thai
Thailand
th_TH
th_TH
Turkish
Turkey
tr_TR
tr_TR
Chinese
China
zh_CN
zh_Hans_CN
Chinese
Taiwan
zh_TW
zh_Hant_TW

If the widget detects that the Commerce Admin language setting matches a supported language, it defaults to that language. Otherwise, the widget default to English. In the Admin, the language setting is configured by navigating to Stores > Settings > Configuration > General > Country Options.

Admins can also set the language of the search index, to help ensure better search results.

Widget code repository

The code for the product listing page widget and the Live Search field widget is available for download from GitHub.

Developers who have access to the code can completely customize how it works and looks. They host the code on their own servers but still use the Live Search service.

Data Export extension

After Live Search is enabled, the Data Export extension synchronizes Commerce data between the Commerce application and Live Search. This process ensures that the most current Commerce data is available on the storefront. In the Admin, you can check synchronization status using the Data Management dashboard. You can manage and troubleshoot the data export process using the Commerce CLI and logs. For details, see the Data Export Guide.

Inventory management

Live Search supports Inventory Management capabilities in Commerce (formerly knows as Multi-Source Inventory, or MSI). To enable full support, you must update the dependency module commerce-data-export to version 102.2.0+.

Live Search returns a boolean noting whether a product is available within Inventory Management, but does not contain information about which source has the stock.

Price indexer

Live Search customers can use the SaaS price indexer, which provides faster price change updates and synchronization time.

Price support

Live Search widgets support most but not all price types supported by Adobe Commerce.

Currently, basic prices are supported. Advanced prices that are not supported are:

  • Cost
  • Minimum Advertised Price

Look at API Mesh for more complex price calculations.

The price format supports the locale configuration setting within the Commerce instance: Stores > Settings > Configuration > General > General > Local Options > Locale.

Headless storefront support

Optionally, you might need to install the module-data-services-graphql module that expands the application’s existing GraphQL coverage to include fields required for storefront behavioral data collection.

composer require magento/module-data-services-graphql

This module adds additional contexts to GraphQL queries:

  • dataServicesStorefrontInstanceContext
  • dataServicesMagentoExtensionContext
  • dataServicesStoreConfigurationContext

B2B support

Live Search supports B2B functionality with additional limitations.

PWA support

Live Search works with PWA Studio but users might see slight differences compared to other Commerce implementations. Basic functionality such as search and product listing page work in Venia but some permutations of Graphql might not work correctly. There might also be performance differences.

  • The current PWA implementation of Live Search requires more processing time to return search results than Live Search with the native Commerce storefront.
  • Live Search in PWA does not support event handling. As a result, search reporting and intelligent merchandising do not work on PWA storefronts.
  • When using PWA Studio, GraphQL does not support filtering directly on description, name, short_description, but these fields can be returned with a more general filter.

To use Live Search with PWA Studio, integrators must also:

  1. Install livesearch-storefront-utils.

  2. Set the environmentId in the storeDetails object.

    code language-javascript 
    const storeDetails: StoreDetailsProps = {
    environmentId: <Storefront_ID>,
    websiteCode: "base",
    storeCode: "main_website_store",
    storeViewCode: "default",
    searchUnitId: searchUnitId,
    config: {
        minQueryLength: 5,
        pageSize: 8,
        currencySymbol: "$",
        },
    };

Cookies

Live Search collects user interaction data as part of its base functionality and cookies are used to store this data. When collecting any user information, the user must agree to store cookies. Live Search and Product Recommendations share the data stream and therefore the same cookie mechanism. Read more about it in Handle Cookie Restrictions.

recommendation-more-help
1d60634e-b73a-404a-be7a-4a2a36676055