Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Index Agent and Search Engine

Index agent and search engine are two basic classes used to work with Elasticsearch index and perform the full text search.

Index Agent

Class: Oro\Bundle\ElasticSearchBundle\Engine\IndexAgent

Index agent is used by the search engine to get index name, initialize client and perform reindexing. The agent receives DI configuration of the search engine, like access credentials and index name, and uses it to setup entity mapping. Afterwards it supplies additional settings to tokenize text fields and merge all generated data with the external configuration.

The entity mapping is built based on the search entity configuration that is defined in search.yml files, main configuration and field type mappings. Field type mappings are injected through the DI as a parameter.

oro_elasticsearch.field_type_mapping:

 1 text:
 2     type: keyword
 3     store: true
 4     # see Oro\Bundle\ElasticSearchBundle\Engine\AbstractIndexAgent for analyzer definitions
 5     fields:
 6         analyzed:
 7             type: text
 8             search_analyzer: fulltext_search_analyzer
 9             analyzer: fulltext_index_analyzer
10 decimal:
11     type: double
12     store: true
13 integer:
14     type: integer
15     store: true
16 datetime:
17     type: date
18     store: true
19     format: "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd"

To make search faster, a special field that contains all text information (“all_text”) is generated (in lowercase and split into tokens using nGram tokenizer). Custom search and index analyzers are attached for this field. They are defined in additional index settings.

The data explained above is used to create and initialize a client (an instance of the ElasticsearchClient) and then return it to the search engine to perform full text search. The Index agent class uses the ClientFactory class to create an instance. You can use the factory to instantiate as many clients with various configurations, as you wish.

For reindex, the agent recreates the entire index by deleting existing one and creating a new one with the defined configuration. Partial mapping recreation is no longer possible.

Search Engine

Class: Oro\Bundle\ElasticSearchBundle\Engine\ElasticSearch

Search engine implements AbstractEngine interface. The SearchBundle uses search engine to handle search-related operations, and the search engine uses an index agent as a proxy to call the search-index-related operations (e.g. to get the index name or to request index recreation).

To perform save and delete operations, search engine uses Elasticsearch bulk API. Deletion performs as is using delete operation, save uses index operation to override existing data. This is done to clean the traces of old values that have no matching new values to overwrite them.

Reindex operation recreates all search indexes and then triggers save operation for all affected entities.

Search engine uses request builders to build Elasticsearch search request based on the source query. Each request builder in chain receives current request, modifies it and returns altered data.

New request builders can be added to engine through DI.