From 3a743ea953f0ecfc35fc7b198f68d142ce99d789 Mon Sep 17 00:00:00 2001
From: Mikhail Khludnev <mkhl@apache.org>
Date: Wed, 22 Apr 2020 23:19:34 +0300
Subject: [PATCH] SOLR-8998,SOLR-12490: Polishing reference guide.

---
 solr/solr-ref-guide/src/indexing-nested-documents.adoc | 2 +-
 solr/solr-ref-guide/src/json-facet-api.adoc            | 2 +-
 solr/solr-ref-guide/src/json-query-dsl.adoc            | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/solr/solr-ref-guide/src/indexing-nested-documents.adoc b/solr/solr-ref-guide/src/indexing-nested-documents.adoc
index 8ea16de35f7..e699cb229a4 100644
--- a/solr/solr-ref-guide/src/indexing-nested-documents.adoc
+++ b/solr/solr-ref-guide/src/indexing-nested-documents.adoc
@@ -38,7 +38,7 @@ With the exception of in-place updates, the whole block must be updated or delet
  * The schema must include an indexed field `\_root_`. Solr automatically populates this with the value of the top/parent ID. +
  `<field name="\_root_" type="string" indexed="true" stored="false" docValues="false" />`
  ** `\_root_` must be set either as stored (stored="true") or doc values (docValues="true") to enable
-    <<updating-parts-of-documents#updating-child-documents, atomic updates of nested documents>>.
+    <<updating-parts-of-documents#updating-child-documents, atomic updates of nested documents>>. Also, beware of `uniqueBlock(\_root_)` <<json-facet-api#stat-facet-functions,field type limitation>>, if you plan to use one.
  * `\_nest_path_` is populated by Solr automatically with the path of the document in the hierarchy for non-root documents. This field is optional. +
  `<fieldType name="\_nest_path_" class="solr.NestPathField" />
   <field name="\_nest_path_" type="_nest_path_" />`
diff --git a/solr/solr-ref-guide/src/json-facet-api.adoc b/solr/solr-ref-guide/src/json-facet-api.adoc
index 1d2bc8adab9..d40362ead02 100644
--- a/solr/solr-ref-guide/src/json-facet-api.adoc
+++ b/solr/solr-ref-guide/src/json-facet-api.adoc
@@ -572,7 +572,7 @@ Unlike all the facets discussed so far, Aggregation functions (also called *face
 |missing |`missing(author)` |number of documents which do not have value for given field or function
 |countvals |`countvals(author)` |number of values for a given field or function
 |unique |`unique(author)` |number of unique values of the given field. Beyond 100 values it yields not exact estimate
-|uniqueBlock |`uniqueBlock(\_root_)` or `uniqueBlock($fldref)` where `fldref=_root_` |same as above with smaller footprint strictly for <<json-faceting-domain-changes.adoc#block-join-domain-changes,counting the number of Block Join blocks>>. The given field must be unique across blocks, and only singlevalued string fields are supported, docValues are recommended.
+|uniqueBlock |`uniqueBlock(\_root_)` or `uniqueBlock($fldref)` where `fldref=\_root_` |same as above with smaller footprint strictly for <<json-faceting-domain-changes.adoc#block-join-domain-changes,counting the number of Block Join blocks>>. The given field must be unique across blocks, and only singlevalued string fields are supported, docValues are recommended.
 | |`uniqueBlock({!v=type:parent})` or `uniqueBlock({!v=$qryref})` where `qryref=type:parent` |same as above, but using bitset of the given query to aggregate hits.
 |hll |`hll(author)` |distributed cardinality estimate via hyper-log-log algorithm
 |percentile |`percentile(salary,50,75,99,99.9)` |Percentile estimates via t-digest algorithm. When sorting by this metric, the first percentile listed is used as the sort value.
diff --git a/solr/solr-ref-guide/src/json-query-dsl.adoc b/solr/solr-ref-guide/src/json-query-dsl.adoc
index fbb7fd5f733..e38ea0832fe 100644
--- a/solr/solr-ref-guide/src/json-query-dsl.adoc
+++ b/solr/solr-ref-guide/src/json-query-dsl.adoc
@@ -358,7 +358,7 @@ curl -X POST http://localhost:8983/solr/techproducts/query -d '
 }'
 ----
 
-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>>.
+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>>. Note that these declarations add request parameters underneath, so using same names with other parameters might cause unexpected behavior. 
 
 == 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.