[
https://issues.apache.org/jira/browse/SOLR-14383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17182195#comment-17182195
]
Chris M. Hostetter commented on SOLR-14383:
-------------------------------------------
FWIW: i keep going back and forth on _where_ it makes the most sense to explain
non-trivial of/which params.
My current thinking, as reflected in my latest branch commits, is that
{{other-parsers.adoc}} should have a sub section introducing the _concept_
(which i've labeled "Block Mask" to differentiate from "all parents" when it
has to include docs which are not parents or children) that explains how/why it
can be tricky in non-trivial situations, and then the (later and more in depth)
{{searching-nested-documents.adoc}} go into the specifics of writing good
"Block Mask" queries when using {{_nest_path_}} with multi-level hierarchies.
(still work to be done, but i'm about to go offline for a week and didn't want
to forget this on my laptop)
> Fix indexing-nested-documents.adoc XML/JSON examples to be accurate,
> consistent, and clear
> ------------------------------------------------------------------------------------------
>
> Key: SOLR-14383
> URL: https://issues.apache.org/jira/browse/SOLR-14383
> Project: Solr
> Issue Type: Sub-task
> Reporter: Chris M. Hostetter
> Assignee: Chris M. Hostetter
> Priority: Major
> Attachments: SOLR-14383.patch, SOLR-14383.patch, SOLR-14383.patch,
> SOLR-14383.patch
>
>
> As reported on solr-user@lucene by Peter Pimley...
> {noformat}
> The page "Indexing Nested Documents" has an XML example showing two
> different ways of adding nested documents:
> https://lucene.apache.org/solr/guide/8_5/indexing-nested-documents.html#xml-examples
> The text says:
> "It illustrates two styles of adding child documents: the first is
> associated via a field "comment" (preferred), and the second is done
> in the classic way now referred to as an "anonymous" or "unlabelled"
> child document."
> However in the XML directly below there is no field named "comment".
> There is one named "content" and another named "comments" (plural),
> but no field named "comment". In fact, looking at the Json example
> immediately below, I wonder if the XML element currently named
> "content" should be named "comments", and what is currently marked
> "comments" should be "content"?
> Secondly, in the Json example it says:
> "The labelled relationship here is one child document but could have
> been wrapped in array brackets."
> However in the actual Json, the parent document (ID=1) with a labelled
> relationship has two child documents (IDs 2 and 3), and they are
> already in array brackets.
> {noformat}
> * The 2 examples (XML and JSON) should be updated to contains *structurally*
> identical content, (ie: same number of documents, with same field values, and
> same hierarchical relationships) to focus on demonstrating the syntax
> differences (ie: things like the special {{\_childDocuments\_}} key in json)
> * The paragraphs describing the examples should be updated to:
> ** refer to the correct field names -- since both "comments" and "contents"
> fields exist in the examples, it's impossible for novice users to even
> udnerstand where th "typo" might be in the descriptions (I'm pretty
> knowledgeable about Solr and even i'm second guessing myself as to what the
> intent in these paragraphs are)
> ** refer to documents by {{"id"}} value, not just descriptors like "first"
> and "second"
> * it might be worth considering rewriting this section to use "callouts":
> https://asciidoctor.org/docs/user-manual/#callouts -- similar to how we use
> them in other sections like this:
> https://lucene.apache.org/solr/guide/8_5/uploading-data-with-index-handlers.html#sending-json-update-commands
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
