SOLR-12490: Describe json.queries in the ref guide.

Link it from many pages.
Fix a few errors by the way.

solr/solr-ref-guide/src/common-query-parameters.adoc

@@ -102,7 +102,7 @@ fq=+popularity:[10 TO *] +section:0
 ----
 
 * The document sets from each filter query are cached independently. Thus, concerning the previous examples: use a single `fq` containing two mandatory clauses if those clauses appear together often, and use two separate `fq` parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see <<the-well-configured-solr-instance.adoc#the-well-configured-solr-instance,The Well-Configured Solr Instance>>.)
-* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucenes-classic-query-parser-and-solrs-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
+* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucene-s-classic-query-parser-and-solr-s-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
 
 * As with all parameters: special characters in an URL need to be properly escaped and encoded as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/.
 

solr/solr-ref-guide/src/json-faceting-domain-changes.adoc

@@ -72,10 +72,47 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-json-facet-filter
 The value of `filter` can be a single query to treat as a filter, or a JSON list of filter queries.  Each query can be:
 
 * a string containing a query in Solr query syntax.
-* a reference to a request parameter containing Solr query syntax, of the form: `{param: <request_param_name>}`.
+* a reference to a request parameter containing Solr query syntax, of the form: `{param: <request_param_name>}`. It's possible to refer to one or multiple queries in DSL syntax defined under <<json-query-dsl.adoc#additional-queries,queries>> key in JSON Request API.
 The referred parameter might have 0 (absent) or many values.
 ** When no values are specified, no filter is applied and no error is thrown.
-** When many values are specified, each value is parsed and used as filters.
+** When many values are specified, each value is parsed and used as filters in conjunction.
+
+Here is the example of referencing DSL queries: 
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/query -d '
+{
+  "query": "*:*",
+  "queries": {
+      "sample_filtrs":[
+           {"field":{"f":"text", "query":"usb"}},
+           {"field":{"f":"text", "query":"lcd"}}
+        ],
+        "another_filtr":
+            {"field":{"f":"text", "query":"usb"}}
+  },
+  "facet": {
+    "usblcd": {
+      "type": "terms",
+      "field": "cat",
+      "limit": 3,
+      "domain": {
+        "filter": {"param":"sample_filtrs"}
+      }
+    },
+    "justusb": {
+      "type": "terms",
+      "field": "cat",
+      "limit": 3,
+      "domain": {
+        "filter": {"param":"another_filtr"}
+      }
+    }
+  }
+}'
+----
+
 
 When a `filter` option is combined with other `domain` changing options, the filtering is applied _after_ the other domain changes take place.
 

solr/solr-ref-guide/src/json-query-dsl.adoc

@@ -339,6 +339,27 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-ipod-query-bool-f
 ====
 --
 
+== Additional Queries
+
+Multiple additional queries might be specified under `queries` key with all syntax alternatives described above. Every entry might have multiple values in array. Notice that old-style referencing `"{!v=$query_name}"` picks only the first element in array ignoring everything beyond, e.g. if one changes the reference below from `"{!v=$electronic}"` to `"{!v=$manufacturers}"` it's equivalent to querying for `manu:apple`, ignoring the later query. These queries don't impact query result until explicit referencing.
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/solr/techproducts/query -d '
+{ 
+    "queries": {
+        "electronic": {"field": {"f":"cat", "query":"electronics"}},
+        "manufacturers": [
+           "manu:apple",
+           {"field": {"f":"manu", "query":"belkin"}}
+        ]
+    },
+    "query":"{!v=$electronic}"
+}'
+----
+
+Overall this example doesn't make much sense, but just demonstrates the syntax. This feature is useful in <<json-faceting-domain-changes.adoc#adding-domain-filters,filtering domain>> in JSON Facet API <<json-facet-api.adoc#changing-the-domain,domain changes>>.
+
 == Tagging in JSON Query DSL
 Query and filter clauses can also be individually "tagged".  Tags serve as handles for query clauses, allowing them to be referenced from elsewhere in the request.  This is most commonly used by the filter-exclusion functionality offered by both <<faceting.adoc#tagging-and-excluding-filters,traditional>> and <<json-faceting-domain-changes.adoc#filter-exclusions,JSON>> faceting.
 

solr/solr-ref-guide/src/json-request-api.adoc

@@ -19,7 +19,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-Solr supports an alternate request API which accepts requests composed in part or entirely of JSON objects. This alternate API can be preferable in some situations, where its increased readability and flexibility make it easier to use than the entirely query-param driven alternative.  There is also some functionality which can only be accessed through this JSON request API, such as much of the analytics capabilities of <<json-facet-api.adoc#json-facet-api,JSON Faceting>>
+Solr supports an alternate request API which accepts requests composed in part or entirely of JSON objects. This alternate API can be preferable in some situations, where its increased readability and flexibility make it easier to use than the entirely query-param driven alternative.  There is also some functionality which can only be accessed through this JSON request API, such as much of the analytics capabilities of <<json-facet-api.adoc#facet-analytics-module,JSON Faceting>>
 
 == Building JSON Requests
 The core of the JSON Request API is its ability to specify request parameters as JSON in the request body, as shown by the example below:
@@ -172,7 +172,7 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-json-facet-all-qu
 ====
 --
 
-See the <<json-facet-api.adoc#json-facet-api,JSON Facet API>> for more on faceting and analytics commands.
+See the <<json-facet-api.adoc#facet-analytics-module,JSON Facet API>> for more on faceting and analytics commands.
 
 == Supported Properties and Syntax
 
@@ -205,6 +205,9 @@ Right now, only some of Solr's traditional query parameters have first class JSO
 
 |`json.<param_name>`
 |`<param_name>`
+
+|`json.queries.<query_name>`
+|`queries`
 |===
 
 Parameters not specified in the table above can still be used in the main body of JSON API requests, but they must be put within a `params` block as shown in the example below.
@@ -240,7 +243,11 @@ include::{example-source-dir}JsonRequestApiTest.java[tag=solrj-json-query-params
 Parameters placed in a `params` block act as if they were added verbatim to the query-parameters of the request.  The request above is equivalent to:
 
 [source,bash]
+----
 curl "http://localhost:8983/solr/techproducts/query?fl=name,price&q=memory&rows=1"
+----
+
+Usage of `queries` key is described in <<json-query-dsl.adoc#additional-queries,Query DSL>>.
 
 
 === Parameter Substitution / Macro Expansion

solr/solr-ref-guide/src/searching.adoc

@@ -62,7 +62,7 @@ This section describes how Solr works with search requests. It covers the follow
 ** <<other-parsers.adoc#other-parsers,Other Parsers>>: More parsers designed for use in specific situations.
 * <<json-request-api.adoc#json-request-api,JSON Request API>>: Overview of Solr's JSON Request API.
 ** <<json-query-dsl.adoc#json-query-dsl,JSON Query DSL>>: Detailed information about a simple yet powerful query language for JSON Request API.
-* <<json-facet-api.adoc#json-facet-api,JSON Facet API>>: Overview of Solr's JSON Facet API.
+* <<json-facet-api.adoc#facet-analytics-module,JSON Facet API>>: Overview of Solr's JSON Facet API.
 * <<faceting.adoc#faceting,Faceting>>: Detailed information about categorizing search results based on indexed terms.
 * <<highlighting.adoc#highlighting,Highlighting>>: Detailed information about Solr's highlighting capabilities, including multiple underlying highlighter implementations.
 * <<spell-checking.adoc#spell-checking,Spell Checking>>: Detailed information about Solr's spelling checker.