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:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
