dsmiley commented on a change in pull request #2159:
URL: https://github.com/apache/lucene-solr/pull/2159#discussion_r552920830
##########
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:
I don't think I broke the flow of introduction. Perhaps the diff makes
this unclear? Any way, I just submitted an update that improves the whole
matter (I hope). I recommend building the HTML file looking at it in a browser.
----------------------------------------------------------------
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
