[GitHub] [lucene-solr] ctargett commented on a change in pull request #2159: SOLR-14923: Nested docs indexing performance.

[GitBox <gi...@apache.org>]

ctargett commented on a change in pull request #2159:
URL: https://github.com/apache/lucene-solr/pull/2159#discussion_r552851326



##########
File path: solr/solr-ref-guide/src/indexing-nested-documents.adoc
##########
@@ -218,31 +225,40 @@ Indexing nested documents _requires_ an indexed field named `\_root_`:
 
 [source,xml]
 ----
-<field name="_root_" type="string" indexed="true" />
+<field name="_root_" type="string" indexed="true" stored="false" docValues="false" />
 ----
 
-Solr automatically populates this field in every nested document with the `id` value of the top most parent document in the block.
+Solr automatically populates this field in _all_ documents with the `id` value of it's root document
+-- it's highest ancestor, possibly itself.
 
 
 There are several additional schema considerations that should be considered for people who wish to use nested documents:
 
-* Nested child documents are very much documents in their own right even if certain nested documents hold different information from the parent, Therefore:
+* Nested child documents are very much documents in their own right even if certain nested
+documents hold different information from the parent or other child documents, therefore:
 ** All field names in the schema can only be configured in one -- different types of child documents can not have the same field name configured in different ways.
-** It may be infeasible to use `required` for any field names that aren't reqiured for all types of documents.
+** It may be infeasible to use `required` for any field names that aren't required for all types of
+documents.
 ** Even child documents need a _globally_ unique `id`.
-* `\_root_` must be configured to either be stored (`stored="true"`) or use doc values (`docValues="true"`) to enable <<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 an optional field that (if definied) will be populated by Solr automatically with the ancestor path of each non-root document.
+* The `\_root_` must be indexed (`indexed="true"`) but doesn't need to
+ be either stored (`stored="true"`) or use doc values (`docValues="true"`), however you are free
+to do so if you find it useful.  If you want to use `uniqueBlock(\_root_)`
+<<json-facet-api#stat-facet-functions,field type limitation>>, then you should enable docValues.

Review comment:
       The removed section introduces the `_nest_path_` field which is shown in the example that has been retained. However the change here talks about the field requirements for the `_root_` field. That leaves the `_nest_path_` field unaddressed and makes the following example seem like it's coming out of nowhere. This gets a bit more confusing as the section goes on, with a later sub-bullet that talks about the `_nest_path_` field which hasn't been discussed really up to that point (the example is literally the first time in the doc that it's mentioned).




----------------------------------------------------------------
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:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org