Uploaded image for project: 'Solr'
  1. Solr
  2. SOLR-12298 Index Full nested document Hierarchy For Queries (umbrella issue)
  3. SOLR-14383

Fix indexing-nested-documents.adoc XML/JSON examples to be accurate, consistent, and clear

    XMLWordPrintableJSON

Details

    • Sub-task
    • Status: Closed
    • Major
    • Resolution: Fixed
    • None
    • 8.7, 9.0
    • None
    • None

    Description

      As reported on solr-user@lucene by Peter Pimley...

      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.
      
      • 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

      Attachments

        1. SOLR-14383.patch
          23 kB
          Chris M. Hostetter
        2. SOLR-14383.patch
          40 kB
          Chris M. Hostetter
        3. SOLR-14383.patch
          49 kB
          Chris M. Hostetter
        4. SOLR-14383.patch
          50 kB
          Chris M. Hostetter
        5. SOLR-14383.patch
          103 kB
          Chris M. Hostetter

        Issue Links

          Activity

            People

              hossman Chris M. Hostetter
              hossman Chris M. Hostetter
              Votes:
              1 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: