ctargett commented on a change in pull request #2159:
URL: https://github.com/apache/lucene-solr/pull/2159#discussion_r552983347
##########
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:
GitHub also allows one to view the whole file as of the commit, which is
what I did so I feel like I did already look at your changes in their broader
context. I think you've misunderstood the point of my comment, which is not
only about that one change, but how it relates to the child bullets under it
(which you didn't change, so maybe overlooked).
The bullet point in question talks about the `_route_` field.
Right under that, indented so it is clearly _part of the same bullet item_,
is an example from a schema for the `_nest_path_` field. There is no `_route_`
field shown in the example. This example used to have text which introduced the
`_nest_path_` field, but that was removed to add the current paragraph about
the `_route_` field.
This example is now the very first time the `_nest_path_` field is mentioned
on the page. What is that field? How does it relate to the `_route_` field?
Right after this example, there is a child-level bullet that states: "In a
nutshell, this fields makes child/nested documents easier to use, and so it’s
recommended you add it." Which field? The typo makes it even more confusing -
does it mean both fields?
The next child-level bullet again says "This field enables Solr to ..." -
again, which field?
A later child-level bullet then says, "If you don't use `_nest_path_` ..."
This is only the 2nd time this field is mentioned. What is this field? Why
would I use it or not use it?
----------------------------------------------------------------
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:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
