---
title: "tx_solr.search"
manual: "Apache Solr for TYPO3"
version: "main"
permalink: "https://docs.typo3.org/permalink/apache-solr-for-typo3/solr:configuration-reference-solrsearch@main"
source: "Configuration/Reference/TxSolrSearch.rst"
modified: "2026-09-16T13:53:01+00:00"
---
# tx_solr.search
The search section, you probably already guessed it, provides configuration options for the all things related to actually searching the index, setting query parameters, formatting and processing result documents and the result listing.
## targetPage
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.targetPage
- *Default:*
- *Since:* 1.0
Sets the target page ID for links. If it is empty or 0, the current page ID will be used.
Note: This setting can be overwritten by the plugins flexform.
## trustedFields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.trustedFields
- *Default:* url
- *Since:* 3.1
The data in EXT:solr is escaped right after the retrieval from Solr. In rare cases when you need to store HTML in Solr documents you can use this configuration to mark these fields as trusted fields and skip the escaping. Typically this is needed when you want to retrieve html from solr.
> The following example shows how to avoid html in the content field:
```typoscript
plugin.tx_solr.search.trustedFields = url, content
```
## initializeWithEmptyQuery
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.initializeWithEmptyQuery
- *Default:*
- *Options:* 0,1
- *Since:* 1.0
If enabled, the results plugin (pi_results) issues a "get everything" query during initialization. This is useful, if you want to create a page that shows all available facets although no search has been issued by the user yet. Note: Enabling this option alone will not show results of the get everything query. To also show the results of the query, see option showResultsOfInitialEmptyQuery below.
## showResultsOfInitialEmptyQuery
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.showResultsOfInitialEmptyQuery
- *Default:*
- *Options:* 0,1
- *Since:* 1.0
Requires initializeWithEmptyQuery (above) to be enabled to have any effect. If enabled together with initializeWithEmptyQuery the results of the initial "get everything" query are shown. This way, in combination with a filter you can easily list a predefined set of results.
## keepExistingParametersForNewSearches
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.keepExistingParametersForNewSearches
- *Default:*
- *Options:* 0,1
- *Since:* 2.0
When doing a new search, existing parameters like filters will be carried over to the new search. This is useful for a scenario where you want to list all available documents first, then allow the user to filter the documents using facets and finally allow him to specify a search term to refine the search.
## ignoreGlobalQParameter
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.ignoreGlobalQParameter
- *Default:*
- *Options:* 0,1
- *Since:* 7.0
In some cases you want EXT:solr to react on the parameter "q" in the url. Normally plugins are bounded to a namespace to allow multiple instances of the search on the same page. In this case you might want to disable this and let EXT:solr only react on the namespaced query parameter (tx_solr\[q\] by default).
## additionalPersistentArgumentNames
- *Type:* String
- *TS Path:* plugin.tx_solr.search.additionalPersistentArgumentNames
- *Since:* 8.0
Comma-separated list of additional argument names, that should be added to the persistent arguments that are kept for sub request, like the facet and sorting urls. Hard coded argument names are q, filter and sort.
Till Solr version 6.5.x all parameters of the plugin namespace was added to the url again. With this setting you could enable this behavior again, but only with a whitelist of argument names.
## query
The query sub-section defines a few query parameters for the query that will be sent to the Solr server later on. Some query parameters are also generated and set by the extension itself, f.e. when using facets.
### query.type
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.type
- *Default:*
- *Options:* 0,1
- *Since:* 12.1.0, 13.1.0
Allows to configure the query type that should be configured
- 0: default score based Solr search (= well-known behaviour since EXT:solr started)
- 1: pure vector based search (requires additional configuration and an LLM)
> [!NOTE]
> A full reindex is required if vector search is enabled, as vectors are only created if vector search is active
> [!NOTE]
> As no classic search term is used/available for the pure vector search, the highlighting component will not work. Using the siteHighlighting and an adjusted JavaScript could be an alternative approach.
> [!NOTE]
> Field `vectorContent` is used as a basis for vector generation, by default the contents of the `content` field are used, but you can define the contents via TypoScript
>
> **How to define the contents of the vector field**
>
> ```typoscript
> plugin.tx_solr.index.queue.news.fields {
> vectorContent = SOLR_CONTENT
> vectorContent.cObject = COA
> vectorContent.cObject {
> 10 = TEXT
> 10 {
> field = name
> }
>
> 15 = TEXT
> 15 {
> field = bodytext
> }
> }
> }
> ```
### query.allowEmptyQuery
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.allowEmptyQuery
- *Default:*
- *Options:* 0,1
- *Since:* 1.4
If enabled, empty queries are allowed.
### query.allowedSites
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.allowedSites
- *Since:* 2.2
- *Default:* \_\_solr_current_site
When indexing documents (pages, records, files, ...) into the Solr index, the Solr extension adds a "siteHash". The siteHash is used to allow indexing multiple sites into one index and still have each site only find its own documents. This is achieved by adding a filter on the siteHash.
Sometimes though, you want to search across multiple domains, then the siteHash is a blocker. Using the allowedSites setting you can set a comma-separated list of domains who's documents are allowed to be included in the current domain's search results. The default value is **\_\_solr_current_site** which is a magic string/variable that is replaced with the current site's domain when querying the Solr server.
- *Since:* 3.0
Version 3.0 introduced a couple more magic keywords that get replaced:
- **\_\_current_site** same as **\_\_solr_current_site**
- **\_\_all** Adds all domains as allowed sites
- \* (asterisk character) Everything is allowed as siteHash (same as no siteHash check). This option should only be used when you need a search across multiple system and you know the impact of turning of the siteHash check.
**Security note (since fix for CVE-2026-56094):** the `siteHash` filter is a security boundary, not a user-facing search option.
It cannot be set or overridden through request-provided `tx_solr[additionalFilters]` — the reserved names `siteHash` and `access` are stripped from request input before the query is built.
To search across sites, use the `allowedSites` setting above; passing a `siteHash` filter from the frontend has no effect.
### query.allowSolrOperatorSyntax
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.allowSolrOperatorSyntax
- *Default:* 1
- *Options:* 0,1
- *Since:* 13.1.4, 14.0
Controls how much Solr/Lucene query syntax survives in `tx_solr[q]`.
Selector, range, grouping and metacharacters (`: [ ] ( ) { } ^ " ~ \ /`) are always escaped at the user-input boundary regardless of this setting, so field-targeted enumeration and range injection cannot reach Solr.
- `1` (default) — the well-known Lucene operators `+ - && || ! * ?` pass through, so the documented wildcard and boolean operator UX (`apple*`, `+foo -bar`) keeps working.
- `0` — strict mode; the additional SolrJ specials `| & ;` are also escaped. `+ - ! * ?` and whitespace stay literal, so required/prohibited terms, `NOT` and the wildcard UX still function.
### query.getParameter
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.getParameter
- *Since:* 2.2
- *Default:* tx_solr|q
The GET query parameter name used in URLs. Useful for cases f.e. when a website tracking tool does not support the default array GET parameters.
The option expects a string, you can also define an array in the form of arrayName|arrayKey.
Example:
```typoscript
plugin.tx_solr.search.query.getParameter = q
```
### query.queryFields (query.fields)
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.queryFields
- *Since:* 1.0
- *Default:* content^40.0, title^5.0, keywords^2.0, tagsH1^5.0, tagsH2H3^3.0, tagsH4H5H6^2.0, tagsInline^1.0, description^4.0, abstract^1.0, subtitle^1.0, navtitle^1.0, author^1.0
- *Note:* query.fields has been renamed to query.queryFields in version 3.0
Defines what fields to search in the index. Fields are defined as a comma separated list. Each field can be given a boost by appending the boost value separated by the ^ character, that's Lucene query language. The boost value itself is a float value, pay attention to using a dot as the separator for the fractions. Use this option to add more fields to search.
The boost take influence on what score a document gets when searching and thus how documents are ranked and listed in the search results. A higher score will move documents up in the result listing. The boost is a multiplier for the original score value of a document for a search term.
By default if a search term is found in the content field the documents gets scored / ranked higher as if a term was found in the title or keywords field. Although the default should provide a good setting, you can play around with the boost values to find the best ranking for your content.
> [!NOTE]
> Fields must be of a Solr `text` type — either the predefined `title` or `content` fields, or dynamic fields like `*_textS` / `*_textM`. These types are tokenized, stemmed, and analyzed for full-text search.
> `string` type fields (e.g. `*_stringS`) store raw, unprocessed values and only support exact, case-sensitive matches — they are **not** suitable for user-facing search.
> See [Appendix - Dynamic Fields](https://docs.typo3.org/permalink/apache-solr-for-typo3/solr:appendix-dynamic-fields@main) for available field types and the [FAQ - Frequently Asked Questions](https://docs.typo3.org/permalink/apache-solr-for-typo3/solr:faq-index@main) section on `stringS` vs `textS` for more details.
### query.userFields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.userFields
- *Default:* (empty — derived from `query.queryFields`)
- *Since:* 13.1.4, 14.0
Whitelist of fields that a Solr field-selector (`field:value`) in `tx_solr[q]` may target.
By default the whitelist is derived from `query.queryFields` — only fields listed in `qf` are addressable via selector.
Selectors against fields outside the whitelist are treated as literal terms and silently miss.
A scalar value replaces the derived whitelist with a whitespace-separated list of field names:
```typoscript
plugin.tx_solr.search.query.userFields = title content fileExtension
```
Alternatively the `add` and `remove` sub-keys apply comma-separated deltas on top of the qf-derived base list (used only when the scalar value is empty):
```typoscript
plugin.tx_solr.search.query.userFields {
add = customField, fileExtension
remove = abstract
}
```
### query.userFields.add
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.userFields.add
- *Default:* (empty)
- *Since:* 13.1.4, 14.0
Comma-separated list of field names to add to the qf-derived user-field whitelist.
Applied only when the scalar `query.userFields` value is empty.
### query.userFields.remove
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.userFields.remove
- *Default:* (empty)
- *Since:* 13.1.4, 14.0
Comma-separated list of field names to remove from the qf-derived user-field whitelist.
Applied only when the scalar `query.userFields` value is empty.
### query.returnFields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.returnFields
- *Since:* 3.0
- *Default:* \*, score
Limits the fields returned in the result documents, by default returns all field plus the virtual score field.
### query.minimumMatch
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.minimumMatch
- *Since:* 1.2, 2.0
- *Default:* (empty)
- *See:* [Apache Solr Reference Guide / mm (Minimum Should Match) Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#mm-minimum-should-match-parameter)
Sets the minimum match mm query parameter.
By default the mm query parameter is set in solrconfig.xml as 2<-35%. This means that for queries with less than three words they all must match the searched fields of a document. For queries with three or more words at least 65% of them must match rounded up.
Please consult the link to the Solr wiki for a more detailed description of the mm syntax.
### query.boostFunction
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.boostFunction
- *Since:* 1.2, 2.0
- *Default:* (empty)
- *See:* [Apache Solr Reference Guide / bf (Boost Functions) Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#bf-boost-functions-parameter)
- *See:* [Apache Solr Reference Guide / Function Queries](https://solr.apache.org/guide/solr/10_0/query-guide/function-queries.html)
- *Example:* recip(ms(NOW,created),3.16e-11,1,1)
A boost function can be useful to influence the relevance calculation and boost some documents to appear more at the beginning of the result list.
Technically the parameter will be mapped to the **"bf"** parameter in the Solr query.
Use cases for example could be:
**"Give newer documents a higher priority":**
This could be done with a recip function:
```bash
recip(ms(NOW,created),3.16e-11,1,1)
```
**"Give documents with a certain field value a higher priority":**
This could be done with:
```bash
termfreq(type,'tx_solr_file')
```
### query.boostQuery
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.query.boostQuery
- *Since:* 2.0
- *Default:* (empty)
- *See:* [Apache Solr Reference Guide / bq (Boost Query) Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#bq-boost-query-parameter)
Sets the boost function **bq** query parameter.
Allows to further manipulate the score of a document by using Lucene syntax queries. A common use case for boost queries is to rank documents of a specific type higher than others.
Please consult the link to the Solr wiki for a more detailed description of boost functions.
Example (boosts tt_news documents by factor 10):
```typoscript
plugin.tx_solr.search.query.boostQuery.boostNews = type:tt_news^10
```
### query.tieParameter
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.tieParameter
- *Since:* 8.0
- *See:* [Apache Solr Reference Guide / tie (Tie Breaker) Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#the-tie-tie-breaker-parameter)
This parameter ties the scores together. Setting is to "0" (default) uses the maximum score of all computed scores.
A value of "1.0" adds all scores. The value is a number between "0.0" and "1.0".
### query.filter
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.query.filter
- *Since:* 1.0
- *See:* [Apache Solr Reference Guide / Standard Query Parser](https://solr.apache.org/guide/solr/10_0/query-guide/standard-query-parser.html)
Allows to predefine filters to apply to a search query. You can add multiple filters through a name to Lucene filter mapping. The filters support stdWrap.
Example:
```typoscript
plugin.tx_solr.search.query.filter {
pagesOnly = type:pages
johnsPages = author:John
badKeywords = {foo}
badKeywords.wrap = -keywords:|
badKeywords.data = GP:q
}
```
Note: When you want to filter for something with whitespaces you might need to quote the filter term.
```typoscript
plugin.tx_solr.search.query.filter {
johnsDoesPages = author:"John Doe"
}
```
### query.filter.\_\_pageSections
- *Type:* comma-separated list of page IDs
- *TS Path:* plugin.tx_solr.search.query.filter.\_\_pageSections
- *Since:* 3.0
This is a magic/reserved filter (thus the double underscore). It limits the query and the results to certain branches/sections of the page tree. Multiple starting points can be provided as a comma-separated list of page IDs.
Since version 11.5.6 it's possible to apply a stdWrap to it.
Example:
```typoscript
plugin.tx_solr.search.query.filter {
__pageSections = TEXT
__pageSections.data = leveluid:0
}
```
**Note:** For this magic filter to work properly all documents require the hierarchical field `rootline`!
Examples of how to fill `rootline` for news and files:
```typoscript
plugin.tx_solr.index.queue {
news.fields.rootline = {$plugin.tx_news.settings.detailPid}
_FILES.pageContext.__RecordContext.rootline = pid
}
```
### query.sortBy
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.sortBy
- *Since:* 1.0
Allows to set a custom sorting for the query. By default Solr will sort by relevance, using this setting you can sort by a custom field.
Needs a Solr field name followed by asc for ascending order or desc for descending.
> [!NOTE]
> The field must be a sort-compatible Solr type: `string` (with `docValues`), `int`, `long`, `float`, `double`, or `date`.
> `text` type fields (like `title`) are tokenized and **cannot** be used for sorting — use dedicated sort fields like `sortTitle` instead.
> See [Appendix - Dynamic Fields](https://docs.typo3.org/permalink/apache-solr-for-typo3/solr:appendix-dynamic-fields@main) for which field types support sorting.
Example:
```typoscript
plugin.tx_solr.search.query.sortBy = sortTitle asc
```
### query.phrase
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.phrase
- *Since:* 8.0
- *Default:*
- *See:* "pf", "ps", "qs" [https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#pf-phrase-fields-parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#pf-phrase-fields-parameter)
This parameter enables the phrase search feature from Apache Solr. Setting is to "0" (default) does not change behaviour from Apache Solr if user searches for two and more words.
Enabling phrase search feature influences the document set and/or the scores of documents.
### query.phrase.fields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.phrase.fields
- *Since:* 8.0
- *Default:* content^10.0, title^10.0, tagsH1^10.0, tagsH2H3^10.0, tagsH4H5H6^10.0, tagsInline^10.0, description^10.0, abstract^10.0, subtitle^10.0, navtitle^10.0
- *See:* "pf" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#pf-phrase-fields-parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#pf-phrase-fields-parameter)
This parameter defines what fields should be used to search in the given phrase. Matched documents will be boosted according to fields boost value.
Fields are defined as a comma separated list and same way as queryFields.
Note: The value of this setting has NO influence on explicit phrase search.
### query.phrase.slop
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.query.phrase.slop
- *Since:* 8.0
- *Default:*
- *See:* "ps" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#ps-phrase-slop-parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#ps-phrase-slop-parameter)
This parameter defines the "phrase slop" value, which represents the number of positions one word needs to be moved in relation to another word in order to match a phrase specified in a query.
Note: The value of this setting has NO influence on explicit phrase search.
### query.phrase.querySlop
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.query.phrase.querySlop
- *Since:* 8.0
- *Default:*
- *See:* "qs" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#qs-query-phrase-slop-parameter](https://solr.apache.org/guide/solr/10_0/query-guide/dismax-query-parser.html#qs-query-phrase-slop-parameter)
This parameter defines the "phrase slop" value, which represents the number of positions one word needs to be moved in relation to another word in order to match a phrase specified in a explicit phrase search query.
Note: On explicit("double quoted" phrase) phrase search Apache Solr searches in "qf" queryFields
- **Note: The value of this setting has no influence on implicit phrase search.**
On explicit phrase search the Solr searches in qf (plugin.tx_solr.search.query.queryFields) defined fields.
### query.bigramPhrase
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.bigramPhrase
- *Since:* 8.0
- *Default:*
- *See:* "pf2", "ps2" [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter enables the bigram phrase search feature from Apache Solr. Setting is to "0" (default) does not change behaviour from Apache Solr if user searches for three and more words.
Enabling bigram phrase search feature influences the scores of documents with phrase occurrences.
### query.bigramPhrase.fields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.bigramPhrase.fields
- *Since:* 8.0
- *Default:* content^10.0, title^10.0, tagsH1^10.0, tagsH2H3^10.0, tagsH4H5H6^10.0, tagsInline^10.0, description^10.0, abstract^10.0, subtitle^10.0, navtitle^10.0
- *See:* "pf2" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter defines what fields should be used to search in the given sentence(three+ words). Matched documents will be boosted according to fields boost value.
Fields are defined as a comma separated list and same way as queryFields.
Note: The value of this setting has NO influence on explicit phrase search.
### query.bigramPhrase.slop
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.query.bigramPhrase.slop
- *Since:* 8.0
- *Default:*
- *See:* "ps2" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter defines the "bigram phrase slop" value, which represents the number of positions one word needs to be moved in relation to another word in order to match a phrase specified in a query.
Note: The value of this setting has NO influence on explicit phrase search.
### query.trigramPhrase
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.query.trigramPhrase
- *Since:* 8.0
- *Default:*
- *See:* "pf3", "ps3" [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter enables the phrase search feature from Apache Solr. Setting is to "0" (default) does not change behaviour from Apache Solr if user searches for two and more words.
Enabling phrase search feature influences the scores of documents with phrase occurrences.
### query.trigramPhrase.fields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.query.trigramPhrase.fields
- *Since:* 8.0
- *Default:* content^10.0, title^10.0, tagsH1^10.0, tagsH2H3^10.0, tagsH4H5H6^10.0, tagsInline^10.0, description^10.0, abstract^10.0, subtitle^10.0, navtitle^10.0
- *See:* "pf3" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter defines what fields should be used to search in the given phrase. Matched documents will be boosted according to fields boost value.
Fields are defined as a comma separated list and same way as queryFields.
Note: The value of this setting has NO influence on explicit phrase search.
### query.trigramPhrase.slop
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.query.trigramPhrase.slop
- *Since:* 8.0
- *Default:*
- *See:* "ps3" parameter [https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters](https://solr.apache.org/guide/solr/10_0/query-guide/edismax-query-parser.html#extended-dismax-parameters)
This parameter defines the "trigram phrase slop" value, which represents the number of positions one word needs to be moved in relation to another word in order to match a phrase specified in a query.
Note: The value of this setting has NO influence on explicit phrase search.
### query.vectorSearch.minimumSimilarity
- *Type:* Float
- *TS Path:* plugin.tx_solr.search.query.vectorSearch.minimumSimilarity
- *Default:* 0.75
- *Since:* 12.1.0, 13.1.0
By default only documents with at least 0.75 of vector similarity score are returned, highest similarity score is 1.
The calculated vector similarity score is returned in field `$q_vector`
> [!NOTE]
> This setting is only relevant if pure vector queries are used (query.type = 1).
### query.vectorSearch.topK
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.query.vectorSearch.topK
- *Default:* 1000
- *Since:* 12.1.0, 13.1.0
Number of documents to return in vector search.
> [!NOTE]
> This setting is only relevant if pure vector queries are used (query.type = 1).
## results
### results.resultsHighlighting
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.results.resultsHighlighting
- *Since:* 1.0
- *Default:*
- *See:* [Apache Solr Reference Guide / Unified Highlighter](https://solr.apache.org/guide/solr/10_0/query-guide/highlighting.html#the-unified-highlighter)
En-/disables search term highlighting on the results page.
> [!NOTE]
> The Unified Highlighter is used unconditionally (Since 14.0, and 13.1.4), regardless of `fragmentSize`.
> It replaces the FastVectorHighlighter, which crashed with HTTP 500 on `field:*` queries
> and thereby exposed a field-existence oracle on the indexed schema (CVE-2026-56096).
> When Solr cannot build a highlighted snippet for a field, it returns a leading-text default summary
> of approximately `hl.snippets * fragmentSize` characters instead, so a result that matched only in
> `title`, `keywords` or a heading field still gets a teaser.
> [!NOTE]
> The highlighting component will not work for vector search (`query.type=1`), as no classic search term is used/available to be highlighted. Using the siteHighlighting and an adjusted JavaScript could be an alternative approach.
### results.resultsHighlighting.highlightFields
- *Type:* String
- *TS Path:* plugin.tx_solr.search.results.resultsHighlighting.highlightFields
- *Since:* 1.0
- *Default:* content
A comma-separated list of fields to highlight.
Note: The Unified Highlighter is requested with `hl.offsetSource=ANALYSIS`, so it re-analyzes the stored
field value at query time instead of reading offsets from the index.
Highlighted fields therefore only need to be **stored=true**;
**termVectors**, **termPositions** and **termOffsets** are no longer required.
If you add other fields here, make sure that they are stored.
### results.resultsHighlighting.fragmentSize
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.results.resultsHighlighting.fragmentSize
- *Since:* 1.0
- *Default:* 200
The size, in characters, of fragments to consider for highlighting. "0" indicates that the whole field value should be used (no fragmenting).
### results.resultsHighlighting.fragmentSeparator
- *Type:* String
- *TS Path:* plugin.tx_solr.search.results.resultsHighlighting.fragmentSeparator
- *Since:* 3.0
- *Default:* \[...\]
When highlighting is activated Solr highlights the fields configured in highlightFields and can return multiple fragments of fragmentSize around the highlighted search word. These fragments are used as teasers in the results list. fragmentSeparator allows to configure the glue string between those fragments.
### results.resultsHighlighting.wrap
- *Type:* String
- *TS Path:* plugin.tx_solr.search.results.resultsHighlighting.wrap
- *Since:* 1.0
- *Default:* \|\
The wrap for search terms to highlight.
### results.siteHighlighting
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.results.siteHighlighting
- *Since:* 2.0
- *Default:*
Activates TYPO3's highlighting of search words on the actual pages. The words a user searched for will be wrapped with a span and CSS class csc-sword
Highlighting can be styled using the CSS class csc-sword, you need to add the style definition yourself for the complete site.
### results.resultsPerPage
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.results.resultsPerPage
- *Since:* 1.0
- *Default:* {$plugin.tx_solr.search.results.resultsPerPage}
Sets the number of shown results per page.
### results.resultsPerPageSwitchOptions
- *Type:* String
- *TS Path:* plugin.tx_solr.search.results.resultsPerPageSwitchOptions
- *Since:* 1.0
- *Default:* 10, 25, 50
Defines the shown options of possible results per page.
### results.maxPaginatorLinks
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.results.maxPaginatorLinks
- *Since:* 11.5
- *Default:*
Sets the number of shown page links in the paginator.
### results.showDocumentScoreAnalysis
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.results.showDocumentScoreAnalysis
- *Since:* 2.5-dkd
- *Default:*
- *Options:* 0,1
If enabled, the analysis and display of the score analysis for logged in backend users will be initialized.
## spellchecking
### spellchecking
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.spellchecking
- *Since:* 1.0
- *Default:*
Set `plugin.tx_solr.search.spellchecking = 1` to enable spellchecking / did you mean.
### spellchecking.searchUsingSpellCheckerSuggestion
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.spellchecking.searchUsingSpellCheckerSuggestion
- *Since:* 4.0
- *Default:*
This setting can be used to trigger a new search automatically when the previous search had no results but
suggestions from the spellchecking. In this case the user can directly see the results of the best correction option.
## lastSearches
### lastSearches
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.lastSearches
- *Since:* 1.3-dkd
- *Default:*
Set `plugin.tx_solr.search.lastSearches = 1` to display a list of the last searches.
### lastSearches.limit
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.lastSearches.limit
- *Since:* 1.3-dkd
- *Default:* 10
Defines the number of last searches, that should get minded.
### lastSearches.mode
- *Type:* String
- *TS Path:* plugin.tx_solr.search.lastSearches.mode
- *Since:* 1.3-dkd
- *Default:* disabled
- *Options:* user, global, disabled
If mode is user, keywords will get stored into the session. If mode is global keywords will get stored into the database. If mode is disabled, then keywords are not stored in the database.
## frequentSearches
### frequentSearches
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.frequentSearches
- *Since:* 1.3-dkd, 2.8
- *Default:*
Set `plugin.tx_solr.search.frequentSearches = 1` to display a list of the frequent / common searches.
### frequentSearches.useLowercaseKeywords
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.frequentSearches.useLowercaseKeywords
- *Since:* 2.9
- *Default:*
When enabled, keywords are written to the statistics table in lower case.
### frequentSearches.minSize
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.frequentSearches.minSize
- *Since:* 1.3-dkd, 2.8
- *Default:* 14
The difference between frequentSearches.maxSize and frequentSearches.minSize is used for calculating the current step.
### frequentSearches.maxSize
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.frequentSearches.maxSize
- *Since:* 1.3-dkd, 2.8
- *Default:* 32
The difference between frequentSearches.maxSize and frequentSearches.minSize is used for calculating the current step.
### frequentSearches.limit
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.frequentSearches.limit
- *Since:* 1.3-dkd, 2.8
- *Default:* 20
Defines the maximum size of the list by frequentSearches.select.
### frequentSearches.select
- *Type:* cObject
- *TS Path:* plugin.tx_solr.search.frequentSearches.select
- *Since:* 1.3-dkd, 2.8
Defines a database connection for retrieving statistics.
## sorting
### sorting
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.sorting
- *Since:* 1.0
- *Default:*
Set `plugin.tx_solr.search.sorting = 1` to allow sorting of results.
### sorting.defaultOrder
- *Type:* String
- *TS Path:* plugin.tx_solr.search.sorting.defaultOrder
- *Since:* 1.0
- *Default:* asc
- *Options:* asc, desc
Sets the default sort order for all sort options.
### sorting.options
This is a list of sorting options. Each option has a field and label to be used. By default the options title, type, author, and created are configured, plus the virtual relevancy field which is used for sorting by default.
Example:
```typoscript
plugin.tx_solr.search {
sorting {
options {
relevance {
field = relevance
label = Relevance
}
title {
field = sortTitle
label = Title
}
}
}
}
```
Note: As mentioned before **relevance** is a virtual field that is used to **reset** the sorting. Sorting by relevance means to have the order provided by the scoring from solr. That the reason why sorting **descending** on relevance is not possible.
### sorting.options.\[optionName\].label
- *Type:* String / stdWrap
- *TS Path:* plugin.tx_solr.search.sorting.options.\[optionName\].label
- *Since:* 1.0
Defines the name of the option's label. Supports stdWrap.
### sorting.options.\[optionName\].field
- *Type:* String / stdWrap
- *TS Path:* plugin.tx_solr.search.sorting.options.\[optionName\].field
- *Since:* 1.0
Defines the option's field. Supports stdWrap.
### sorting.options.\[optionName\].defaultOrder
- *Type:* String
- *TS Path:* plugin.tx_solr.search.sorting.options.\[optionName\].defaultOrder
- *Since:* 2.2
- *Default:* asc
- *Options:* asc, desc
Sets the default sort order for a particular sort option.
## faceting
### faceting
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting
- *Since:* 1.0
- *Default:*
Set `plugin.tx_solr.search.faceting = 1` to enable faceting.
### faceting.minimumCount
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.faceting.minimumCount
- *Since:* 1.0
- *Default:* 1
- *See:* [Apache Solr Reference Guide / facet.mincount Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/faceting.html#field-value-faceting-parameters)
This indicates the minimum counts for facet fields should be included in the response.
### faceting.sortBy
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.sortBy
- *Since:* 1.0
- *Default:* count
- *Options:* count, index, 1, 0, true, false, alpha (1.2, 2.0), lex (1.2, 2.0)
- *See:* [Apache Solr Reference Guide / facet.sort Parameter](https://solr.apache.org/guide/solr/10_0/query-guide/faceting.html#field-value-faceting-parameters)
Defines how facet options are sorted, by default they are sorted by count of results, highest on top. count, 1, true are aliases for each other.
Facet options can also be sorted alphabetically (lexicographic by indexed term) by setting the option to index. index, 0, false, alpha (from version 1.2 and 2.0), and lex (from version 1.2 and 2.0) are aliases for index.
### faceting.limit
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.faceting.limit
- *Since:* 1.0
- *Default:* 10
Number of options to display per facet. If more options are returned by Solr, they are hidden and can be expanded by clicking a "show more" link. This feature uses a small javascript function to collapse/expand the additional options.
### faceting.facetLimit
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.faceting.facetLimit
- *Since:* 6.0
- *Default:* 100
Number of options of a facet returned from solr.
### faceting.keepAllFacetsOnSelection
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.keepAllFacetsOnSelection
- *Since:* 2.2
- *Default:*
- *Options:* 0, 1
When enabled selecting an option from a facet will not reduce the number of options available in other facets.
### faceting.countAllFacetsForSelection
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.countAllFacetsForSelection
- *Since:* 8.0
- *Default:*
- *Options:* 0, 1
When ``keepAllFacetsOnSelection`` is active the count of a facet do not get reduced. You can use ``countAllFacetsForSelection`` to achieve that.
The following example shows how to keep all options of all facets by keeping the real document count, even when it has zero options:
```typoscript
plugin.tx_solr.search.faceting.keepAllFacetsOnSelection = 1
plugin.tx_solr.search.faceting.countAllFacetsForSelection = 1
plugin.tx_solr.search.faceting.minimumCount = 0
```
### faceting.showAllLink.wrap
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.showAllLink.wrap
- *Since:* 1.0
- *Default:* \|\
Defines the output of the "Show more" link, that is rendered if there are more facets given than set by faceting.limit.
### faceting.showEmptyFacets
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.showEmptyFacets
- *Since:* 1.3
- *Default:*
- *Options:* 0, 1
By setting this option to 1, you will allow rendering of empty facets. Usually, if a facet does not offer any options to filter a result-set of documents, the facet header will not be shown. Using this option allows the header still to be rendered when no filter options are provided.
### faceting.urlParameterStyle
- *Type:* Option/String (`index` or `assoc`)
- *TS Path:* plugin.tx_solr.search.faceting.urlParameterStyle
- *Since:* 11.1
- *Default:* index
Allows to change the URL style of facets.
Possible values:
- **`index`: Index style (default)**
`tx_solr[filter][0]=type:pages`, the legacy style URL
- **`assoc`: Associative style**
`tx_solr[filter][type:pages]=1`, the more modern associative style URL.
Note: The setting `faceting.urlParameterSort` will be enabled and can not be disabled.
Example:
**EXT:my_extension/Configuration/TypoScript/setup.typoscript**
```typoscript
plugin.tx_solr.search.faceting {
urlParameterStyle = assoc
}
```
### faceting.urlParameterSort
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.urlParameterSort
- *Since:* 11.1
- *Default:*
- *Note:* On faceting.urlParameterStyle = assoc, this setting can not be disabled.
Allows to enable sorting of url parameters, so the single state of facets is associated with same url, no matter in which order the facets were selected
### faceting.facetLinkUrlParameters
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facetLinkUrlParameters
- *Since:* 2.8
Allows to add URL GET parameters to the links build in facets.
### faceting.facetLinkUrlParameters.useForFacetResetLinkUrl
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facetLinkUrlParameters.useForFacetResetLinkUrl
- *Since:* 2.8
Allows to prevent adding the URL parameters to the facets reset link by setting the option to 0.
### faceting.facets
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.faceting.facets
- *Since:* 1.0
- *Default:* type
- *See:* [Apache Solr Reference Guide / Faceting](https://solr.apache.org/guide/solr/10_0/query-guide/faceting.html)
Defines which fields you want to use for faceting. It's a list of facet configurations.
```typoscript
plugin.tx_solr.search.faceting.facets {
type {
field = type
label = Content Type
}
category {
field = category_stringM
label = Category
}
}
```
### faceting.facets.\[facetName\] - single facet configuration
You can add new facets by simply adding a new facet configuration in TypoScript. \[facetName\] represents the facet's name and acts as a configuration "container" for a single facet. All configuration options for a facet are defined within that "container".
A facet will use the values of a configured index field to offer these values as filter options to your site's visitors. You need to make sure that the facet field's type allows to sort the field's value; like string, int, and other primitive types.
To configure a facet you only need to provide the label and field configuration options, all other configuration options are optional.
### faceting.facets.\[facetName\].additionalExcludeTags
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].additionalExcludeTags
- *Since:* 9.0
- *Required:* no
The settings ``keepAllOptionsOnSelection`` and ``keepAllFacetsOnSelection`` are used internally to build exclude tags for facets in order to exclude the filters from the facet counts.
This helps to keep the counts of a facet as expected by the user, in some use-cases (Read also: [http://yonik.com/multi-select-faceting/](http://yonik.com/multi-select-faceting/)).
With the setting ``additionalExcludeTags`` you can add tags of facets that should be excluded from the counts as well.
**Note:** This setting is only available for option facets by now.
### faceting.facets.\[facetName\].addFieldAsTag
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].addFieldAsTag
- *Since:* 9.0
- *Required:* no
- *Default:* false
When you want to add fields as ``additionalExcludeTags`` for a facet a tag for this facet needs to exist. You can use this setting to force the creation of a tag for this facet in the Solr query.
### faceting.facets.\[facetName\].field
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].field
- *Since:* 1.0
- *Required:* yes
Which field to use to create the facet.
### faceting.facets.\[facetName\].label
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].label
- *Since:* 1.0
- *Required:* yes
Used as a headline or title to describe the options of a facet.
Used in flex forms of plugin for filter labels. Can be translated with LLL: and consumed and translated in Partial/Facets/\* with f:translate ViewHelper.
### faceting.facets.\[facetName\].excludeValues
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].excludeValues
- *Since:* 7.0
- *Required:* no
Defines a comma separated list of options that are excluded (The value needs to match the value in solr)
Important: This setting only makes sense for option based facets (option, query, hierarchy)
### faceting.facets.\[facetName\].allowedValues
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].allowedValues
- *Since:* 13.0
- *Required:* no
Defines a comma separated list of options that should be the only ones included in the facet.
All other options will be hidden.
Important: This setting only makes sense for option based facets (option, query, hierarchy)
### faceting.facets.\[facetName\].facetLimit
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].facetLimit
- *Since:* 8.0
- *Default:* -1
Hard limit of options returned by solr.
**Note**: This is only available for options facets.
### faceting.facets.\[facetName\].metrics
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].metrics
- *Since:* 8.0
- *Default:* empty
Metrics can be use to collect and enhance facet options with statistical data of the faceted documents. They can
be used to render useful information in the context of an facet option.
Example:
```typoscript
plugin.tx_solr.search.faceting.facets {
category {
field = field
label = Category
metrics {
downloads = sum(downloads_intS)
}
}
}
```
The example above will make the metric "downloads" available for all category options. In this case it will be the sum of all downloads
of this category item. In the frontend you can render this metric with "\.metrics.downloads" and use it for example to show it instead of the normal option count.
### faceting.facets.\[facetName\].partialName
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].partialName
- *Since:* 7.0
- *Required:* no
By convention a facet is rendered by it's default partial that is located in "Resources/Private/Partials/Facets/\.html".
If you want to render a single facet with another, none conventional partial, your can configure it with "partialName = MyFacetPartial".
### faceting.facets.\[facetName\].keepAllOptionsOnSelection
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].keepAllOptionsOnSelection
- *Since:* 1.2, 2.0
- *Default:*
- *Options:* 0, 1
Normally, when clicking any option link of a facet this would result in only that one option being displayed afterwards. By setting this option to one, you can prevent this. All options will still be displayed.
This is useful if you want to allow the user to select more than one option from a single facet.
### faceting.facets.\[facetName\].operator
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].operator
- *Since:* 1.2, 2.0
- *Default:* AND
- *Options:* OR, AND
When configuring a facet to allow selection of multiple options, you can use this option to decide whether multiple selected options should be combined using AND or OR.
### faceting.facets.\[facetName\].sortBy
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].sortBy
- *Since:* 1.2
- *Default:* by count of results
- *Options:* alpha (aliases: index, lex)
Sets how a single facet's options are sorted, by default they are sorted by count of results, highest on top.
Facet options can also be sorted alphabetically by setting the option to alpha.
Note: Since 9.0.0 it is possible to sort a facet by a function. This can be done by defining a metric and use that metric in the sortBy configuration. As sorting name you then need to use by convention "metrics\_\"
Example:
```typoscript
pid {
label = Content Type
field = pid
metrics {
newest = max(created)
}
sortBy = metrics_newest desc
}
```
### faceting.facets.\[facetName\].manualSortOrder
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].manualSortOrder
- *Since:* 2.2
By default facet options are sorted by the amount of results they will return when applied. This option allows to manually adjust the order of the facet's options. The sorting is defined as a comma-separated list of options to re-order. Options listed will be moved to the top in the order defined, all other options will remain in their original order.
Example - We have a category facet like this:
```bash
News Category
+ Politics (256)
+ Sports (212)
+ Economy (185)
+ Culture (179)
+ Health (132)
+ Automobile (99)
+ Travel (51)
```
Using `faceting.facets.[facetName].manualSortOrder = Travel, Health` will result in the following order of options:
```bash
News Category
+ Travel (51)
+ Health (132)
+ Politics (256)
+ Sports (212)
+ Economy (185)
+ Culture (179)
+ Automobile (99)
```
### faceting.facets.\[facetName\].manualSortOrderDelimiter
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].manualSortOrderDelimiter
- *Since:* 11.5
- *Default:* ,
Define an alternative delimiter instead of the default comma (`,`) for the manualSortOrder option.
This is especially useful if the `,` is part of a facet option value.
### faceting.facets.\[facetName\].minimumCount
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].minimumCount
- *Since:* 8.0
- *Default:* 1
Set's the minimumCount for a single facet. This can be useful e.g. to set the minimumCount of a single facet to 0,
to have the options available even when there is result available.
**Note**: This setting is only available for facets that are using the json faceting API of solr. By now this
is only available for the options facets.
### faceting.facets.\[facetName\].reverseOrder
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].reverseOrder
- *Since:* 3.0
- *Default:*
- *Options:* 0, 1
Reverses the order of facet options.
### faceting.facets.\[facetName\].showEvenWhenEmpty
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].showEvenWhenEmpty
- *Since:* 2.0
- *Default:*
- *Options:* 0, 1
Allows you to display a facet even if it does not offer any options (is empty) and although you have set `plugin.tx_solr.search.faceting.showEmptyFacets = 0`.
### faceting.facets.\[facetName\].includeInAvailableFacets
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].includeInAvailableFacets
- *Since:* 1.3
- *Default:* 1
- *Options:* 0, 1
By setting this option to 0, you can prevent rendering of a given facet within the list of available facets.
This is useful if you render the facet somewhere else on the page using the facet view helper and don't want the facet to be rendered twice.
### faceting.facets.\[facetName\].includeInUsedFacets
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].includeInUsedFacets
- *Since:* 2.0
- *Default:* 1
- *Options:* 0, 1
By setting this option to 0, you can prevent rendering of a given facet within the list of used facets.
### faceting.facets.\[facetName\].type
- *Type:* String
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].type
- *Since:* 2.0
Defines the type of the facet. By default all facets will render their facet options as a list. PHP Classes can be registered to add new types. Using this setting will allow you to use such a type and then have the facet's options rendered and processed by the registered PHP class.
### faceting.facets.\[facetName\].\[type\]
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].\[type\]
- *Since:* 2.0
When setting a special type for a facet you can set further options for this type using this array.
Example (numericRange facet displayed as a slider):
```typoscript
plugin.tx_solr.search.faceting.facets.size {
field = size_intS
label = Size
type = numericRange
numericRange {
start = 0
end = 100
gap = 1
}
}
```
### faceting.facets.\[facetName\].requirements.\[requirementName\]
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].requirements.\[requirementName\]
- *Since:* 2.2
Allows to define requirements for a facet to be rendered. These requirements are dependencies on values of other facets being selected by the user. You can define multiple requirements for each facet. If multiple requirements are defined, all must be met before the facet is rendered.
Each requirement has a name so you can easily recognize what the requirement is about. The requirement is then defined by the name of another facet and a list of comma-separated values. At least one of the defined values must be selected by the user to meet the requirement.
There are two magic values for the requirement's values definition:
> - \_\_any: will mark the requirement as met if the user selects any of the required facet's options
> - \_\_none: marks the requirement as met if none of the required facet's options is selected. As soon as any of the required facet's options is selected the requirement will not be met and thus the facet will not be rendered
Example of a category facet showing only when the user selects the news type facet option:
```typoscript
plugin.tx_solr {
search {
faceting {
facets {
type {
label = Content Type
field = type
}
category {
label = Category
field = category_stringS
requirements {
typeIsNews {
# typeIsNews is the name of the requirement, c
# choose any so you can easily recognize what it does
facet = type
# The name of the facet as defined above
values = news
# The value of the type facet option as
# it is stored in the Solr index
}
}
}
}
}
}
}
```
### faceting.facets.\[facetName\].renderingInstruction
- *Type:* cObject
- *TS Path:* plugin.tx_solr.search.faceting.facets.\[facetName\].renderingInstruction
- *Since:* 1.0
Overwrites how single facet options are rendered using TypoScript cObjects.
Example: (taken from issue #5920)
```typoscript
plugin.tx_solr {
search {
faceting {
facets {
type {
renderingInstruction = CASE
renderingInstruction {
key.field = optionValue
pages = TEXT
pages.value = Pages
pages.lang.de = Seiten
tx_solr_file = TEXT
tx_solr_file.value = Files
tx_solr_file.lang.de = Dateien
tt_news = TEXT
tt_news.value = News
tt_news.lang.de = Nachrichten
}
}
language {
renderingInstruction = CASE
renderingInstruction {
key.field = optionValue
0 = TEXT
0.value = English
0.lang.de = Englisch
1 = TEXT
1.value = German
1.lang.de = Deutsch
}
}
}
}
}
}
```
EXT:solr provides the following renderingInstructions that you can use in your project:
**FormatDate**:
This rendering instruction can be used in combination with a date field or an integer field that hold a timestamp. You can use this rendering instruction to format the facet value on rendering.
A common use-case for this is, when the datatype in Solr needs to be sortable (date or int) but you need to render the date as readable date option in the frontend:
```typoscript
plugin.tx_solr.search.faceting.facets {
created {
field = created
label = Created
sortBy = alpha
reverseOrder = 1
renderingInstruction = TEXT
renderingInstruction {
field = optionValue
postUserFunc = ApacheSolrForTypo3\Solr\Domain\Search\ResultSet\Facets\RenderingInstructions\FormatDate->format
}
}
}
```
## elevation
### elevation
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.elevation
- *Since:* 3.0
- *Default:*
Set plugin.tx_solr.search.elevation = 1 to enable content elevation in search results.
### elevation.forceElevation
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.elevation.forceElevation
- *Since:* 3.0
- *Default:* 1
Forces content elevation to be active.
### elevation.markElevatedResults
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.elevation.markElevatedResults
- *Since:* 3.0
- *Default:* 1
If enabled, elevated results are marked with CSS class "results-elevated".
## variants
By using variants you can shrink down multiple documents with the same value
in one field into one document and make similar documents available in
the variants property.
By default the field variantId is used as Solr collapsing criteria.
This can be used e.g. as one approach of deduplication to group similar
documents into on "root" SearchResult.
To use the different variants of the documents you can
access "document.variants" to access the expanded documents.
This can be used for example for de-duplication to list variants of
the same document below a certain document.
Note: Internally this is implemented with Solr field collapsing
> [!WARNING]
> If you're additionally using the `grouping` feature, the `variants`
> feature will be deactivated completely.
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.variants
- *Since:* 6.0
- *Default:*
Set plugin.tx_solr.search.variants = 1 to enable the variants in search results.
### variants.expand
Used to expand the document variants to the document.variants property.
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.variants.expand
- *Since:* 6.0
- *Default:* 1
### variants.variantField
Used to expand the document variants to the document.variants property.
**Note:**: The field must be a numeric field or a string field! Not a
text field!
- *Type:* String
- *TS Path:* plugin.tx_solr.search.variants.variantField
- *Since:* 6.0
- *Default:* variantId
### variants.limit
Limit of expanded documents.
Though this setting limits the returned variants, you still can get the number
of existing variants, it's set in "document.variantsNumFound" (since
EXT:solr 10)
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.variants.limit
- *Since:* 6.0
- *Default:* 10
## grouping
The Solr grouping feature can be used to group documents based on a Solr field
or a set of Solr queries.
> [!NOTE]
> The `grouping` feature has a higher value than the `collapsing/variant`
> feature. So if you use the `grouping` feature, the `variant` feature
> is deactivated.
The following example shows how to group documents based on the "type" field:
```typoscript
plugin.tx_solr {
search {
grouping = 1
grouping {
numberOfGroups = 5
numberOfResultsPerGroup = 5
allowGetParameterSwitch = 0
groups {
typeGroup {
field = type
}
}
}
}
}
```
The next example shows how to group documents based on queries:
```typoscript
plugin.tx_solr {
search {
grouping = 1
grouping {
numberOfGroups = 5
numberOfResultsPerGroup = 5
allowGetParameterSwitch = 0
groups {
pidQuery {
queries {
lessThenTen = pid:[0 TO 10]
lessThen30 = pid:[11 TO 30]
rest = pid:[30 TO *]
}
}
}
}
}
}
```
### grouping.numberOfGroups
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.grouping.numberOfGroups
- *Default:* 5
- *Since:* 12.0
### grouping.numberOfResultsPerGroup
- *Type:* Integer
- *TS Path:* plugin.tx_solr.search.grouping.numberOfResultsPerGroup
- *Default:* 5
- *Since:* 12.0
### grouping.allowGetParameterSwitch
- *Type:* Boolean
- *TS Path:* plugin.tx_solr.search.grouping.allowGetParameterSwitch
- *Default:*
- *Since:* 12.0
If set, grouping can be disabled via "tx_solr\[grouping\]=off"
### grouping.groups.\[groupName\].field
- *Type:* String
- *TS Path:* plugin.tx_solr.search.grouping.groups.\[groupName\].field
- *Default:* empty
- *Since:* 12.0
Defines the Solr field where a group should be build on.
Note: Use either field or queries no mix. Groups with field are field groups,
groups with queries are query groups.
### grouping.groups.\[groupName\].queries
- *Type:* Array
- *TS Path:* plugin.tx_solr.search.grouping.groups.\[groupName\].queries
- *Default:* empty
- *Since:* 12.0
Defines an array of queries to group the results in.
Note: Use either field or queries no mix. Groups with field are field groups,
groups with queries are query groups.
### grouping.groups.\[groupName\].sortBy
- *Type:* String
- *TS Path:* plugin.tx_solr.search.grouping.groups.\[groupName\].sortBy
- *Since:* 12.0
Allows to set a custom sorting for the group. Useful especially if you have already set `plugin.tx_solr.search.query.sortBy`. By default Solr will sort within a group by relevance, using this setting you can sort by any sortable field.
Needs a Solr field name followed by asc for ascending order or desc for descending.