Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SOLR-14829: Improve documentation for Request Handlers in RefGuide and solrconfig.xml (#1921) 

Restructured documentation page, fixed cross-linked, and cleanup of relevant sections of example configuration files
This commit is contained in:
Alexandre Rafalovitch 2020-10-06 20:35:47 -04:00 committed by GitHub
parent 5039e7170b
commit 247cea1011
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 288 additions and 353 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
solr/CHANGES.txt
View File

@ -128,6 +128,8 @@ Other Changes
* SOLR-14659: Remove restlet as dependency for the ManagedResource API (Timothy Potter, noble)
* SOLR-14829: Cleanup the documentation for Request Handlers and Search Components (Alexandre Rafalovitch)
Bug Fixes
---------------------
* SOLR-14546: Fix for a relatively hard to hit issue in OverseerTaskProcessor that could lead to out of order execution

156
solr/server/solr/configsets/_default/conf/solrconfig.xml
View File

@ -735,90 +735,26 @@
<!-- Request Handlers
http://wiki.apache.org/solr/SolrRequestHandler
https://lucene.apache.org/solr/guide/requesthandlers-and-searchcomponents-in-solrconfig.html
Incoming queries will be dispatched to a specific handler by name
based on the path specified in the request.
Incoming queries will be dispatched to a specific handler by name based on the path specified in the request.
If a Request Handler is declared with startup="lazy", then it will
not be initialized until the first request that uses it.
All handlers (Search Handlers, Update Request Handlers, and other specialized types) can have default parameters (defaults, appends and invariants).
Search Handlers can also (append, prepend or even replace) default or defined Search Components.
Update Request Handlers can leverage Update Request Processors to pre-process documents after they are loaded
and before they are indexed/stored.
Not all Request Handlers are defined in the solrconfig.xml, many are implicit.
-->
<!-- SearchHandler
http://wiki.apache.org/solr/SearchHandler
For processing Search Queries, the primary Request Handler
provided with Solr is "SearchHandler" It delegates to a sequent
of SearchComponents (see below) and supports distributed
queries across multiple shards
-->
<!-- Primary search handler, expected by most clients, examples and UI frameworks -->
<requestHandler name="/select" class="solr.SearchHandler">
<!-- default values for query parameters can be specified, these
will be overridden by parameters in the request
-->
<lst name="defaults">
<str name="echoParams">explicit</str>
<int name="rows">10</int>
<!-- Default search field
<str name="df">text</str>
-->
<!-- Change from JSON to XML format (the default prior to Solr 7.0)
<str name="wt">xml</str>
-->
</lst>
<!-- In addition to defaults, "appends" params can be specified
to identify values which should be appended to the list of
multi-val params from the query (or the existing "defaults").
-->
<!-- In this example, the param "fq=instock:true" would be appended to
any query time fq params the user may specify, as a mechanism for
partitioning the index, independent of any user selected filtering
that may also be desired (perhaps as a result of faceted searching).
NOTE: there is *absolutely* nothing a client can do to prevent these
"appends" values from being used, so don't use this mechanism
unless you are sure you always want it.
-->
<!--
<lst name="appends">
<str name="fq">inStock:true</str>
</lst>
-->
<!-- "invariants" are a way of letting the Solr maintainer lock down
the options available to Solr clients. Any params values
specified here are used regardless of what values may be specified
in either the query, the "defaults", or the "appends" params.
In this example, the facet.field and facet.query params would
be fixed, limiting the facets clients can use. Faceting is
not turned on by default - but if the client does specify
facet=true in the request, these are the only facets they
will be able to see counts for; regardless of what other
facet.field or facet.query params they may specify.
NOTE: there is *absolutely* nothing a client can do to prevent these
"invariants" values from being used, so don't use this mechanism
unless you are sure you always want it.
-->
<!--
<lst name="invariants">
<str name="facet.field">cat</str>
<str name="facet.field">manu_exact</str>
<str name="facet.query">price:[* TO 500]</str>
<str name="facet.query">price:[500 TO *]</str>
</lst>
-->
<!-- If the default list of SearchComponents is not desired, that
list can either be overridden completely, or components can be
prepended or appended to the default list. (see below)
-->
<!--
<arr name="components">
<str>nameOfCustomComponent1</str>
<str>nameOfCustomComponent2</str>
</arr>
-->
</requestHandler>
<!-- A request handler that returns indented JSON by default -->
@ -830,62 +766,19 @@
</lst>
</requestHandler>
<!-- Shared parameters for multiple Request Handlers -->
<initParams path="/update/**,/query,/select,/spell">
<lst name="defaults">
<str name="df">_text_</str>
</lst>
</initParams>
<!-- Search Components
Search components are registered to SolrCore and used by
instances of SearchHandler (which can access them by name)
By default, the following components are available:
<searchComponent name="query" class="solr.QueryComponent" />
<searchComponent name="facet" class="solr.FacetComponent" />
<searchComponent name="mlt" class="solr.MoreLikeThisComponent" />
<searchComponent name="highlight" class="solr.HighlightComponent" />
<searchComponent name="stats" class="solr.StatsComponent" />
<searchComponent name="terms" class="solr.TermsComponent" />
<searchComponent name="debug" class="solr.DebugComponent" />
Default configuration in a requestHandler would look like:
<arr name="components">
<str>query</str>
<str>facet</str>
<str>mlt</str>
<str>highlight</str>
<str>stats</str>
<str>debug</str>
</arr>
If you register a searchComponent to one of the standard names,
that will be used instead of the default.
To insert components before or after the 'standard' components, use:
<arr name="first-components">
<str>myFirstComponentName</str>
</arr>
<arr name="last-components">
<str>myLastComponentName</str>
</arr>
NOTE: The component registered with the name "debug" will
always be executed after the "last-components"
-->
<!-- Spell Check
The spell check component can return a list of alternative spelling
suggestions.
http://wiki.apache.org/solr/SpellCheckComponent
https://lucene.apache.org/solr/guide/spell-checking.html
-->
<searchComponent name="spellcheck" class="solr.SpellCheckComponent">
@ -942,7 +835,7 @@
IN OTHER WORDS, THERE IS REALLY GOOD CHANCE THE SETUP BELOW IS
NOT WHAT YOU WANT FOR YOUR PRODUCTION SYSTEM!
See http://wiki.apache.org/solr/SpellCheckComponent for details
See https://lucene.apache.org/solr/guide/spell-checking.html for details
on the request parameters.
-->
<requestHandler name="/spell" class="solr.SearchHandler" startup="lazy">
@ -969,7 +862,7 @@
<!-- Highlighting Component
http://wiki.apache.org/solr/HighlightingParameters
https://lucene.apache.org/solr/guide/highlighting.html
-->
<searchComponent class="solr.HighlightComponent" name="highlight">
<highlighting>
@ -1073,29 +966,28 @@
</highlighting>
</searchComponent>
<!-- Update Processors
Chains of Update Processor Factories for dealing with Update
Requests can be declared, and then used by name in Update
Request Processors
http://wiki.apache.org/solr/UpdateRequestProcessor
<!-- Update Request Processors
https://lucene.apache.org/solr/guide/update-request-processors.html
Chains or individual Update Request Processor Factories can be declared and referenced
to preprocess documents sent to Update Request Handlers.
-->
<!-- Add unknown fields to the schema
Field type guessing update processors that will
Field type guessing update request processors that will
attempt to parse string-typed field values as Booleans, Longs,
Doubles, or Dates, and then add schema fields with the guessed
field types. Text content will be indexed as "text_general" as
field types Text content will be indexed as "text_general" as
well as a copy to a plain string version in *_str.
See the updateRequestProcessorChain defined later for the order they are executed in.
These require that the schema is both managed and mutable, by
declaring schemaFactory as ManagedIndexSchemaFactory, with
mutable specified as true.
See http://wiki.apache.org/solr/GuessingFieldTypes
See https://lucene.apache.org/solr/guide/schemaless-mode.html for further explanation.
-->
<updateProcessor class="solr.UUIDUpdateProcessorFactory" name="uuid"/>
<updateProcessor class="solr.RemoveBlankFieldUpdateProcessorFactory" name="remove-blank"/>
@ -1157,7 +1049,7 @@
<!-- Deduplication
An example dedup update processor that creates the "id" field
An example dedup update request processor chain that creates the "id" field
on the fly based on the hash code of some other fields. This
example has overwriteDupes set to false since we are using the
id field as the signatureField and Solr will maintain

168
solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml
View File

@ -738,87 +738,34 @@
<!-- Request Handlers
http://wiki.apache.org/solr/SolrRequestHandler
https://lucene.apache.org/solr/guide/requesthandlers-and-searchcomponents-in-solrconfig.html
Incoming queries will be dispatched to a specific handler by name
based on the path specified in the request.
Incoming queries will be dispatched to a specific handler by name based on the path specified in the request.
If a Request Handler is declared with startup="lazy", then it will
not be initialized until the first request that uses it.
All handlers (Search Handlers, Update Request Handlers, and other specialized types) can have default parameters (defaults, appends and invariants).
Search Handlers can also (append, prepend or even replace) default or defined Search Components.
Update Request Handlers can leverage Update Request Processors to pre-process documents after they are loaded
and before they are indexed/stored.
Not all Request Handlers are defined in the solrconfig.xml, many are implicit.
-->
<!-- SearchHandler
http://wiki.apache.org/solr/SearchHandler
For processing Search Queries, the primary Request Handler
provided with Solr is "SearchHandler" It delegates to a sequent
of SearchComponents (see below) and supports distributed
queries across multiple shards
-->
<!-- Primary search handler, expected by most clients, examples and UI frameworks -->
<requestHandler name="/select" class="solr.SearchHandler">
<!-- default values for query parameters can be specified, these
will be overridden by parameters in the request
-->
<lst name="defaults">
<str name="echoParams">explicit</str>
<int name="rows">10</int>
<!-- Default search field
<str name="df">text</str>
-->
<!-- Change from JSON to XML format (the default prior to Solr 7.0)
<str name="wt">xml</str>
-->
<!-- Controls the distribution of a query to shards other than itself.
Consider making 'preferLocalShards' true when:
1) more than 1 replica may be located on a node
2) Number of shards > 1
3) CloudSolrClient or LbHttpSolrServer is used by clients.
Without this option, every core broadcasts the distributed query to
a replica of each shard where the replicas are chosen randomly.
This option directs the cores to prefer cores hosted locally, thus
preventing network delays between machines.
This behavior also immunizes a bad/slow machine from slowing down all
the good machines (if those good machines were querying this bad one).
Specify this option=false for clients connecting through HttpSolrServer
-->
<bool name="preferLocalShards">false</bool>
</lst>
<!-- In addition to defaults, "appends" params can be specified
to identify values which should be appended to the list of
multi-val params from the query (or the existing "defaults").
-->
<!-- In this example, the param "fq=instock:true" would be appended to
any query time fq params the user may specify, as a mechanism for
partitioning the index, independent of any user selected filtering
that may also be desired (perhaps as a result of faceted searching).
NOTE: there is *absolutely* nothing a client can do to prevent these
"appends" values from being used, so don't use this mechanism
unless you are sure you always want it.
-->
<!-- "appends" example to ensure only products in stock are returned when using this Search Handler -->
<!--
<lst name="appends">
<str name="fq">inStock:true</str>
</lst>
-->
<!-- "invariants" are a way of letting the Solr maintainer lock down
the options available to Solr clients. Any params values
specified here are used regardless of what values may be specified
in either the query, the "defaults", or the "appends" params.
In this example, the facet.field and facet.query params would
be fixed, limiting the facets clients can use. Faceting is
not turned on by default - but if the client does specify
facet=true in the request, these are the only facets they
will be able to see counts for; regardless of what other
facet.field or facet.query params they may specify.
NOTE: there is *absolutely* nothing a client can do to prevent these
"invariants" values from being used, so don't use this mechanism
unless you are sure you always want it.
-->
<!-- "invariants" example that will completely lock down the facets fields and queries if the facets are turned on -->
<!--
<lst name="invariants">
<str name="facet.field">cat</str>
@ -827,16 +774,6 @@
<str name="facet.query">price:[500 TO *]</str>
</lst>
-->
<!-- If the default list of SearchComponents is not desired, that
list can either be overridden completely, or components can be
prepended or appended to the default list. (see below)
-->
<!--
<arr name="components">
<str>nameOfCustomComponent1</str>
<str>nameOfCustomComponent2</str>
</arr>
-->
</requestHandler>
<!-- A request handler that returns indented JSON by default -->
@ -855,7 +792,7 @@
</lst>
</initParams>
<!-- The following are implicitly added
<!-- The following are some of the implicit Update Request Handlers
<requestHandler name="/update/json" class="solr.UpdateRequestHandler">
<lst name="invariants">
<str name="stream.contentType">application/json</str>
@ -870,7 +807,7 @@
<!-- Solr Cell Update Request Handler
http://wiki.apache.org/solr/ExtractingRequestHandler
https://lucene.apache.org/solr/guide/uploading-data-with-solr-cell-using-apache-tika.html
-->
<requestHandler name="/update/extract"
@ -887,56 +824,12 @@
</lst>
</requestHandler>
<!-- Search Components
Search components are registered to SolrCore and used by
instances of SearchHandler (which can access them by name)
By default, the following components are available:
<searchComponent name="query" class="solr.QueryComponent" />
<searchComponent name="facet" class="solr.FacetComponent" />
<searchComponent name="mlt" class="solr.MoreLikeThisComponent" />
<searchComponent name="highlight" class="solr.HighlightComponent" />
<searchComponent name="stats" class="solr.StatsComponent" />
<searchComponent name="terms" class="solr.TermsComponent" />
<searchComponent name="debug" class="solr.DebugComponent" />
Default configuration in a requestHandler would look like:
<arr name="components">
<str>query</str>
<str>facet</str>
<str>mlt</str>
<str>highlight</str>
<str>stats</str>
<str>debug</str>
</arr>
If you register a searchComponent to one of the standard names,
that will be used instead of the default.
To insert components before or after the 'standard' components, use:
<arr name="first-components">
<str>myFirstComponentName</str>
</arr>
<arr name="last-components">
<str>myLastComponentName</str>
</arr>
NOTE: The component registered with the name "debug" will
always be executed after the "last-components"
-->
<!-- Spell Check
The spell check component can return a list of alternative spelling
suggestions.
http://wiki.apache.org/solr/SpellCheckComponent
https://lucene.apache.org/solr/guide/spell-checking.html
-->
<searchComponent name="spellcheck" class="solr.SpellCheckComponent">
@ -1030,7 +923,7 @@
IN OTHER WORDS, THERE IS REALLY GOOD CHANCE THE SETUP BELOW IS
NOT WHAT YOU WANT FOR YOUR PRODUCTION SYSTEM!
See http://wiki.apache.org/solr/SpellCheckComponent for details
See https://lucene.apache.org/solr/guide/spell-checking.html for details
on the request parameters.
-->
<requestHandler name="/spell" class="solr.SearchHandler" startup="lazy">
@ -1061,9 +954,7 @@
As with the rest of this solrconfig.xml file, the configuration of this component is purely
an example that applies specifically to this configset and example documents.
More information about this component and other configuration options are described in the
"Suggester" section of the reference guide available at
http://archive.apache.org/dist/lucene/solr/ref-guide
See: https://lucene.apache.org/solr/guide/suggester.html
-->
<searchComponent name="suggest" class="solr.SuggestComponent">
<lst name="suggester">
@ -1091,7 +982,7 @@
<!-- Term Vector Component
http://wiki.apache.org/solr/TermVectorComponent
https://lucene.apache.org/solr/guide/the-term-vector-component.html
-->
<searchComponent name="tvComponent" class="solr.TermVectorComponent"/>
@ -1129,7 +1020,6 @@
* org.carrot2.clustering.lingo.LingoClusteringAlgorithm
* org.carrot2.clustering.stc.STCClusteringAlgorithm
* org.carrot2.clustering.kmeans.BisectingKMeansClusteringAlgorithm
See http://project.carrot2.org/algorithms.html for more information.
Commercial algorithm Lingo3G (needs to be installed separately):
* com.carrotsearch.lingo3g.Lingo3GClusteringAlgorithm
@ -1203,7 +1093,7 @@
<!-- Query Elevation Component
http://wiki.apache.org/solr/QueryElevationComponent
https://lucene.apache.org/solr/guide/the-query-elevation-component.html
a search component that enables you to configure the top
results for a given query regardless of the normal lucene
@ -1227,7 +1117,7 @@
<!-- Highlighting Component
http://wiki.apache.org/solr/HighlightingParameters
https://lucene.apache.org/solr/guide/highlighting.html
-->
<searchComponent class="solr.HighlightComponent" name="highlight">
<highlighting>
@ -1331,18 +1221,15 @@
</highlighting>
</searchComponent>
<!-- Update Processors
Chains of Update Processor Factories for dealing with Update
Requests can be declared, and then used by name in Update
Request Processors
http://wiki.apache.org/solr/UpdateRequestProcessor
<!-- Update Request Processors
https://lucene.apache.org/solr/guide/update-request-processors.html
Chains or individual Update Request Processor Factories can be declared and referenced
to preprocess documents sent to Update Request Handlers.
-->
<!-- Deduplication
An example dedup update processor that creates the "id" field
An example dedup update request processor chain that creates the "id" field
on the fly based on the hash code of some other fields. This
example has overwriteDupes set to false since we are using the
id field as the signatureField and Solr will maintain
@ -1365,13 +1252,14 @@
<!-- Language identification
This example update chain identifies the language of the incoming
This example update request process chain identifies the language of the incoming
documents using the langid contrib. The detected language is
written to field language_s. No field name mapping is done.
The fields used for detection are text, title, subject and description,
making this example suitable for detecting languages form full-text
rich documents injected via ExtractingRequestHandler.
See more about langId at http://wiki.apache.org/solr/LanguageDetection
See more about langId at https://lucene.apache.org/solr/guide/detecting-languages-during-indexing.html
-->
<!--
<updateRequestProcessorChain name="langid">

2
solr/solr-ref-guide/src/analytics.adoc
View File

@ -57,7 +57,7 @@ For these changes to take effect, restart Solr or reload the core or collection.
== Request Syntax
An Analytics request is passed to Solr with the parameter `analytics` in a request sent to the
<<requesthandlers-and-searchcomponents-in-solrconfig.adoc#searchhandlers,Search Handler>>.
<<requesthandlers-and-searchcomponents-in-solrconfig.adoc#search-handlers,Search Handler>>.
Since the analytics request is sent inside of a search handler request, it will compute results based on the result set determined by the search handler.
For example, this curl command encodes and POSTs a simple analytics request to the the search handler:

8
solr/solr-ref-guide/src/common-query-parameters.adoc
View File

@ -18,7 +18,7 @@
Several query parsers share supported query parameters.
The following sections describe Solr's common query parameters, which are supported by the <<requesthandlers-and-searchcomponents-in-solrconfig#searchhandlers,Search RequestHandlers>>.
The following sections describe Solr's common query parameters, which are supported by the <<requesthandlers-and-searchcomponents-in-solrconfig#search-handlers,Search RequestHandlers>>.
== defType Parameter
@ -307,11 +307,13 @@ The `echoParams` parameter controls what information about request parameters is
The `echoParams` parameter accepts the following values:
* `explicit`: This is the default value. Only parameters included in the actual request, plus the `_` parameter (which is a 64-bit numeric timestamp) will be added to the `params` section of the response header.
* `explicit`: Only parameters included in the actual request will be added to the `params` section of the response header.
* `all`: Include all request parameters that contributed to the query. This will include everything defined in the request handler definition found in `solrconfig.xml` as well as parameters included with the request, plus the `_` parameter. If a parameter is included in the request handler definition AND the request, it will appear multiple times in the response header.
* `none`: Entirely removes the `params` section of the response header. No information about the request parameters will be available in the response.
Here is an example of a JSON response where the echoParams parameter was not included, so the default of `explicit` is active. The request URL that created this response included three parameters - `q`, `wt`, and `indent`:
The default value is `none`, though many `solrconfig.xml` handlers set default to be `explicit`.
Here is an example of a JSON response where the echoParams parameter was set in that SearchHandler's default,
so it itself was not echoed, but only three parameters from the request itself - `q`, `wt`, and `indent`:
[source,json]
----

2
solr/solr-ref-guide/src/faceting.adoc
View File

@ -20,6 +20,8 @@ Faceting is the arrangement of search results into categories based on indexed t
Searchers are presented with the indexed terms, along with numerical counts of how many matching documents were found for each term. Faceting makes it easy for users to explore search results, narrowing in on exactly the results they are looking for.
See also <<json-facet-api.adoc#json-facet-api, JSON Facet API>> for an alternative approach to this.
== General Facet Parameters
There are two general parameters for controlling faceting.

2
solr/solr-ref-guide/src/highlighting.adoc
View File

@ -141,7 +141,7 @@ The `highlighting` section includes the ID of each document, and the field that
== Choosing a Highlighter
Solr provides a `HighlightComponent` (a <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#search-components,`SearchComponent`>>) and it's in the default list of components for search handlers. It offers a somewhat unified API over multiple actual highlighting implementations (or simply "highlighters") that do the business of highlighting.
Solr provides a `HighlightComponent` (a <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#defining-search-components,`SearchComponent`>>) and it's in the default list of components for search handlers. It offers a somewhat unified API over multiple actual highlighting implementations (or simply "highlighters") that do the business of highlighting.
There are many parameters supported by more than one highlighter, and sometimes the implementation details and semantics will be a bit different, so don't expect identical results when switching highlighters. You should use the `hl.method` parameter to choose a highlighter but it's also possible to explicitly configure an implementation by class name in `solrconfig.xml`.

2
solr/solr-ref-guide/src/index-replication.adoc
View File

@ -82,7 +82,7 @@ A directory containing hard links to the data files of an index. Snapshots are d
In addition to `ReplicationHandler` configuration options specific to the leader/follower roles, there are a few special configuration options that are generally supported (even when using SolrCloud).
* `maxNumberOfBackups` an integer value dictating the maximum number of backups this node will keep on disk as it receives `backup` commands.
* Similar to most other request handlers in Solr you may configure a set of <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#searchhandlers,defaults, invariants, and/or appends>> parameters corresponding with any request parameters supported by the `ReplicationHandler` when <<HTTP API Commands for the ReplicationHandler,processing commands>>.
* Similar to most other request handlers in Solr you may configure a set of <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#search-handlers,defaults, invariants, and/or appends>> parameters corresponding with any request parameters supported by the `ReplicationHandler` when <<HTTP API Commands for the ReplicationHandler,processing commands>>.
=== Configuring the Replication RequestHandler on a Leader Server

288
solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc
View File

@ -1,4 +1,4 @@
= RequestHandlers and SearchComponents in SolrConfig
= Request Handlers and Search Components in SolrConfig
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
@ -18,34 +18,84 @@
After the `<query>` section of `solrconfig.xml`, request handlers and search components are configured.
A _request handler_ processes requests coming to Solr. These might be query requests or index update requests. You will likely need several of these defined, depending on how you want Solr to handle the various requests you will make.
A _request handler_ processes requests coming to Solr. These might be query requests, index update requests or specialized interactions such as <<ping.adoc#ping,ping>>.
A _search component_ is a feature of search, such as highlighting or faceting. The search component is defined in `solrconfig.xml` separate from the request handlers, and then registered with a request handler as needed.
Not all handlers are defined explicitly in `solrconfig.xml`, many essential ones are actually defined <<implicit-requesthandlers.adoc#implicit-requesthandlers,implicitly>>.
These are often referred to as "requestHandler" and "searchComponent", which is how they are defined in `solrconfig.xml`.
Additionally, handlers can be defined - or even overridden - in `configoverlay.json` by using <<config-api.adoc#config-api,Config API>>.
Finally, independent parameter sets can be also defined by <<request-parameters-api.adoc#request-parameters-api,Request Parameters API>>.
They will be stored in `params.json` file and referenced with <<#paramsets-and-useparams,useParams>>.
== Request Handlers
All of this multi-layered configuration, may be verified via <<config-api.adoc#config-api,Config API>>.
Every request handler is defined with a name and a class. The name of the request handler is referenced with the request to Solr, typically as a path. For example, if Solr is installed at `\http://localhost:8983/solr/` and you have a collection named "gettingstarted", you can make a request that looks like this:
Defining your own config handlers is often a useful way to provide defaults and advanced configuration to support business cases and simplify client API.
At the same time, using every single option explained in this guide, will most certainly cause some confusion about which parameter is actually used when.
== Defining and Calling Request Handlers
Every request handler is defined with a name and a class. The name of the request handler is referenced with the request to Solr, typically as a path.
For example, if Solr is installed at `\http://localhost:8983/solr/`, and you have a collection named "gettingstarted", you can make a request that looks like this:
[source,text]
----
http://localhost:8983/solr/gettingstarted/select?q=solr
----
This query will be processed by the request handler with the name `/select`. We've only used the "q" parameter here, which includes our query term, a simple keyword of "solr". If the request handler has more parameters defined, those will be used with any query we send to this request handler unless they are over-ridden by the client (or user) in the query itself.
This query will be processed by the request handler with the name `/select`. We've only used the "q" parameter here, which includes our query term, a simple keyword of "solr".
If the request handler has more default parameters defined, those will be used with any query we send to that request handler unless they are overridden by the client (or user) in the query itself.
If you have another request handler defined, you would send your request with that name. For example, `/update` is a request handler that handles index updates (i.e., sending new documents to the index). By default, `/select` is a request handler that handles query requests.
If you have another request handler defined, you could send your request with that name.
For example, `/update` is an implicit request handler that handles index updates (i.e., sending new documents to the index).
By default, `/select` is a request handler that handles query requests and one expected by most examples and tools.
Request handlers can also process requests for nested paths of their names, for example, a request using `/myhandler/extrapath` may be processed by a request handler registered with the name `/myhandler`. If a request handler is explicitly defined by the name `/myhandler/extrapath`, that would take precedence over the nested path. This assumes you are using the request handler classes included with Solr; if you create your own request handler, you should make sure it includes the ability to handle nested paths if you want to use them with your custom request handler.
Request handlers can also process requests for nested paths in their names,
for example, a request using `/myhandler/extrapath` may be processed by a request handler registered with the name `/myhandler`.
If a request handler is explicitly defined by the name `/myhandler/extrapath`, that would take precedence over the nested path.
This assumes you are using the request handler classes included with Solr; if you create your own request handler,
you should make sure it includes the ability to handle nested paths if you want to use them with your custom request handler.
It is also possible to configure defaults for request handlers with a section called `initParams`. These defaults can be used when you want to have common properties that will be used by each separate handler. For example, if you intend to create several request handlers that will all request the same list of fields in the response, you can configure an `initParams` section with your list of fields. For more information about `initParams`, see the section <<initparams-in-solrconfig.adoc#initparams-in-solrconfig,InitParams in SolrConfig>>.
If a request handler is not expected to be used very often, it can be marked with `startup="lazy"` to avoid loading until needed.
=== SearchHandlers
[source,xml]
----
<requestHandler name="/spell" class="solr.SearchHandler" startup="lazy">
...
</requestHandler>
----
The primary request handler defined with Solr by default is the "SearchHandler", which handles search queries. The request handler is defined, and then a list of defaults for the handler are defined with a `defaults` list.
== Configuring Request Handlers
There are 3 ways to configure request handlers inside their definitions and another 3 ways to configure them somewhere else.
For example, in the default `solrconfig.xml`, the first request handler defined looks like this:
=== Request Parameters (GET and POST)
The easiest and most flexible way is to provide parameters with standard GET or POST requests.
Here is an example of sending parameters `id`, `fl`, and `wt` to `/select` Search Handler.
Notice the URL-encoded space (as +) for the values of `fl` parameter.
[source,text]
----
http://localhost:8983/solr/techproducts/select?q=id:SP2514N&fl=id+name&wt=xml
----
And here is an example of parameters being sent through the POST form to `/query` Search Handler using <<json-request-api.adoc#json-request-api,JSON Request API>>.
[source,bash]
----
curl http://localhost:8983/solr/techproducts/query -d '
{
"query" : "memory",
"filter" : "inStock:true"
}'
----
Either way, the parameters are extracted and combined with other options explained below.
=== Defaults, Appends, and Invariants
==== Defaults
The most common way to configure request handlers is by providing `defaults` section.
The parameters there are used unless they are overridden by any other method.
[source,xml]
----
@ -57,24 +107,44 @@ For example, in the default `solrconfig.xml`, the first request handler defined
</requestHandler>
----
This example defines the `rows` parameter, which defines how many search results to return, to "10". The `echoParams` parameter defines that the parameters defined in the query should be returned when debug information is returned. Note also that the way the defaults are defined in the list varies if the parameter is a string, an integer, or another type.
This example defined a useful troubleshooting parameter <<common-query-parameters.adoc#echoparams-parameter,echoParams>>, with value that returns only params defined in the request itself (no defaults), set it to `all` for more information.
It also defines the `rows` parameter, with how many results to return (per page) (10 is a true default actually, so this is a redundant definition, if you are not going to modify it).
All of the parameters described in the section <<searching.adoc#searching,Searching>> can be defined as defaults for any of the SearchHandlers.
Note also that the way the defaults are defined in the list varies if the parameter is a string, an integer, or another type.
Besides `defaults`, there are other options for the SearchHandler, which are:
Here is how some other primitive types are represented:
[source,xml]
----
<lst name="defaults">
<float name="hl.regex.slop">0.5</float>
<bool name="default">true</bool>
</lst>
----
Other specialized types may exist, they would be explained in the sections for relevant components.
==== Appends
In the `appends` section, you can define parameters that are added those already defined elsewhere.
These are useful when the same parameter may be meaningfully defined multiple times, such as for <<common-query-parameters.adoc#fq-filter-query-parameter,filter queries>>.
There is no mechanism in Solr to allow a client to override these additions, so you should be absolutely sure you always want these parameters applied to queries.
* `appends`: This allows definition of parameters that are added to the user query. These might be <<common-query-parameters.adoc#fq-filter-query-parameter,filter queries>>, or other query rules that should be added to each query. There is no mechanism in Solr to allow a client to override these additions, so you should be absolutely sure you always want these parameters applied to queries.
+
[source,xml]
----
<lst name="appends">
<str name="fq">inStock:true</str>
</lst>
----
+
In this example, the filter query "inStock:true" will always be added to every query.
* `invariants`: This allows definition of parameters that cannot be overridden by a client. The values defined in an `invariants` section will always be used regardless of the values specified by the user, by the client, in `defaults` or in `appends`.
+
In this example, the filter query `inStock:true` will always be added to every query, enforcing that only available "products" are returned.
==== Invariants
In the `invariants` section, you can define parameters that cannot be overridden by a client.
The values defined in the `invariants` section will always be used regardless of the values specified by the user, by the client, in `defaults` or in `appends`.
[source,xml]
----
<lst name="invariants">
@ -84,42 +154,77 @@ In this example, the filter query "inStock:true" will always be added to every q
<str name="facet.query">price:[500 TO *]</str>
</lst>
----
+
In this example, facet fields have been defined which limits the facets that will be returned by Solr. If the client requests facets, the facets defined with a configuration like this are the only facets they will see.
The final section of a request handler definition is `components`, which defines a list of search components that can be used with a request handler. They are only registered with the request handler. How to define a search component is discussed further on in the section on <<Search Components>> below. The `components` element can only be used with a request handler that is a SearchHandler.
In this example, the `facet.field` and `facet.query` params would be fixed, limiting the facets clients can use.
Faceting is not turned on by default - but if the client does specify `facet=true` in the request,
these are the only facets they will be able to see counts for; regardless of what other `facet.field` or `facet.query` params they may specify.
The `solrconfig.xml` file includes many other examples of SearchHandlers that can be used or modified as needed.
=== InitParams
It is also possible to configure defaults for request handlers with a section called `initParams`.
These defaults can be used when you want to have common properties that will be used by each separate handler.
For example, if you intend to create several request handlers that will all request the same list of fields in the response, you can configure an `initParams` section with your list of fields.
For more information about `initParams`, see the section <<initparams-in-solrconfig.adoc#initparams-in-solrconfig,InitParams in SolrConfig>>.
=== UpdateRequestHandlers
=== Paramsets and UseParams
If you are expecting to change the parameters often, or if you want define sets of parameters that you can apply on the fly,
you can define them with <<request-parameters-api.adoc#request-parameters-api,Request Parameters API>> and then invoke them
by providing one or more in `useParams` setting either in the handler definition itself or as a query parameter.
The UpdateRequestHandlers are request handlers which process updates to the index.
[source,xml]
----
<requestHandler name="/terms" class="solr.SearchHandler" useParams="myQueries">
In this guide, we've covered these handlers in detail in the section <<uploading-data-with-index-handlers.adoc#uploading-data-with-index-handlers,Uploading Data with Index Handlers>>.
...
</requestHandler>
----
=== ShardHandlers
[source,text]
----
http://localhost/solr/techproducts/select?useParams=myFacets,myQueries
----
It is possible to configure a request handler to search across shards of a cluster, used with distributed search. More information about distributed search and how to configure the shardHandler is in the section <<distributed-search-with-index-sharding.adoc#distributed-search-with-index-sharding,Distributed Search with Index Sharding>>.
If paramset is called but is not defined, it is ignored.
This allows most <<implicit-requesthandlers.adoc#implicit-requesthandlers,implicit request handlers>> to call specific paramsets,
that you can define later, as needed.
=== Implicit Request Handlers
Solr includes many out-of-the-box request handlers that are not configured in `solrconfig.xml`, and so are referred to as "implicit" - see <<implicit-requesthandlers.adoc#implicit-requesthandlers,Implicit RequestHandlers>>.
== Search Handlers
== Search Components
Search Handlers are very important to Solr, as the data is indexed (roughly) once but is searched many times.
The whole design of Solr (and Lucene) is optimising data for searching and Search Handler is a flexible gateway to that.
Search components define the logic that is used by the SearchHandler to perform queries for users.
The following sections are allowed within a Search Handler:
=== Default Components
[source,xml]
----
<requestHandler name="/select" class="solr.SearchHandler">
... defaults/appends/invariants
... first-components/last-components or components
... shardHandlerFactory
</requestHandler>
----
There are several default search components that work with all SearchHandlers without any additional configuration. If no components are defined (with the exception of `first-components` and `last-components` - see below), these are executed by default, in the following order:
All the blocks are optional, especially since parameters can also be provided with `initParams` and `useParams`.
// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
The defaults/appends/invariants blocks were described <<#defaults-appends-and-invariants,higher>> on the page. All the parameters described in the section <<searching.adoc#searching,Searching>> can be defined as parameters for any of the Search Handlers.
The Search Components blocks are described next, and <<distributed-requests.adoc#configuring-the-shardhandlerfactory,shardHandlerFactory>> is for fine-tuning of the SolrCloud distributed requests.
=== Defining Search Components
The search components themselves are defined outside of the Request Handlers and then are referenced from various Search Handlers that want to use them.
Most Search Handlers use the default - implicit - stack of Search Components and only sometimes need to augment them with additional components prepended or appended.
It is quite rare - and somewhat brittle - to completely override the component stack, though it is used in examples to clearly demonstrate the effect of a specific Search Component.
==== Default Components
As you can see below, what we see as a search experience is mostly a sequence of components defined below. They are called in the order listed.
[cols="20,40,40",options="header"]
|===
|Component Name |Class Name |More Information
|query |`solr.QueryComponent` |Described in the section <<query-syntax-and-parsing.adoc#query-syntax-and-parsing,Query Syntax and Parsing>>.
|facet |`solr.FacetComponent` |Described in the section <<faceting.adoc#faceting,Faceting>>.
|facet |`solr.FacetComponent` |Original parameter-based facet component, described in the section <<faceting.adoc#faceting,Faceting>>.
|facet_module |`solr.facet.FacetModule` | JSON Faceting and Analytics module, described in the section <<json-facet-api.adoc#json-facet-api, JSON Facet API>>.
|mlt |`solr.MoreLikeThisComponent` |Described in the section <<morelikethis.adoc#morelikethis,MoreLikeThis>>.
|highlight |`solr.HighlightComponent` |Described in the section <<highlighting.adoc#highlighting,Highlighting>>.
|stats |`solr.StatsComponent` |Described in the section <<the-stats-component.adoc#the-stats-component,The Stats Component>>.
@ -128,53 +233,92 @@ There are several default search components that work with all SearchHandlers wi
|debug |`solr.DebugComponent` |Described in the section on <<common-query-parameters.adoc#debug-parameter,Common Query Parameters>>.
|===
If you register a new search component with one of these default names, the newly defined component will be used instead of the default.
==== Shipped Custom Components
Apart from default components, Solr ships with a number of additional - very useful - components.
They do need to defined and referenced in `solrconfig.xml` to be actually used.
=== First-Components and Last-Components
* `AnalyticsComponent`, described in the section <<analytics.adoc#analytics,Analytics>>.
* `ClusteringComponent`, described in the section <<result-clustering.adoc#result-clustering,Result Clustering>>.
* `PhrasesIdentificationComponent`, used to identify & score "phrases" found in the input string, based on shingles in indexed fields, described in the {solr-javadocs}solr-core/org/apache/solr/handler/component/PhrasesIdentificationComponent.html[PhrasesIdentificationComponent] javadocs.
* `QueryElevationComponent`, described in the section <<the-query-elevation-component.adoc#the-query-elevation-component,The Query Elevation Component>>.
* `RealTimeGetComponent`, described in the section <<realtime-get.adoc#realtime-get,RealTime Get>>.
* `ResponseLogComponent`, used to record which documents are returned to the user via the Solr log, described in the {solr-javadocs}solr-core/org/apache/solr/handler/component/ResponseLogComponent.html[ResponseLogComponent] javadocs.
* `SpellCheckComponent`, described in the section <<spell-checking.adoc#spell-checking,Spell Checking>>.
* `SuggestComponent`, described in the section <<suggester.adoc#suggester,Suggester>>.
* `TermVectorComponent`, described in the section <<the-term-vector-component.adoc#the-term-vector-component,The Term Vector Component>>.
Some third party components are also linked from https://solr.cool/ website.
==== Defining Custom Search Components
To define custom component, the syntax is:
[source,xml]
----
<searchComponent name="spellcheck" class="solr.SpellCheckComponent">
<lst name="spellchecker">
<str name="classname">solr.IndexBasedSpellChecker</str>
...
</lst>
</searchComponent>
----
Custom components often have configuration elements not described here. Check specific component's documentation/examples for details.
Notice: If you register a new search component with one of the default names, the newly defined component will be used instead of the default.
This allows to override a specific component, while not having to worry so much about upgrading Solr.
=== Referencing Search Components
It's possible to define some components as being used before (with `first-components`) or after (with `last-components`) the default components listed above.
[IMPORTANT]
====
`first-components` and/or `last-components` may only be used in conjunction with the default components. If you define your own `components`, the default components will not be executed, and `first-components` and `last-components` are disallowed.
====
[source,xml]
----
<searchComponent name="..." class="...">
<arr name="first-components">
<str>mycomponent</str>
</arr>
<arr name="last-components">
<str>spellcheck</str>
</arr>
</searchComponent>
----
NOTE: The component registered with the name "debug" will always be executed after the "last-components"
If you define `components` instead, the <<#default-components,default components (above)>> will not be executed, and `first-components` and `last-components` are disallowed.
This should be considered as a last-resort option as the default list may change in a later Solr version.
[source,xml]
----
<arr name="first-components">
<str>mycomponent</str>
</arr>
<arr name="last-components">
<str>spellcheck</str>
</arr>
<searchComponent name="..." class="...">
<arr name="components">
<str>mycomponent</str>
<str>query</str>
<str>debug</str>
</arr>
</searchComponent>
----
=== Components
If you define `components`, the default components (see above) will not be executed, and `first-components` and `last-components` are disallowed:
== Update Request Handlers
The Update Request Handlers are request handlers which process updates to the index. Most of the request handlers are <<implicit-requesthandlers.adoc#update-handlers,implicit>>
and can be customized by defining properly named Paramsets.
If you need to define additional Update Request Handler, the syntax is:
[source,xml]
----
<arr name="components">
<str>mycomponent</str>
<str>query</str>
<str>debug</str>
</arr>
<requestHandler name="/update/json" class="solr.UpdateRequestHandler">
... defaults/appends/invariants
</requestHandler>
----
=== Other Useful Components
The full details are covered in the section <<uploading-data-with-index-handlers.adoc#uploading-data-with-index-handlers,Uploading Data with Index Handlers>>.
Many of the other useful components are described in sections of this Guide for the features they support. These are:
Similar to Search Components for Search Handlers, Solr has document-preprocessing plugins for Update Request Handlers,
called <<update-request-processors.adoc#update-request-processors,Update Request Processors>>,
which also allow for default and custom configuration chains.
* `SpellCheckComponent`, described in the section <<spell-checking.adoc#spell-checking,Spell Checking>>.
* `TermVectorComponent`, described in the section <<the-term-vector-component.adoc#the-term-vector-component,The Term Vector Component>>.
* `QueryElevationComponent`, described in the section <<the-query-elevation-component.adoc#the-query-elevation-component,The Query Elevation Component>>.
* `RealTimeGetComponent`, described in the section <<realtime-get.adoc#realtime-get,RealTime Get>>.
* `ClusteringComponent`, described in the section <<result-clustering.adoc#result-clustering,Result Clustering>>.
* `SuggestComponent`, described in the section <<suggester.adoc#suggester,Suggester>>.
* `AnalyticsComponent`, described in the section <<analytics.adoc#analytics,Analytics>>.
Other components that ship with Solr include:
* `ResponseLogComponent`, used to record which documents are returned to the user via the Solr log, described in the {solr-javadocs}solr-core/org/apache/solr/handler/component/ResponseLogComponent.html[ResponseLogComponent] javadocs.
* `PhrasesIdentificationComponent`, used to identify & score "phrases" found in the input string, based on shingles in indexed fields, described in the {solr-javadocs}solr-core/org/apache/solr/handler/component/PhrasesIdentificationComponent.html[PhrasesIdentificationComponent] javadocs.
Note: Do not confuse Update Request Handlers with <<updatehandlers-in-solrconfig.adoc#updatehandlers-in-solrconfig,`updateHandler`>> section also defined in `solrconfig.xml`.

4
solr/solr-ref-guide/src/rule-based-authorization-plugin.adoc
View File

@ -240,8 +240,8 @@ The predefined permission names (and their effects) are:
** OVERSEERSTATUS
** CLUSTERSTATUS
** REQUESTSTATUS
* *update*: this permission is allowed to perform any update action on any collection. This includes sending documents for indexing (using an <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#updaterequesthandlers,update request handler>>). This applies to all collections by default (`collection:"*"`).
* *read*: this permission is allowed to perform any read action on any collection. This includes querying using search handlers (using <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#searchhandlers,request handlers>>) such as `/select`, `/get`, `/tvrh`, `/terms`, `/clustering`, `/elevate`, `/export`, `/spell`, `/clustering`, and `/sql`. This applies to all collections by default ( `collection:"*"` ).
* *update*: this permission is allowed to perform any update action on any collection. This includes sending documents for indexing (using an <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#update-request-handlers,update request handler>>). This applies to all collections by default (`collection:"*"`).
* *read*: this permission is allowed to perform any read action on any collection. This includes querying using search handlers (using <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#search-handlers,request handlers>>) such as `/select`, `/get`, `/tvrh`, `/terms`, `/clustering`, `/elevate`, `/export`, `/spell`, `/clustering`, and `/sql`. This applies to all collections by default ( `collection:"*"` ).
* *all*: Any requests coming to Solr.
=== Permission Ordering and Resolution

2
solr/solr-ref-guide/src/the-terms-component.adoc
View File

@ -22,7 +22,7 @@ In a sense, this search component provides fast field-faceting over the whole in
== Configuring the Terms Component
Terms Component is one of <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#search-components,the default search components>>
Terms Component is one of <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#defining-search-components,the default search components>>
and does not need to be defined in `solrconfig.xml`.
The definition is equivalent to:

5
solr/solr-ref-guide/src/uploading-data-with-index-handlers.adoc
View File

@ -23,6 +23,11 @@ The recommended way to configure and use request handlers is with path based nam
A single unified update request handler supports XML, CSV, JSON, and javabin update requests, delegating to the appropriate `ContentStreamLoader` based on the `Content-Type` of the <<content-streams.adoc#content-streams,ContentStream>>.
If you need to pre-process documents after they are loaded but before they are indexed (or even checked against the schema),
Solr has document-preprocessing plugins for Update Request Handlers,
called <<update-request-processors.adoc#update-request-processors,Update Request Processors>>,
which allow for default and custom configuration chains.
== UpdateRequestHandler Configuration
The default configuration file has the update request handler configured by default.