ctargett commented on a change in pull request #1921: URL: https://github.com/apache/lucene-solr/pull/1921#discussion_r495489865
########## File path: solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc ########## @@ -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 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 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. + +If a request handler is not expected to be used very often, it can be marked with `startup="lazy"` to avoid loading until needed. + +[source,xml] +---- +<requestHandler name="/spell" class="solr.SearchHandler" startup="lazy"> + ... +</requestHandler> +---- + +== Configuring request handlers +There are 3 ways to configure request handlers inside their definitions and another 3 ways to configure them somewhere else. -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. +=== Request parameters (GET and POST) +The easiest and most flexible way is to provide parameters with standard GET or POST requests. -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. +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. -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>>. +[source,text] +---- +http://localhost:8983/solr/techproducts/select?q=id:SP2514N&fl=id+name&wt=xml +---- -=== SearchHandlers +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" +}' +---- -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. +Either way, the parameters are extracted and combined with other options explained below. -For example, in the default `solrconfig.xml`, the first request handler defined looks like this: +=== defaults, appends, and invariants Review comment: I think these should be capitalized. In the sub-sections here you did not capitalize "defaults" but you did "Appends" - it should be consistent, and even though those terms are the XML names we can also refer to the concepts of default and append, etc, as words and capitalize them in headings. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org For additional commands, e-mail: issues-h...@lucene.apache.org
