Search Modifiers
Search modifiers can influence the search results by modifying the search query. They can be used to filter, sort or aggregate the search results.
Search modifiers can be added to the search via the addModifier() method of the search object.
$search->addModifier(new ParentIdFilter(1))
Available Search Modifiers
Filters
| Modifier | Modifier Category | Description |
|---|---|---|
| IdFilter | Basic filters | Filter by element ID |
| IdsFilter | Basic filters | Filter by multiple element IDs |
| ExcludeFoldersFilter | Basic filters | Exclude folders from search result |
| ParentIdsFilter | Tree related filters | Filter by parent ID |
| PathFilter | Tree related filters | Filter by path (depending on use case for all levels or direct children only and with or without the parent item included) |
| TagFilter | Tree related filters | Filter by tag IDs (it is also possible to include child tags) |
| AssetMetaDataFilter | Asset filters | Filter by asset meta data attribute. The format of the $data which needs to be passed depends on the type of the meta data attribute and is handled by its field definition adapter. |
| WorkspaceQuery | Workspace related filters | Filter based on the user workspaces and permissions for a defined element type (this query is added to the asset/document/data object search by default) |
| ElementWorkspacesQuery | Workspace related filters | Filter based on the user workspaces and permissions respecting all element types (this query is added to the element search by default) |
| MultiSelectFilter | Field type filters | Filter text fields by a list of exact strings. Supports PQL field name resolution. |
| DateFilter | Field type filters | Filter date fields based on an exact date or a range of dates. Supports PQL field name resolution. |
Full Text Search Queries
| Modifier | Modifier Category | Description |
|---|---|---|
| ElementKeySearch | Full text search | Search by element key like in the studio UI with wildcard support. |
| WildcardSearch | Full text search | Filter text fields based on search terms with wildcard support and PQL field name resolution support. |
Dependencies
| Modifier | Modifier Category | Description |
|---|---|---|
| RequiresFilter | Dependencies | Get all elements which the given element requires. |
| RequiredByFilter | Dependencies | Get all elements which are required by the given element. |
Query Language
| Modifier | Modifier Category | Description |
|---|---|---|
| PqlFilter | Query Language | Apply a Pimcore Query Language (PQL) condition. |
Sort Modifiers
If multiple sort modifiers are added to the search, the order of the modifiers is important. The search result will be sorted by the first added modifier first, then by the second added modifier and so on.
| Modifier | Modifier Category | Description |
|---|---|---|
| OrderByFullPath | Tree related sorting | Order by full path (including element key) |
| OrderByField | Field based sorting | Order by given field name. If $enablePqlFieldNameResolution is set to true (default) Pimcore Query Language field name resolution logic is enabled. Therefore it's possible to use short field names then instead of specifying the full path in OpenSearch. |
| OrderByPageNumber | Search related sorting | Use inverted search for large amounts of data (this modifier is added to the search when there are at least 1000 results by default, and page number is above the half of total pages. Furthermore, existing sorting has to be already applied.) |
| OrderByIndexField | Search related sorting | Order by object tree index for custom tree sorting. This modifier is currently applied only for data objects! |
Aggregations
| Modifier | Modifier Category | Description |
|---|---|---|
| ChildrenCountAggregation | Tree related aggregation | Get children counts for given element IDs. |
| AssetMetaDataAggregation | Assets | Used for the filters in the asset grid to aggregate the filter options for supported meta data types. |
| FileSizeSumAggregation | Assets | Aggregates the sum of file sizes for all assets for a given search. The FileSizeAggregationServiceInterface internally uses this aggregation and provides an easy way to use this functionality. |
Search Modifier Implementation Details
Wildcard support
For some search modifiers, wildcard support is available. Wildcards support the following characters:
*can be used to match any sequence of characters, regardless of length - for example "Car*" to find all items starting with "Car".?can be used to match exactly one character - for example "Car?" to find all items starting with "Car" and having one more character.
PQL field name resolution
Some modifiers support Pimcore Query Language (PQL) field name resolution by setting $enablePqlFieldNameResolution to true (enabled by default). Therefore, it's possible to use short field names then instead of specifying the full path in OpenSearch.
Add your own search modifier
To add a custom search modifier implementation two steps are necessary:
-
Create a new class that implements the
Pimcore\Bundle\GenericDataIndexBundle\Model\Search\Modifier\ModifierInterfaceinterface. This model class should contain all configurable attributes for the modifier. Take a look at the IdFilter for an example. -
Create a service to implement the logic behind the modifier and add the AsSearchModifierHandler attribute. The attribute can either be directly added to the method which implements to logic or to a class. If added to a class the ´__invoke` method will be used as the handler.
The implemented method needs exactly two arguments.:
- First argument: the modifier model (see step 1).
- Second argument: SearchModifierContextInterface $context
Take a look at the BasicFilters for an example and the OpenSearch search models documentation for more details about the search models to manipulate the search.