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.
Configuration¶
OroSearchBundle provides options that can be used to customize the search functionality.
System Configuration¶
All configuration data is placed in the configuration under alias
oro_search. Let us look at the configuration example:
1oro_search:
2 engine: orm
3 engine_parameters:
4 ...
5 log_queries: true
6 item_container_template: MyBundle:Search:itemContainer.html.twig
7 entities_config:
8 ...
Description of parameters:
engine, default “orm” (converted to container parameter oro_search.engine) - specifies the search engine name used to perform search and indexation (see section Search Engine Configuration);
engine_parameters (converted to the container parameter oro_search.engine_parameters) - additional parameters of the search engine used for initialization (f.e. IP, port, credentials etc);
log_queries, default false (converted to container parameter oro_search.log_queries) - flag that defines whether it is necessary to log search queries to the database;
item_container_template, default “OroSearchBundle:Datagrid:itemContainer.html.twig” (converted to container parameter oro_search.twig.item_container_template) - template used to render entity row in search results;
entities_config (converted to container parameter oro_search.entities_config) - entity search configuration, can be used to override the default entity search configuration (see section Entity Configuration).
Configuration Merging¶
All configurations merge in the boot bundles order. The application collects configurations of all nodes with the same name and merges them into one configuration. Merging uses simple rules:
if the node value is scalar, the value will be replaced
if the node value is an array:
by default the value will be replaced
for node ‘fields’ this array will be appended by values from the second configuration.
After this step, the application knows about all entity search configurations from the search.yml files and has only one configuration for each entity.
Example
Acme/Bundle/DemoBundle/Resources/config/oro/search.yml:
1Acme\Bundle\DemoBundle\Entity\Tag:
2 alias: acme_tag
3 title_fields: [name]
4 search_template: DemoBundle:Search:result.html.twig
5 route:
6 name: acme_tag_search
7 parameters:
8 id: id
9 fields:
10 -
11 name: name
12 target_type: text
13 target_fields: [name]
AcmeCRM/Bundle/DemoBundle/Resources/config/search.yml:
1Acme\Bundle\DemoBundle\Entity\Tag:
2 alias: acme_tag
3 title_fields: [subject]
4 fields:
5 -
6 name: subject
7 target_type: text
8 target_fields: [subject]
Result:
1 alias: acme_tag
2 title_fields: [subject]
3 search_template: DemoBundle:Search:result.html.twig
4 route:
5 name: acme_tag_search
6 parameters:
7 id: id
8 fields:
9 -
10 name: name
11 target_type: text
12 target_fields: [name]
13 -
14 name: subject
15 target_type: text
16 target_fields: [subject]
Entity Configuration¶
After insert, update or delete entity records, the search index must be updated. The search index consists of data from entities by mapping parameters. Entity search configuration maps fields to the virtual search fields in the search index.
Entity search configuration can be stored in main config.yml file (in
oro_search config section) or in search.yml files in the config
directory of the bundle.
Configuration is an array that contains info about the bundle name, entity name
and the array of fields. Fields array contains the array of field name and field
type. Data from all text fields will be stored in the all_text virtual field.
Additionally, all the fields will be stored in the fieldName virtual
fields, if the target_fields parameter is not set.
Example:
1Acme\DemoBundle\Entity\Product:
2 alias: demo_product # Alias for 'from' keyword in advanced search
3 search_template: AcmeDemoBundle:result.html.twig # Template to use in search result page for this entity type
4 label: Demo products # Label for entity to identify entity in search results
5 route:
6 name: acme_demo_search_product # Route name to generate url link to the entity record
7 parameters: # Array with parameters for route
8 id: id
9 mode: normal # optional, default normal. Defines behavior for entities
10 title_fields: [name] # with inheritance hierarchy. See possible values in config
11 fields: # dump reference or in class constants Oro\Bundle\SearchBundle\Query\Mode
12 -
13 name: name # Name of field in entity
14 target_type: text # Type of virtual search field. Supported target types:
15 # text (string and text fields), integer, double, datetime
16 -
17 name: description
18 target_type: text
19 target_fields: [description, another_index_name] # Array of virtual fields for entity field from 'name' parameter.
20 -
21 name: manufacturer
22 relation_type: many-to-one # Indicate that this field is relation field to another table.
23 # Supported: one-to-one, many-to-many, one-to-many, many-to-one.
24 relation_fields: # Array of fields from relation record we must to index.
25 -
26 name: name # related entity field name to index
27 target_type: text # related entity field name type
28 target_fields: [manufacturer, all_data] # target fields to store field index
29 -
30 name: id
31 target_type: integer
32 target_fields: [manufacturer]
33 -
34 name: categories
35 relation_type: many-to-many
36 relation_fields:
37 -
38 name: name
39 target_type: text
40 target_fields: [all_data]
Search Engine Configuration¶
The search bundle provides the ability to use different search engines through the common interface.
Used search engine is defined in the configuration under oro_search.engine
key. To make engine work, at least one bundle must have s file with the
Resources/config/oro/search_engine/<engine_name>.yml name that contains the
configuration of search engine services that will be added to container
services.
To make the engine work, two services must be defined in the engine configuration:
search service oro_search.search.engine must implement Oro\Bundle\SearchBundle\Engine\EngineInterface.
indexer service oro_search.search.engine.indexer must implement Oro\Bundle\SearchBundle\Engine\IndexerInterface.
To make implementation easier, there are abstract classes Oro\Bundle\SearchBundle\Engine\AbstractEngine and Oro\Bundle\SearchBundle\Engine\AbstractIndexer that provide useful functionality (such as logging, queuing etc).
If the search engine requires some additional parameters (credentials, index configuration etc.), then they can be passed through the configuration using the oro_search.engine_parameters key, so these parameters can be injected into search services.
Also, engine configuration can override existing services to support some specific use cases of the search engine (e.g. ORM engine overrides index listener to support single flush).
Datagrid Configuration¶
The SearchBundle supplies a datasource that can be used interchangeably with the default ORM datasource. This datasource feeds pure search index data, bypassing the default DBMS, thus allowing pure index storage layer driven datagrids to be built.
The following is an example of a DatagridBundle’s configuration entry in the
Resources/config/oro/datagrids.yml file that builds a simple user
datagrid using search index data only:
1 user-search-grid:
2 source:
3 type: search
4 query:
5 select:
6 - text.username as name
7 - text.email
8 from:
9 - oro_user
10 columns:
11 name:
12 label: oro.user.username.label
13 data_name: name
14 email:
15 label: oro.user.email.label
16 data_name: email
17 sorters:
18 columns:
19 name:
20 data_name: username
21 type: string
22 email:
23 data_name: email
24 type: string
25 default:
26 name: ASC
27 filters:
28 columns:
29 quick_search:
30 label: 'Quick search'
31 type: string
32 data_name: all_text
33 name:
34 type: string
35 data_name: username
36 email:
37 type: string
38 data_name: email
39 properties:
40 id: ~
41 view_link:
42 type: url
43 route: oro_user_view
44 params:
45 - id
46 update_link:
47 type: url
48 route: oro_user_update
49 params:
50 - id
51 delete_link:
52 type: url
53 route: oro_api_delete_user
54 params:
55 - id
56 actions:
57 view:
58 type: navigate
59 label: oro.grid.action.view
60 link: view_link
61 icon: eye
62 acl_resource: oro_user_user_view
63 rowAction: true
64 update:
65 type: navigate
66 label: oro.grid.action.update
67 link: update_link
68 icon: edit
69 acl_resource: oro_user_user_update
70 delete:
71 type: delete
72 label: oro.grid.action.delete
73 link: delete_link
74 icon: trash
75 acl_resource: oro_user_user_delete