[
https://issues.apache.org/jira/browse/SOLR-14383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17128682#comment-17128682
]
Chris M. Hostetter commented on SOLR-14383:
-------------------------------------------
i was recently reminded of this Jira when i tried to look up the current state
of nested document support in solr 8.5, and realized a few additional things
about these examples that are super confusing:
# the field names used in these examples aren't valid in the default solr
schema unless you have schemaless field guessing enabled – but even then the
docs use "ID" (all caps) instead of "id" so trying to add these documents fails
due to a missing uniqueKey
# the examples only show the "raw" input documents, not how/where to index
them – if you try to use
{{[http://localhost:8983/solr/gettingstarted/update/json/docs]}} (the
convenience path recommended in other places of the ref-guide because it
automatically assumes the JSON content type and expects a list of JSON
documents instead of a list of solr update commands) you will not get any
nested docs, because that path has the implicit params for flattening custom
json:
[https://lucene.apache.org/solr/guide/8_5/transforming-and-indexing-custom-json.html]
> 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
> Priority: Major
>
> 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
