You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2017/05/12 14:05:21 UTC
[13/37] lucene-solr:branch_6x: squash merge jira/solr-10290 into
master
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/putting-the-pieces-together.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/putting-the-pieces-together.adoc b/solr/solr-ref-guide/src/putting-the-pieces-together.adoc
new file mode 100644
index 0000000..eac49b2
--- /dev/null
+++ b/solr/solr-ref-guide/src/putting-the-pieces-together.adoc
@@ -0,0 +1,61 @@
+= Putting the Pieces Together
+:page-shortname: putting-the-pieces-together
+:page-permalink: putting-the-pieces-together.html
+
+At the highest level, `schema.xml` is structured as follows.
+
+This example is not real XML, but it gives you an idea of the structure of the file.
+
+[source,xml]
+----
+<schema>
+ <types>
+ <fields>
+ <uniqueKey>
+ <copyField>
+</schema>
+----
+
+Obviously, most of the excitement is in `types` and `fields`, where the field types and the actual field definitions live.
+
+These are supplemented by `copyFields`.
+
+The `uniqueKey` must always be defined.
+
+In older Solr versions you would find `defaultSearchField` and `solrQueryParser` tags as well, but although these still work they are deprecated and discouraged, see <<other-schema-elements.adoc#other-schema-elements,Other Schema Elements>>.
+
+.Types and fields are optional tags
+[NOTE]
+====
+Note that the `types` and `fields` sections are optional, meaning you are free to mix `field`, `dynamicField`, `copyField` and `fieldType` definitions on the top level. This allows for a more logical grouping of related tags in your schema.
+====
+
+== Choosing Appropriate Numeric Types
+
+For general numeric needs, consider using one of the` IntPointField`, `LongPointField`, `FloatPointField`, or `DoublePointField` classes, depending on the specific values you expect. These "Dimensional Point" based numeric classes use specially encoded data structures to support efficient range queries regardless of the size of the ranges used. Enable <<docvalues.adoc#docvalues,DocValues>> on these fields as needed for sorting and/or faceting.
+
+Some Solr features may not yet work with "Dimensional Points", in which case you may want to consider the equivalent `TrieIntField`, `TrieLongField`, `TrieFloatField`, and `TrieDoubleField` classes. Configure a `precisionStep="0"` if you wish to minimize index size, but if you expect users to make frequent range queries on numeric types, use the default `precisionStep` (by not specifying it) or specify it as `precisionStep="8"` (which is the default). This offers faster speed for range queries at the expense of increasing index size.
+
+== Working With Text
+
+Handling text properly will make your users happy by providing them with the best possible results for text searches.
+
+One technique is using a text field as a catch-all for keyword searching. Most users are not sophisticated about their searches and the most common search is likely to be a simple keyword search. You can use `copyField` to take a variety of fields and funnel them all into a single text field for keyword searches.
+
+In the schema.xml file for the "```techproducts```" example included with Solr, `copyField` declarations are used to dump the contents of `cat`, `name`, `manu`, `features`, and `includes` into a single field, `text`. In addition, it could be a good idea to copy `ID` into `text` in case users wanted to search for a particular product by passing its product number to a keyword search.
+
+Another technique is using `copyField` to use the same field in different ways. Suppose you have a field that is a list of authors, like this:
+
+`Schildt, Herbert; Wolpert, Lewis; Davies, P.`
+
+For searching by author, you could tokenize the field, convert to lower case, and strip out punctuation:
+
+`schildt / herbert / wolpert / lewis / davies / p`
+
+For sorting, just use an untokenized field, converted to lower case, with punctuation stripped:
+
+`schildt herbert wolpert lewis davies p`
+
+Finally, for faceting, use the primary author only via a `StrField`:
+
+`Schildt, Herbert`
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/query-re-ranking.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-re-ranking.adoc b/solr/solr-ref-guide/src/query-re-ranking.adoc
new file mode 100644
index 0000000..9f02059
--- /dev/null
+++ b/solr/solr-ref-guide/src/query-re-ranking.adoc
@@ -0,0 +1,55 @@
+= Query Re-Ranking
+:page-shortname: query-re-ranking
+:page-permalink: query-re-ranking.html
+:page-children: learning-to-rank
+
+Query Re-Ranking allows you to run a simple query (A) for matching documents and then re-rank the top N documents using the scores from a more complex query (B).
+
+Since the more costly ranking from query B is only applied to the top _N_ documents it will have less impact on performance then just using the complex query B by itself. The trade off is that documents which score very low using the simple query A may not be considered during the re-ranking phase, even if they would score very highly using query B.
+
+== Specifying a Ranking Query
+
+A Ranking query can be specified using the `rq` request parameter. The `rq` parameter must specify a query string that when parsed, produces a {solr-javadocs}/solr-core/org/apache/solr/search/RankQuery.html[RankQuery].
+
+Three rank queries are currently included in the Solr distribution. You can also configure a custom {solr-javadocs}/solr-core/org/apache/solr/search/QParserPlugin.html[QParserPlugin] you have written, but most users can just use a parser provided with Solr.
+
+// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+
+[cols="30,70",options="header"]
+|===
+|Parser |QParserPlugin class
+|rerank |{solr-javadocs}/solr-core/org/apache/solr/search/ReRankQParserPlugin.html[ReRankQParserPlugin]
+|xport |{solr-javadocs}/solr-core/org/apache/solr/search/ExportQParserPlugin.html[ExportQParserPlugin]
+|ltr |LTRQParserPlugin
+|===
+
+=== ReRank Query Parser
+
+The `rerank` parser wraps a query specified by an local parameter, along with additional parameters indicating how many documents should be re-ranked, and how the final scores should be computed:
+
+// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+
+[cols="20,15,65",options="header"]
+|===
+|Parameter |Default |Description
+|`reRankQuery` |(Mandatory) |The query string for your complex ranking query - in most cases <<local-parameters-in-queries.adoc#local-parameters-in-queries,a variable>> will be used to refer to another request parameter.
+|`reRankDocs` |200 |The number of top N documents from the original query that should be re-ranked. This number will be treated as a minimum, and may be increased internally automatically in order to rank enough documents to satisfy the query (ie: start+rows)
+|`reRankWeight` |2.0 |A multiplicative factor that will be applied to the score from the reRankQuery for each of the top matching documents, before that score is added to the original score
+|===
+
+In the example below, the top 1000 documents matching the query "greetings" will be re-ranked using the query "(hi hello hey hiya)". The resulting scores for each of those 1000 documents will be 3 times their score from the "(hi hello hey hiya)", plus the score from the original "greetings" query:
+
+[source,text]
+----
+q=greetings&rq={!rerank reRankQuery=$rqq reRankDocs=1000 reRankWeight=3}&rqq=(hi+hello+hey+hiya)
+----
+
+If a document matches the original query, but does not match the re-ranking query, the document's original score will remain.
+
+=== LTR Query Parser
+
+The `ltr` stands for Learning To Rank, please see <<learning-to-rank.adoc#learning-to-rank,Learning To Rank>> for more detailed information.
+
+== Combining Ranking Queries with Other Solr Features
+
+The `rq` parameter and the re-ranking feature in general works well with other Solr features. For example, it can be used in conjunction with the <<collapse-and-expand-results.adoc#collapse-and-expand-results,collapse parser>> to re-rank the group heads after they've been collapsed. It also preserves the order of documents elevated by the <<the-query-elevation-component.adoc#the-query-elevation-component,elevation component>>. And it even has its own custom explain so you can see how the re-ranking scores were derived when looking at <<common-query-parameters.adoc#CommonQueryParameters-ThedebugParameter,debug information>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/query-screen.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-screen.adoc b/solr/solr-ref-guide/src/query-screen.adoc
new file mode 100644
index 0000000..5480796
--- /dev/null
+++ b/solr/solr-ref-guide/src/query-screen.adoc
@@ -0,0 +1,42 @@
+= Query Screen
+:page-shortname: query-screen
+:page-permalink: query-screen.html
+
+You can use the *Query* screen to submit a search query to a Solr collection and analyze the results.
+
+In the example in the screenshot, a query has been submitted, and the screen shows the query results sent to the browser as JSON.
+
+.JSON Results of a Query
+image::images/query-screen/query-top.png[image,height=400]
+
+In this example, a query for `genre:Fantasy` was sent to a "films" collection. Defaults were used for all other options in the form, which are explained briefly in the table below, and covered in detail in later parts of this Guide.
+
+The response is shown to the right of the form. Requests to Solr are simply HTTP requests, and the query submitted is shown in light type above the results; if you click on this it will open a new browser window with just this request and response (without the rest of the Solr Admin UI). The rest of the response is shown in JSON, which is part of the request (see the `wt=json` part at the end).
+
+The response has at least two sections, but may have several more depending on the options chosen. The two sections it always has are the `responseHeader` and the `response`. The `responseHeader` includes the status of the search (`status`), the processing time (`QTime`), and the parameters (`params`) that were used to process the query.
+
+The `response` includes the documents that matched the query, in `doc` sub-sections. The fields return depend on the parameters of the query (and the defaults of the request handler used). The number of results is also included in this section.
+
+This screen allows you to experiment with different query options, and inspect how your documents were indexed. The query parameters available on the form are some basic options that most users want to have available, but there are dozens more available which could be simply added to the basic request by hand (if opened in a browser). The table below explains the parameters available:
+
+// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+
+[cols="20,80",options="header"]
+|===
+|Field |Description
+|Request-handler (qt) |Specifies the query handler for the request. If a query handler is not specified, Solr processes the response with the standard query handler.
+|q |The query event. See <<searching.adoc#searching,Searching>> for an explanation of this parameter.
+|fq |The filter queries. See <<common-query-parameters.adoc#common-query-parameters,Common Query Parameters>> for more information on this parameter.
+|sort |Sorts the response to a query in either ascending or descending order based on the response's score or another specified characteristic.
+|start, rows |`start` is the offset into the query result starting at which documents should be returned. The default value is 0, meaning that the query should return results starting with the first document that matches. This field accepts the same syntax as the start query parameter, which is described in <<searching.adoc#searching,Searching>>. `rows` is the number of rows to return.
+|fl |Defines the fields to return for each document. You can explicitly list the stored fields, <<function-queries.adoc#function-queries,functions>>, and <<transforming-result-documents.adoc#transforming-result-documents,doc transformers>> you want to have returned by separating them with either a comma or a space.
+|wt |Specifies the Response Writer to be used to format the query response. Defaults to XML if not specified.
+|indent |Click this button to request that the Response Writer use indentation to make the responses more readable.
+|debugQuery |Click this button to augment the query response with debugging information, including "explain info" for each document returned. This debugging information is intended to be intelligible to the administrator or programmer.
+|dismax |Click this button to enable the Dismax query parser. See <<the-dismax-query-parser.adoc#the-dismax-query-parser,The DisMax Query Parser>> for further information.
+|edismax |Click this button to enable the Extended query parser. See <<the-extended-dismax-query-parser.adoc#the-extended-dismax-query-parser,The Extended DisMax Query Parser>> for further information.
+|hl |Click this button to enable highlighting in the query response. See <<highlighting.adoc#highlighting,Highlighting>> for more information.
+|facet |Enables faceting, the arrangement of search results into categories based on indexed terms. See <<faceting.adoc#faceting,Faceting>> for more information.
+|spatial |Click to enable using location data for use in spatial or geospatial searches. See <<spatial-search.adoc#spatial-search,Spatial Search>> for more information.
+|spellcheck |Click this button to enable the Spellchecker, which provides inline query suggestions based on other, similar, terms. See <<spell-checking.adoc#spell-checking,Spell Checking>> for more information.
+|===
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc b/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
new file mode 100644
index 0000000..52f852d
--- /dev/null
+++ b/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
@@ -0,0 +1,217 @@
+= Query Settings in SolrConfig
+:page-shortname: query-settings-in-solrconfig
+:page-permalink: query-settings-in-solrconfig.html
+
+The settings in this section affect the way that Solr will process and respond to queries.
+
+These settings are all configured in child elements of the `<query>` element in `solrconfig.xml`.
+
+[source,xml]
+----
+<query>
+ ...
+</query>
+----
+
+[[QuerySettingsinSolrConfig-Caches]]
+== Caches
+
+Solr caches are associated with a specific instance of an Index Searcher, a specific view of an index that doesn't change during the lifetime of that searcher. As long as that Index Searcher is being used, any items in its cache will be valid and available for reuse. Caching in Solr differs from caching in many other applications in that cached Solr objects do not expire after a time interval; instead, they remain valid for the lifetime of the Index Searcher.
+
+When a new searcher is opened, the current searcher continues servicing requests while the new one auto-warms its cache. The new searcher uses the current searcher's cache to pre-populate its own. When the new searcher is ready, it is registered as the current searcher and begins handling all new search requests. The old searcher will be closed once it has finished servicing all its requests.
+
+In Solr, there are three cache implementations: `solr.search.LRUCache`, `solr.search.FastLRUCache,` and `solr.search.LFUCache` .
+
+The acronym LRU stands for Least Recently Used. When an LRU cache fills up, the entry with the oldest last-accessed timestamp is evicted to make room for the new entry. The net effect is that entries that are accessed frequently tend to stay in the cache, while those that are not accessed frequently tend to drop out and will be re-fetched from the index if needed again.
+
+The `FastLRUCache`, which was introduced in Solr 1.4, is designed to be lock-free, so it is well suited for caches which are hit several times in a request.
+
+Both `LRUCache` and `FastLRUCache` use an auto-warm count that supports both integers and percentages which get evaluated relative to the current size of the cache when warming happens.
+
+The `LFUCache` refers to the Least Frequently Used cache. This works in a way similar to the LRU cache, except that when the cache fills up, the entry that has been used the least is evicted.
+
+The Statistics page in the Solr Admin UI will display information about the performance of all the active caches. This information can help you fine-tune the sizes of the various caches appropriately for your particular application. When a Searcher terminates, a summary of its cache usage is also written to the log.
+
+Each cache has settings to define its initial size (`initialSize`), maximum size (`size`) and number of items to use for during warming (`autowarmCount`). The LRU and FastLRU cache implementations can take a percentage instead of an absolute value for `autowarmCount`.
+
+FastLRUCache and LFUCache support `showItems` attribute. This is the number of cache items to display in the stats page for the cache. It is for debugging.
+
+Details of each cache are described below.
+
+[[QuerySettingsinSolrConfig-filterCache]]
+=== `filterCache`
+
+This cache is used by `SolrIndexSearcher` for filters (DocSets) for unordered sets of all documents that match a query. The numeric attributes control the number of entries in the cache.
+
+The most typical way Solr uses the `filterCache` is to cache results of each `fq` search parameter, though there are some other cases as well. Subsequent queries using the same parameter filter query result in cache hits and rapid returns of results. See <<searching.adoc#searching,Searching>> for a detailed discussion of the `fq` parameter. Another Solr feature using this cache is the `filter(...)` syntax in the default Lucene query parser.
+
+Solr also uses this cache for faceting when the configuration parameter `facet.method` is set to `fc`. For a discussion of faceting, see <<searching.adoc#searching,Searching>>.
+
+[source,xml]
+----
+<filterCache class="solr.LRUCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="128"/>
+----
+
+[[QuerySettingsinSolrConfig-queryResultCache]]
+=== `queryResultCache`
+
+This cache holds the results of previous searches: ordered lists of document IDs (DocList) based on a query, a sort, and the range of documents requested.
+
+The `queryResultCache` has an additional (optional) setting to limit the maximum amount of RAM used (`maxRamMB`). This lets you specify the maximum heap size, in megabytes, used by the contents of this cache. When the cache grows beyond this size, oldest accessed queries will be evicted until the heap usage of the cache decreases below the specified limit.
+
+[source,xml]
+----
+<queryResultCache class="solr.LRUCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="128"
+ maxRamMB="1000"/>
+----
+
+[[QuerySettingsinSolrConfig-documentCache]]
+=== `documentCache`
+
+This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache is not auto-warmed. The size for the `documentCache` should always be greater than `max_results` times the `max_concurrent_queries`, to ensure that Solr does not need to refetch a document during a request. The more fields you store in your documents, the higher the memory usage of this cache will be.
+
+[source,xml]
+----
+<documentCache class="solr.LRUCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="0"/>
+----
+
+[[QuerySettingsinSolrConfig-UserDefinedCaches]]
+=== User Defined Caches
+
+You can also define named caches for your own application code to use. You can locate and use your cache object by name by calling the `SolrIndexSearcher` methods `getCache()`, `cacheLookup()` and `cacheInsert()`.
+
+[source,xml]
+----
+<cache name="myUserCache" class="solr.LRUCache"
+ size="4096"
+ initialSize="1024"
+ autowarmCount="1024"
+ regenerator="org.mycompany.mypackage.MyRegenerator" />
+----
+
+If you want auto-warming of your cache, include a `regenerator` attribute with the fully qualified name of a class that implements `solr.search.CacheRegenerator`. You can also use the `NoOpRegenerator`, which simply repopulates the cache with old items. Define it with the `regenerator` parameter as`: regenerator="solr.NoOpRegenerator"`.
+
+[[QuerySettingsinSolrConfig-QuerySizingandWarming]]
+== Query Sizing and Warming
+
+[[QuerySettingsinSolrConfig-maxBooleanClauses]]
+=== `maxBooleanClauses`
+
+This sets the maximum number of clauses allowed in a boolean query. This can affect range or prefix queries that expand to a query with a large number of boolean terms. If this limit is exceeded, an exception is thrown.
+
+[source,xml]
+----
+<maxBooleanClauses>1024</maxBooleanClauses>
+----
+
+[WARNING]
+====
+This option modifies a global property that effects all Solr cores. If multiple `solrconfig.xml` files disagree on this property, the value at any point in time will be based on the last Solr core that was initialized.
+====
+
+[[QuerySettingsinSolrConfig-enableLazyFieldLoading]]
+=== `enableLazyFieldLoading`
+
+If this parameter is set to true, then fields that are not directly requested will be loaded lazily as needed. This can boost performance if the most common queries only need a small subset of fields, especially if infrequently accessed fields are large in size.
+
+[source,xml]
+----
+<enableLazyFieldLoading>true</enableLazyFieldLoading>
+----
+
+[[QuerySettingsinSolrConfig-useFilterForSortedQuery]]
+=== `useFilterForSortedQuery`
+
+This parameter configures Solr to use a filter to satisfy a search. If the requested sort does not include "score", the `filterCache` will be checked for a filter matching the query. For most situations, this is only useful if the same search is requested often with different sort options and none of them ever use "score".
+
+[source,xml]
+----
+<useFilterForSortedQuery>true</useFilterForSortedQuery>
+----
+
+[[QuerySettingsinSolrConfig-queryResultWindowSize]]
+=== `queryResultWindowSize`
+
+Used with the `queryResultCache`, this will cache a superset of the requested number of document IDs. For example, if the a search in response to a particular query requests documents 10 through 19, and `queryWindowSize` is 50, documents 0 through 49 will be cached.
+
+[source,xml]
+----
+<queryResultWindowSize>20</queryResultWindowSize>
+----
+
+[[QuerySettingsinSolrConfig-queryResultMaxDocsCached]]
+=== `queryResultMaxDocsCached`
+
+This parameter sets the maximum number of documents to cache for any entry in the `queryResultCache`.
+
+[source,xml]
+----
+<queryResultMaxDocsCached>200</queryResultMaxDocsCached>
+----
+
+[[QuerySettingsinSolrConfig-useColdSearcher]]
+=== `useColdSearcher`
+
+This setting controls whether search requests for which there is not a currently registered searcher should wait for a new searcher to warm up (false) or proceed immediately (true). When set to "false", requests will block until the searcher has warmed its caches.
+
+[source,xml]
+----
+<useColdSearcher>false</useColdSearcher>
+----
+
+[[QuerySettingsinSolrConfig-maxWarmingSearchers]]
+=== `maxWarmingSearchers`
+
+This parameter sets the maximum number of searchers that may be warming up in the background at any given time. Exceeding this limit will raise an error. For read-only slaves, a value of two is reasonable. Masters should probably be set a little higher.
+
+[source,xml]
+----
+<maxWarmingSearchers>2</maxWarmingSearchers>
+----
+
+[[QuerySettingsinSolrConfig-Query-RelatedListeners]]
+== Query-Related Listeners
+
+As described in the section on <<QuerySettingsinSolrConfig-Caches,Caches>>, new Index Searchers are cached. It's possible to use the triggers for listeners to perform query-related tasks. The most common use of this is to define queries to further "warm" the Index Searchers while they are starting. One benefit of this approach is that field caches are pre-populated for faster sorting.
+
+Good query selection is key with this type of listener. It's best to choose your most common and/or heaviest queries and include not just the keywords used, but any other parameters such as sorting or filtering requests.
+
+There are two types of events that can trigger a listener. A `firstSearcher` event occurs when a new searcher is being prepared but there is no current registered searcher to handle requests or to gain auto-warming data from (i.e., on Solr startup). A `newSearcher` event is fired whenever a new searcher is being prepared and there is a current searcher handling requests.
+
+The (commented out) examples below can be found in the `solrconfig.xml` file of the `sample_techproducts_configs` <<config-sets.adoc#config-sets,config set>>included with Solr, and demonstrate using the `solr.QuerySenderListener` class to warm a set of explicit queries:
+
+[source,xml]
+----
+<listener event="newSearcher" class="solr.QuerySenderListener">
+ <arr name="queries">
+ <!--
+ <lst><str name="q">solr</str><str name="sort">price asc</str></lst>
+ <lst><str name="q">rocks</str><str name="sort">weight asc</str></lst>
+ -->
+ </arr>
+</listener>
+
+<listener event="firstSearcher" class="solr.QuerySenderListener">
+ <arr name="queries">
+ <lst><str name="q">static firstSearcher warming in solrconfig.xml</str></lst>
+ </arr>
+</listener>
+----
+
+[IMPORTANT]
+====
+The above code comes from a _sample_ `solrconfig.xml`.
+
+A key best practice is to modify these defaults before taking your application to production, but please note: while the sample queries are commented out in the section for the "newSearcher", the sample query is not commented out for the "firstSearcher" event.
+
+There is no point in auto-warming your Index Searcher with the query string "static firstSearcher warming in solrconfig.xml" if that is not relevant to your search application.
+====
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/query-syntax-and-parsing.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-syntax-and-parsing.adoc b/solr/solr-ref-guide/src/query-syntax-and-parsing.adoc
new file mode 100644
index 0000000..31f5131
--- /dev/null
+++ b/solr/solr-ref-guide/src/query-syntax-and-parsing.adoc
@@ -0,0 +1,17 @@
+= Query Syntax and Parsing
+:page-shortname: query-syntax-and-parsing
+:page-permalink: query-syntax-and-parsing.html
+:page-children: common-query-parameters, the-standard-query-parser, the-dismax-query-parser, the-extended-dismax-query-parser, function-queries, local-parameters-in-queries, other-parsers
+
+Solr supports several query parsers, offering search application designers great flexibility in controlling how queries are parsed.
+
+This section explains how to specify the query parser to be used. It also describes the syntax and features supported by the main query parsers included with Solr and describes some other parsers that may be useful for particular situations. There are some query parameters common to all Solr parsers; these are discussed in the section <<common-query-parameters.adoc#common-query-parameters,Common Query Parameters>>.
+
+The parsers discussed in this Guide are:
+
+* <<the-standard-query-parser.adoc#the-standard-query-parser,The Standard Query Parser>>
+* <<the-dismax-query-parser.adoc#the-dismax-query-parser,The DisMax Query Parser>>
+* <<the-extended-dismax-query-parser.adoc#the-extended-dismax-query-parser,The Extended DisMax Query Parser>>
+* <<other-parsers.adoc#other-parsers,Other Parsers>>
+
+The query parser plugins are all subclasses of {solr-javadocs}/solr-core/org/apache/solr/search/QParserPlugin.html[QParserPlugin]. If you have custom parsing needs, you may want to extend that class to create your own query parser.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/read-and-write-side-fault-tolerance.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/read-and-write-side-fault-tolerance.adoc b/solr/solr-ref-guide/src/read-and-write-side-fault-tolerance.adoc
new file mode 100644
index 0000000..91d94bb
--- /dev/null
+++ b/solr/solr-ref-guide/src/read-and-write-side-fault-tolerance.adoc
@@ -0,0 +1,99 @@
+= Read and Write Side Fault Tolerance
+:page-shortname: read-and-write-side-fault-tolerance
+:page-permalink: read-and-write-side-fault-tolerance.html
+
+SolrCloud supports elasticity, high availability, and fault tolerance in reads and writes.
+
+What this means, basically, is that when you have a large cluster, you can always make requests to the cluster: Reads will return results whenever possible, even if some nodes are down, and Writes will be acknowledged only if they are durable; i.e., you won't lose data.
+
+[[ReadandWriteSideFaultTolerance-ReadSideFaultTolerance]]
+== Read Side Fault Tolerance
+
+In a SolrCloud cluster each individual node load balances read requests across all the replicas in collection. You still need a load balancer on the 'outside' that talks to the cluster, or you need a smart client which understands how to read and interact with Solr's metadata in ZooKeeper and only requests the ZooKeeper ensemble's address to start discovering to which nodes it should send requests. (Solr provides a smart Java SolrJ client called {solr-javadocs}/solr-solrj/org/apache/solr/client/solrj/impl/CloudSolrClient.html[CloudSolrClient].)
+
+Even if some nodes in the cluster are offline or unreachable, a Solr node will be able to correctly respond to a search request as long as it can communicate with at least one replica of every shard, or one replica of every _relevant_ shard if the user limited the search via the `shards` or `\_route_` parameters. The more replicas there are of every shard, the more likely that the Solr cluster will be able to handle search results in the event of node failures.
+
+[[ReadandWriteSideFaultTolerance-zkConnected]]
+=== `zkConnected`
+
+A Solr node will return the results of a search request as long as it can communicate with at least one replica of every shard that it knows about, even if it can _not_ communicate with ZooKeeper at the time it receives the request. This is normally the preferred behavior from a fault tolerance standpoint, but may result in stale or incorrect results if there have been major changes to the collection structure that the node has not been informed of via ZooKeeper (i.e., shards may have been added or removed, or split into sub-shards)
+
+A `zkConnected` header is included in every search response indicating if the node that processed the request was connected with ZooKeeper at the time:
+
+.Solr Response with partialResults
+[source,json]
+----
+{
+ "responseHeader": {
+ "status": 0,
+ "zkConnected": true,
+ "QTime": 20,
+ "params": {
+ "q": "*:*"
+ }
+ },
+ "response": {
+ "numFound": 107,
+ "start": 0,
+ "docs": [ "..." ]
+ }
+}
+----
+
+[[ReadandWriteSideFaultTolerance-shards.tolerant]]
+=== `shards.tolerant`
+
+In the event that one or more shards queried are completely unavailable, then Solr's default behavior is to fail the request. However, there are many use-cases where partial results are acceptable and so Solr provides a boolean `shards.tolerant` parameter (default `false`).
+
+If `shards.tolerant=true` then partial results may be returned. If the returned response does not contain results from all the appropriate shards then the response header contains a special flag called `partialResults`.
+
+The client can specify '<<distributed-search-with-index-sharding.adoc#distributed-search-with-index-sharding,`shards.info`>>' along with the `shards.tolerant` parameter to retrieve more fine-grained details.
+
+Example response with `partialResults` flag set to 'true':
+
+*Solr Response with partialResults*
+
+[source,json]
+----
+{
+ "responseHeader": {
+ "status": 0,
+ "zkConnected": true,
+ "partialResults": true,
+ "QTime": 20,
+ "params": {
+ "q": "*:*"
+ }
+ },
+ "response": {
+ "numFound": 77,
+ "start": 0,
+ "docs": [ "..." ]
+ }
+}
+----
+
+[[ReadandWriteSideFaultTolerance-WriteSideFaultTolerance]]
+== Write Side Fault Tolerance
+
+SolrCloud is designed to replicate documents to ensure redundancy for your data, and enable you to send update requests to any node in the cluster. That node will determine if it hosts the leader for the appropriate shard, and if not it will forward the request to the the leader, which will then forward it to all existing replicas, using versioning to make sure every replica has the most up-to-date version. If the leader goes down, another replica can take its place. This architecture enables you to be certain that your data can be recovered in the event of a disaster, even if you are using <<near-real-time-searching.adoc#near-real-time-searching,Near Real Time Searching>>.
+
+[[ReadandWriteSideFaultTolerance-Recovery]]
+=== Recovery
+
+A Transaction Log is created for each node so that every change to content or organization is noted. The log is used to determine which content in the node should be included in a replica. When a new replica is created, it refers to the Leader and the Transaction Log to know which content to include. If it fails, it retries.
+
+Since the Transaction Log consists of a record of updates, it allows for more robust indexing because it includes redoing the uncommitted updates if indexing is interrupted.
+
+If a leader goes down, it may have sent requests to some replicas and not others. So when a new potential leader is identified, it runs a synch process against the other replicas. If this is successful, everything should be consistent, the leader registers as active, and normal actions proceed. If a replica is too far out of sync, the system asks for a full replication/replay-based recovery.
+
+If an update fails because cores are reloading schemas and some have finished but others have not, the leader tells the nodes that the update failed and starts the recovery procedure.
+
+[[ReadandWriteSideFaultTolerance-AchievedReplicationFactor]]
+=== Achieved Replication Factor
+
+When using a replication factor greater than one, an update request may succeed on the shard leader but fail on one or more of the replicas. For instance, consider a collection with one shard and a replication factor of three. In this case, you have a shard leader and two additional replicas. If an update request succeeds on the leader but fails on both replicas, for whatever reason, the update request is still considered successful from the perspective of the client. The replicas that missed the update will sync with the leader when they recover.
+
+Behind the scenes, this means that Solr has accepted updates that are only on one of the nodes (the current leader). Solr supports the optional `min_rf` parameter on update requests that cause the server to return the achieved replication factor for an update request in the response. For the example scenario described above, if the client application included `min_rf >= 1`, then Solr would return `rf=1` in the Solr response header because the request only succeeded on the leader. The update request will still be accepted as the `min_rf` parameter only tells Solr that the client application wishes to know what the achieved replication factor was for the update request. In other words, `min_rf` does not mean Solr will enforce a minimum replication factor as Solr does not support rolling back updates that succeed on a subset of replicas.
+
+On the client side, if the achieved replication factor is less than the acceptable level, then the client application can take additional measures to handle the degraded state. For instance, a client application may want to keep a log of which update requests were sent while the state of the collection was degraded and then resend the updates once the problem has been resolved. In short, `min_rf` is an optional mechanism for a client application to be warned that an update request was accepted while the collection is in a degraded state.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/realtime-get.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/realtime-get.adoc b/solr/solr-ref-guide/src/realtime-get.adoc
new file mode 100644
index 0000000..e9ddc5c
--- /dev/null
+++ b/solr/solr-ref-guide/src/realtime-get.adoc
@@ -0,0 +1,102 @@
+= RealTime Get
+:page-shortname: realtime-get
+:page-permalink: realtime-get.html
+
+For index updates to be visible (searchable), some kind of commit must reopen a searcher to a new point-in-time view of the index.
+
+The *realtime get* feature allows retrieval (by `unique-key`) of the latest version of any documents without the associated cost of reopening a searcher. This is primarily useful when using Solr as a NoSQL data store and not just a search index.
+
+Real Time Get relies on the update log feature, which is enabled by default and can be configured in `solrconfig.xml`:
+
+[source,xml]
+----
+<updateLog>
+ <str name="dir">${solr.ulog.dir:}</str>
+</updateLog>
+----
+
+Real Time Get requests can be performed using the `/get` handler which exists implicitly in Solr - see <<implicit-requesthandlers.adoc#implicit-requesthandlers,Implicit RequestHandlers>> - it's equivalent to the following configuration:
+
+[source,xml]
+----
+<requestHandler name="/get" class="solr.RealTimeGetHandler">
+ <lst name="defaults">
+ <str name="omitHeader">true</str>
+ <str name="wt">json</str>
+ <str name="indent">true</str>
+ </lst>
+</requestHandler>
+----
+
+For example, if you started Solr using the `bin/solr -e techproducts` example command, you could then index a new document (with out committing it) like so:
+
+[source,bash]
+----
+curl 'http://localhost:8983/solr/techproducts/update/json?commitWithin=10000000' \
+ -H 'Content-type:application/json' -d '[{"id":"mydoc","name":"realtime-get test!"}]'
+----
+
+If you do a normal search, this document should not be found yet:
+
+[source,text]
+----
+http://localhost:8983/solr/techproducts/query?q=id:mydoc
+...
+"response":
+{"numFound":0,"start":0,"docs":[]}
+----
+
+However if you use the Real Time Get handler exposed at `/get`, you can still retrieve that document:
+
+[source,text]
+----
+http://localhost:8983/solr/techproducts/get?id=mydoc
+...
+{"doc":{"id":"mydoc","name":"realtime-get test!", "_version_":1487137811571146752}}
+----
+
+You can also specify multiple documents at once via the `ids` parameter and a comma separated list of ids, or by using multiple `id` parameters. If you specify multiple ids, or use the `ids` parameter, the response will mimic a normal query response to make it easier for existing clients to parse.
+
+For example:
+
+[source,text]
+----
+http://localhost:8983/solr/techproducts/get?ids=mydoc,IW-02
+http://localhost:8983/solr/techproducts/get?id=mydoc&id=IW-02
+...
+{"response":
+ {"numFound":2,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752},
+ {
+ "id":"IW-02",
+ "name":"iPod & iPod Mini USB 2.0 Cable",
+ ...
+ ]
+ }
+}
+----
+
+Real Time Get requests can also be combined with filter queries, specified with an <<common-query-parameters.adoc#CommonQueryParameters-Thefq_FilterQuery_Parameter,`fq` parameter>>, just like search requests:
+
+[source,text]
+----
+http://localhost:8983/solr/techproducts/get?id=mydoc&id=IW-02&fq=name:realtime-get
+...
+{"response":
+ {"numFound":1,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752}
+ ]
+ }
+}
+----
+
+[IMPORTANT]
+====
+Do *NOT* disable the realtime get handler at `/get` if you are using SolrCloud otherwise any leader election will cause a full sync in *ALL* replicas for the shard in question.
+
+Similarly, a replica recovery will also always fetch the complete index from the leader because a partial sync will not be possible in the absence of this handler.
+====
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/relevance.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/relevance.adoc b/solr/solr-ref-guide/src/relevance.adoc
new file mode 100644
index 0000000..afa37e5
--- /dev/null
+++ b/solr/solr-ref-guide/src/relevance.adoc
@@ -0,0 +1,31 @@
+= Relevance
+:page-shortname: relevance
+:page-permalink: relevance.html
+
+*Relevance* is the degree to which a query response satisfies a user who is searching for information.
+
+The relevance of a query response depends on the context in which the query was performed. A single search application may be used in different contexts by users with different needs and expectations. For example, a search engine of climate data might be used by a university researcher studying long-term climate trends, a farmer interested in calculating the likely date of the last frost of spring, a civil engineer interested in rainfall patterns and the frequency of floods, and a college student planning a vacation to a region and wondering what to pack. Because the motivations of these users vary, the relevance of any particular response to a query will vary as well.
+
+How comprehensive should query responses be? Like relevance in general, the answer to this question depends on the context of a search. The cost of _not_ finding a particular document in response to a query is high in some contexts, such as a legal e-discovery search in response to a subpoena, and quite low in others, such as a search for a cake recipe on a Web site with dozens or hundreds of cake recipes. When configuring Solr, you should weigh comprehensiveness against other factors such as timeliness and ease-of-use.
+
+The e-discovery and recipe examples demonstrate the importance of two concepts related to relevance:
+
+* *Precision* is the percentage of documents in the returned results that are relevant.
+* *Recall* is the percentage of relevant results returned out of all relevant results in the system. Obtaining perfect recall is trivial: simply return every document in the collection for every query.
+
+Returning to the examples above, it's important for an e-discovery search application to have 100% recall returning all the documents that are relevant to a subpoena. It's far less important that a recipe application offer this degree of precision, however. In some cases, returning too many results in casual contexts could overwhelm users. In some contexts, returning fewer results that have a higher likelihood of relevance may be the best approach.
+
+Using the concepts of precision and recall, it's possible to quantify relevance across users and queries for a collection of documents. A perfect system would have 100% precision and 100% recall for every user and every query. In other words, it would retrieve all the relevant documents and nothing else. In practical terms, when talking about precision and recall in real systems, it is common to focus on precision and recall at a certain number of results, the most common (and useful) being ten results.
+
+Through faceting, query filters, and other search components, a Solr application can be configured with the flexibility to help users fine-tune their searches in order to return the most relevant results for users. That is, Solr can be configured to balance precision and recall to meet the needs of a particular user community.
+
+The configuration of a Solr application should take into account:
+
+* the needs of the application's various users (which can include ease of use and speed of response, in addition to strictly informational needs)
+* the categories that are meaningful to these users in their various contexts (e.g., dates, product categories, or regions)
+* any inherent relevance of documents (e.g., it might make sense to ensure that an official product description or FAQ is always returned near the top of the search results)
+* whether or not the age of documents matters significantly (in some contexts, the most recent documents might always be the most important)
+
+Keeping all these factors in mind, it's often helpful in the planning stages of a Solr deployment to sketch out the types of responses you think the search application should return for sample queries. Once the application is up and running, you can employ a series of testing methodologies, such as focus groups, in-house testing, http://trec.nist.gov[TREC] tests and A/B testing to fine tune the configuration of the application to best meet the needs of its users.
+
+For more information about relevance, see Grant Ingersoll's tech article https://lucidworks.com/blog/2009/09/02/debugging-search-application-relevance-issues/[Debugging Search Application Relevance Issues] which is available on SearchHub.org.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/replication-screen.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/replication-screen.adoc b/solr/solr-ref-guide/src/replication-screen.adoc
new file mode 100644
index 0000000..d8c8e3f
--- /dev/null
+++ b/solr/solr-ref-guide/src/replication-screen.adoc
@@ -0,0 +1,21 @@
+= Replication Screen
+:page-shortname: replication-screen
+:page-permalink: replication-screen.html
+
+The Replication screen shows you the current replication state for the core you have specified. <<solrcloud.adoc#solrcloud,SolrCloud>> has supplanted much of this functionality, but if you are still using Master-Slave index replication, you can use this screen to:
+
+. View the replicatable index state. (on a master node)
+. View the current replication status (on a slave node)
+. Disable replication. (on a master node)
+
+.Caution When Using SolrCloud
+[IMPORTANT]
+====
+When using <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,SolrCloud>>, do not attempt to disable replication via this screen.
+====
+
+.Sample Replication Screen
+image::images/replication-screen/replication.png[image,width=412,height=250]
+
+
+More details on how to configure replication is available in the section called <<index-replication.adoc#index-replication,Index Replication>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/request-parameters-api.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/request-parameters-api.adoc b/solr/solr-ref-guide/src/request-parameters-api.adoc
new file mode 100644
index 0000000..8037421
--- /dev/null
+++ b/solr/solr-ref-guide/src/request-parameters-api.adoc
@@ -0,0 +1,187 @@
+= Request Parameters API
+:page-shortname: request-parameters-api
+:page-permalink: request-parameters-api.html
+
+The Request Parameters API allows creating parameter sets, a.k.a. paramsets, that can override or take the place of parameters defined in `solrconfig.xml`.
+
+The parameter sets defined with this API can be used in requests to Solr, or referenced directly in `solrconfig.xml` request handler definitions.
+
+It is really another endpoint of the <<config-api.adoc#config-api,Config API>> instead of a separate API, and has distinct commands. It does not replace or modify any sections of `solrconfig.xml`, but instead provides another approach to handling parameters used in requests. It behaves in the same way as the Config API, by storing parameters in another file that will be used at runtime. In this case, the parameters are stored in a file named `params.json`. This file is kept in ZooKeeper or in the `conf` directory of a standalone Solr instance.
+
+The settings stored in `params.json` are used at query time to override settings defined in `solrconfig.xml` in some cases as described below.
+
+When might you want to use this feature?
+
+* To avoid frequently editing your `solrconfig.xml` to update request parameters that change often.
+* To reuse parameters across various request handlers.
+* To mix and match parameter sets at request time.
+* To avoid a reload of your collection for small parameter changes.
+
+[[RequestParametersAPI-TheRequestParametersEndpoint]]
+== The Request Parameters Endpoint
+
+All requests are sent to the `/config/params` endpoint of the Config API.
+
+[[RequestParametersAPI-SettingRequestParameters]]
+== Setting Request Parameters
+
+The request to set, unset, or update request parameters is sent as a set of Maps with names. These objects can be directly used in a request or a request handler definition.
+
+The available commands are:
+
+* `set`: Create or overwrite a parameter set map.
+* `unset`: delete a parameter set map.
+* `update`: update a parameter set map. This is equivalent to a map.putAll(newMap) . Both the maps are merged and if the new map has same keys as old they are overwritten
+
+You can mix these commands into a single request if necessary.
+
+Each map must include a name so it can be referenced later, either in a direct request to Solr or in a request handler definition.
+
+In the following example, we are setting 2 sets of parameters named 'myFacets' and 'myQueries'.
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "set":{
+ "myFacets":{
+ "facet":"true",
+ "facet.limit":5}},
+ "set":{
+ "myQueries":{
+ "defType":"edismax",
+ "rows":"5",
+ "df":"text_all"}}
+}'
+----
+
+In the above example all the parameters are equivalent to the "defaults" in `solrconfig.xml`. It is possible to add invariants and appends as follows:
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "set":{
+ "my_handler_params":{
+ "facet.limit":5,
+ "_invariants_": {
+ "facet":true,
+ "wt":"json"
+ },
+ "_appends_":{"facet.field":["field1","field2"]
+ }
+ }}
+}'
+----
+
+[[RequestParametersAPI-UsingRequestParameterswithRequestHandlers]]
+== Using Request Parameters with RequestHandlers
+
+After creating the `my_handler_params` paramset in the above section, it is possible to define a request handler as follows:
+
+[source,xml]
+----
+<requestHandler name="/my_handler" class="solr.SearchHandler" useParams="my_handler_params"/>
+----
+
+It will be equivalent to a standard request handler definition such as this one:
+
+[source,xml]
+----
+<requestHandler name="/my_handler" class="solr.SearchHandler">
+ <lst name="defaults">
+ <int name="facet.limit">5</int>
+ </lst>
+ <lst name="invariants">
+ <str name="wt">json</str>
+ <bool name="facet">true</bool>
+ </lst>
+ <lst name="appends">
+ <arr name="facet.field">
+ <str>field1</str>
+ <str>field2</str>
+ </arr>
+ </lst>
+</requestHandler>
+----
+
+[[RequestParametersAPI-ImplicitRequestHandlers]]
+=== Implicit RequestHandlers
+
+Solr ships with many out-of-the-box request handlers that may only be configured via the Request Parameters API, because their configuration is not present in `solrconfig.xml`. See <<implicit-requesthandlers.adoc#implicit-requesthandlers,Implicit RequestHandlers>> for the paramset to use when configuring an implicit request handler.
+
+[[RequestParametersAPI-ViewingExpandedParamsetsandEffectiveParameterswithRequestHandlers]]
+=== Viewing Expanded Paramsets and Effective Parameters with RequestHandlers
+
+To see the expanded paramset and the resulting effective parameters for a RequestHandler defined with `useParams`, use the `expandParams` request param. E.g. for the `/export` request handler:
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/requestHandler?componentName=/export&expandParams=true
+----
+
+[[RequestParametersAPI-ViewingRequestParameters]]
+== Viewing Request Parameters
+
+To see the paramsets that have been created, you can use the `/config/params` endpoint to read the contents of `params.json`, or use the name in the request:
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params
+
+#Or use the paramset name
+curl http://localhost:8983/solr/techproducts/config/params/myQueries
+----
+
+[[RequestParametersAPI-TheuseParamsParameter]]
+== The `useParams` Parameter
+
+When making a request, the `useParams` parameter applies the request parameters sent to the request. This is translated at request time to the actual parameters.
+
+For example (using the names we set up in the earlier examples, please replace with your own name):
+
+[source,text]
+----
+http://localhost/solr/techproducts/select?useParams=myQueries
+----
+
+It is possible to pass more than one parameter set in the same request. For example:
+
+[source,text]
+----
+http://localhost/solr/techproducts/select?useParams=myFacets,myQueries
+----
+
+In the above example the param set 'myQueries' is applied on top of 'myFacets'. So, values in 'myQueries' take precedence over values in 'myFacets'. Additionally, any values passed in the request take precedence over `useParams` parameters. This acts like the "defaults" specified in the `<requestHandler>` definition in `solrconfig.xml`.
+
+The parameter sets can be used directly in a request handler definition as follows. Please note that the `useParams` specified is always applied even if the request contains `useParams`.
+
+[source,xml]
+----
+<requestHandler name="/terms" class="solr.SearchHandler" useParams="myQueries">
+ <lst name="defaults">
+ <bool name="terms">true</bool>
+ <bool name="distrib">false</bool>
+ </lst>
+ <arr name="components">
+ <str>terms</str>
+ </arr>
+</requestHandler>
+----
+
+To summarize, parameters are applied in this order:
+
+* parameters defined in `<invariants>` in `solrconfig.xml`.
+* parameters applied in `invariants` in `params.json` and that is specified in the requesthandler definition or even in request
+* parameters defined in the request directly.
+* parameter sets defined in the request, in the order they have been listed with `useParams`.
+* parameter sets defined in `params.json` that have been defined in the request handler.
+* parameters defined in `<defaults>` in `solrconfig.xml`.
+
+[[RequestParametersAPI-PublicAPIs]]
+== Public APIs
+
+The RequestParams Object can be accessed using the method `SolrConfig#getRequestParams()`. Each paramset can be accessed by their name using the method `RequestParams#getRequestParams(String name)`.
+
+[[RequestParametersAPI-Examples]]
+== Examples
+
+The Solr "films" example demonstrates the use of the parameters API. See https://github.com/apache/lucene-solr/tree/master/solr/example/films for details.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/requestdispatcher-in-solrconfig.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/requestdispatcher-in-solrconfig.adoc b/solr/solr-ref-guide/src/requestdispatcher-in-solrconfig.adoc
new file mode 100644
index 0000000..44ef0b1
--- /dev/null
+++ b/solr/solr-ref-guide/src/requestdispatcher-in-solrconfig.adoc
@@ -0,0 +1,82 @@
+= RequestDispatcher in SolrConfig
+:page-shortname: requestdispatcher-in-solrconfig
+:page-permalink: requestdispatcher-in-solrconfig.html
+
+The `requestDispatcher` element of `solrconfig.xml` controls the way the Solr HTTP `RequestDispatcher` implementation responds to requests.
+
+Included are parameters for defining if it should handle `/select` urls (for Solr 1.1 compatibility), if it will support remote streaming, the maximum size of file uploads and how it will respond to HTTP cache headers in requests.
+
+[[RequestDispatcherinSolrConfig-handleSelectElement]]
+== `handleSelect` Element
+
+[IMPORTANT]
+====
+`handleSelect` is for legacy back-compatibility; those new to Solr do not need to change anything about the way this is configured by default.
+====
+
+The first configurable item is the `handleSelect` attribute on the `<requestDispatcher>` element itself. This attribute can be set to one of two values, either "true" or "false". It governs how Solr responds to requests such as `/select?qt=XXX`. The default value "false" will ignore requests to `/select` if a requestHandler is not explicitly registered with the name `/select`. A value of "true" will route query requests to the parser defined with the `qt` value.
+
+In recent versions of Solr, a `/select` requestHandler is defined by default, so a value of "false" will work fine. See the section <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#requesthandlers-and-searchcomponents-in-solrconfig,RequestHandlers and SearchComponents in SolrConfig>> for more information.
+
+[source,xml]
+----
+<requestDispatcher handleSelect="true" >
+ ...
+</requestDispatcher>
+----
+
+[[RequestDispatcherinSolrConfig-requestParsersElement]]
+== `requestParsers` Element
+
+The `<requestParsers>` sub-element controls values related to parsing requests. This is an empty XML element that doesn't have any content, only attributes.
+
+The attribute `enableRemoteStreaming` controls whether remote streaming of content is allowed. If set to `false`, streaming will not be allowed. Setting it to `true` (the default) lets you specify the location of content to be streamed using `stream.file` or `stream.url` parameters.
+
+If you enable remote streaming, be sure that you have authentication enabled. Otherwise, someone could potentially gain access to your content by accessing arbitrary URLs. It's also a good idea to place Solr behind a firewall to prevent it being accessed from untrusted clients.
+
+The attribute `multipartUploadLimitInKB` sets an upper limit in kilobytes on the size of a document that may be submitted in a multi-part HTTP POST request. The value specified is multiplied by 1024 to determine the size in bytes.
+
+The attribute `formdataUploadLimitInKB` sets a limit in kilobytes on the size of form data (application/x-www-form-urlencoded) submitted in a HTTP POST request, which can be used to pass request parameters that will not fit in a URL.
+
+The attribute `addHttpRequestToContext` can be used to indicate that the original `HttpServletRequest` object should be included in the context map of the `SolrQueryRequest` using the key `httpRequest`. This `HttpServletRequest` is not used by any Solr component, but may be useful when developing custom plugins.
+
+[source,xml]
+----
+<requestParsers enableRemoteStreaming="true"
+ multipartUploadLimitInKB="2048000"
+ formdataUploadLimitInKB="2048"
+ addHttpRequestToContext="false" />
+----
+
+[[RequestDispatcherinSolrConfig-httpCachingElement]]
+== `httpCaching` Element
+
+The `<httpCaching>` element controls HTTP cache control headers. Do not confuse these settings with Solr's internal cache configuration. This element controls caching of HTTP responses as defined by the W3C HTTP specifications.
+
+This element allows for three attributes and one sub-element. The attributes of the `<httpCaching>` element control whether a 304 response to a GET request is allowed, and if so, what sort of response it should be. When an HTTP client application issues a GET, it may optionally specify that a 304 response is acceptable if the resource has not been modified since the last time it was fetched.
+
+// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+
+[cols="20,80",options="header"]
+|===
+|Parameter |Description
+|never304 |If present with the value `true`, then a GET request will never respond with a 304 code, even if the requested resource has not been modified. When this attribute is set to true, the next two attributes are ignored. Setting this to true is handy for development, as the 304 response can be confusing when tinkering with Solr responses through a web browser or other client that supports cache headers.
+|lastModFrom |This attribute may be set to either `openTime` (the default) or `dirLastMod`. The value `openTime` indicates that last modification times, as compared to the If-Modified-Since header sent by the client, should be calculated relative to the time the Searcher started. Use `dirLastMod` if you want times to exactly correspond to when the index was last updated on disk.
+|etagSeed |This value of this attribute is sent as the value of the `ETag` header. Changing this value can be helpful to force clients to re-fetch content even when the indexes have not changed---for example, when you've made some changes to the configuration.
+|===
+
+[source,xml]
+----
+<httpCaching never304="false"
+ lastModFrom="openTime"
+ etagSeed="Solr">
+ <cacheControl>max-age=30, public</cacheControl>
+</httpCaching>
+----
+
+[[RequestDispatcherinSolrConfig-cacheControlElement]]
+=== `cacheControl` Element
+
+In addition to these attributes, `<httpCaching>` accepts one child element: `<cacheControl>`. The content of this element will be sent as the value of the Cache-Control header on HTTP responses. This header is used to modify the default caching behavior of the requesting client. The possible values for the Cache-Control header are defined by the HTTP 1.1 specification in http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9[Section 14.9].
+
+Setting the max-age field controls how long a client may re-use a cached response before requesting it again from the server. This time interval should be set according to how often you update your index and whether or not it is acceptable for your application to use content that is somewhat out of date. Setting `must-revalidate` will tell the client to validate with the server that its cached copy is still good before re-using it. This will ensure that the most timely result is used, while avoiding a second fetch of the content if it isn't needed, at the cost of a request to the server to do the check.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ccbc93b8/solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc b/solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc
new file mode 100644
index 0000000..380e2c5
--- /dev/null
+++ b/solr/solr-ref-guide/src/requesthandlers-and-searchcomponents-in-solrconfig.adoc
@@ -0,0 +1,167 @@
+= RequestHandlers and SearchComponents in SolrConfig
+:page-shortname: requesthandlers-and-searchcomponents-in-solrconfig
+:page-permalink: requesthandlers-and-searchcomponents-in-solrconfig.html
+
+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 _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.
+
+These are often referred to as "requestHandler" and "searchComponent", which is how they are defined in `solrconfig.xml`.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-RequestHandlers]]
+== 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 using URLs 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.
+
+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 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.
+
+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>>.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-SearchHandlers]]
+=== SearchHandlers
+
+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.
+
+For example, in the default `solrconfig.xml`, the first request handler defined looks like this:
+
+[source,xml]
+----
+<requestHandler name="/select" class="solr.SearchHandler">
+ <lst name="defaults">
+ <str name="echoParams">explicit</str>
+ <int name="rows">10</int>
+ </lst>
+</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.
+
+All of the parameters described in the section <<searching.adoc#searching,Searching>> can be defined as defaults for any of the SearchHandlers.
+
+Besides `defaults`, there are other options for the SearchHandler, which are:
+
+* `appends`: This allows definition of parameters that are added to the user query. These might be <<common-query-parameters.adoc#CommonQueryParameters-Thefq_FilterQuery_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`.
++
+[source,xml]
+----
+<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>
+----
++
+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 <<RequestHandlersandSearchComponentsinSolrConfig-SearchComponents,Search Components>>. The `components` element can only be used with a request handler that is a SearchHandler.
+
+The `solrconfig.xml` file includes many other examples of SearchHandlers that can be used or modified as needed.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-UpdateRequestHandlers]]
+=== UpdateRequestHandlers
+
+The UpdateRequestHandlers are request handlers which process updates to the index.
+
+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>>.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-ShardHandlers]]
+=== ShardHandlers
+
+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>>.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-ImplicitRequestHandlers]]
+=== 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>>.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-SearchComponents]]
+== Search Components
+
+Search components define the logic that is used by the SearchHandler to perform queries for users.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-DefaultComponents]]
+=== Default Components
+
+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:
+
+// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+
+[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>>.
+|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>>.
+|debug |solr.DebugComponent |Described in the section on <<common-query-parameters.adoc#CommonQueryParameters-ThedebugParameter,Common Query Parameters>>.
+|expand |solr.ExpandComponent |Described in the section <<collapse-and-expand-results.adoc#collapse-and-expand-results,Collapse and Expand Results>>.
+|===
+
+If you register a new search component with one of these default names, the newly defined component will be used instead of the default.
+
+[[RequestHandlersandSearchComponentsinSolrConfig-First-ComponentsandLast-Components]]
+=== First-Components and Last-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]
+----
+<arr name="first-components">
+ <str>mycomponent</str>
+</arr>
+<arr name="last-components">
+ <str>spellcheck</str>
+</arr>
+----
+
+[[RequestHandlersandSearchComponentsinSolrConfig-Components]]
+=== Components
+
+If you define `components`, the default components (see above) will not be executed, and `first-components` and `last-components` are disallowed:
+
+[source,xml]
+----
+<arr name="components">
+ <str>mycomponent</str>
+ <str>query</str>
+ <str>debug</str>
+</arr>
+----
+
+[[RequestHandlersandSearchComponentsinSolrConfig-OtherUsefulComponents]]
+=== Other Useful Components
+
+Many of the other useful components are described in sections of this Guide for the features they support. These are:
+
+* `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>>.
+* `TermsComponent`, described in the section <<the-terms-component.adoc#the-terms-component,The Terms Component>>.