Derby
  1. Derby
  2. DERBY-5198

XPLAIN table documentation needs some cleanup

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      While working on DERBY-5184 (table cleanup), I noticed that in some of the XPLAIN style tables topics there remain some questions that were not answered by reviewers and that managed to make it into the final documentation. These should be fixed separately from DERBY-5184, which focuses on formatting rather than substantive questions.

      I'll list the problems in a comment.

      1. DERBY-5198.zip
        17 kB
        Kim Haase
      2. DERBY-5198.stat
        0.2 kB
        Kim Haase
      3. DERBY-5198.diff
        4 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        I've listed the issues with the XPLAIN system table docs below, along with some possible solutions if they seem obvious.

        rrefsysxplain_statements.dita, STMT_NAME row:

        "The name of the associated query or statement. This value is NULL if the user did not assign a name. I'm not sure how the user assigns a name to a statement, perhaps by calling Statement.setCursorName()?"

        Do we know the answer to this? Otherwise, I can just remove the question.

        rrefsysxplain_resultsets.dita, OP_IDENTIFIER row:

        "A code indicating what type of result set these statistics are for. Common result set types include: TABLESCAN, INDEXSCAN, PROJECTION, etc. Should I try to list all the result set types here?"

        Are the names easy to find somewhere? (I can't find them, but that means little.) If not, they should be listed; if so, the examples are fine.

        rrefsysxplain_resultsets.dita, DEFERRED_ROWS row:

        "The column is only non-null for INSERT, UPDATE, and DELETE result sets. For those result sets, this column holds 'Y' if the INSERT/UPDATE/DELETE is being performed using deferred change semantics, and holds 'N' otherwise. I think that deferred change semantics are used when there is self-referencing going on, and we must avoid the "Halloween" problem of processing the rows multiple times."

        Can "I think that" be removed? More rephrasing might be helpful.

        rrefsysxplain_resultset_timings.dita, TEMP_CONG_CREATE_TIME row:

        "For result sets which involve a materialization of a temporary intermediate result set, this value is the time it took to create the materialized result set, in milliseconds. I think this may occur with hash joins where the number of rows in the intermediate result is too large to hold in memory?"

        Can "I think" be removed?

        rrefsysxplain_scan_props.dita, FETCH_SIZE row:

        "I think this is the number of pages fetched at a time when the scan is retrieving pages from disk? I expected this to be 16 when doing a TABLESCAN, and 1 when doing an INDEXSCAN, but I've also seen it be 16 for INDEXSCAN?"

        Can this be changed to just "The number of pages fetched at a time when the scan is retrieving pages from disk"?

        rrefsysxplain_sort_props.dita, SORT_TYPE row:

        "A code indicating the type of sort that was performed. The code values include 'IN' for an internal sort, and 'EX' for an external sort. I think that an internal sort is one which was entirely performed in-memory and did not overflow to any temporary files, while an external sort used one or more external files."

        Can "I think that" be removed?

        Show
        Kim Haase added a comment - I've listed the issues with the XPLAIN system table docs below, along with some possible solutions if they seem obvious. rrefsysxplain_statements.dita, STMT_NAME row: "The name of the associated query or statement. This value is NULL if the user did not assign a name. I'm not sure how the user assigns a name to a statement, perhaps by calling Statement.setCursorName()?" Do we know the answer to this? Otherwise, I can just remove the question. rrefsysxplain_resultsets.dita, OP_IDENTIFIER row: "A code indicating what type of result set these statistics are for. Common result set types include: TABLESCAN, INDEXSCAN, PROJECTION, etc. Should I try to list all the result set types here?" Are the names easy to find somewhere? (I can't find them, but that means little.) If not, they should be listed; if so, the examples are fine. rrefsysxplain_resultsets.dita, DEFERRED_ROWS row: "The column is only non-null for INSERT, UPDATE, and DELETE result sets. For those result sets, this column holds 'Y' if the INSERT/UPDATE/DELETE is being performed using deferred change semantics, and holds 'N' otherwise. I think that deferred change semantics are used when there is self-referencing going on, and we must avoid the "Halloween" problem of processing the rows multiple times." Can "I think that" be removed? More rephrasing might be helpful. rrefsysxplain_resultset_timings.dita, TEMP_CONG_CREATE_TIME row: "For result sets which involve a materialization of a temporary intermediate result set, this value is the time it took to create the materialized result set, in milliseconds. I think this may occur with hash joins where the number of rows in the intermediate result is too large to hold in memory?" Can "I think" be removed? rrefsysxplain_scan_props.dita, FETCH_SIZE row: "I think this is the number of pages fetched at a time when the scan is retrieving pages from disk? I expected this to be 16 when doing a TABLESCAN, and 1 when doing an INDEXSCAN, but I've also seen it be 16 for INDEXSCAN?" Can this be changed to just "The number of pages fetched at a time when the scan is retrieving pages from disk"? rrefsysxplain_sort_props.dita, SORT_TYPE row: "A code indicating the type of sort that was performed. The code values include 'IN' for an internal sort, and 'EX' for an external sort. I think that an internal sort is one which was entirely performed in-memory and did not overflow to any temporary files, while an external sort used one or more external files." Can "I think that" be removed?
        Hide
        Bryan Pendleton added a comment -

        Hi Kim, thanks for working on this. All your proposed adjustments to the text
        seem fine to me. In an ideal world, I suppose we could try to improve the docs
        to answer some of these questions, but since the existing docs have been out
        there for a while now and nobody's particularly complained that those explanations
        are inadequate, I think they're as good as they're going to get for the time being.

        So yes, please, remove the hemming and hawing that I left in those docs; I think
        your rewrite will make those pages quite a bit better.

        Show
        Bryan Pendleton added a comment - Hi Kim, thanks for working on this. All your proposed adjustments to the text seem fine to me. In an ideal world, I suppose we could try to improve the docs to answer some of these questions, but since the existing docs have been out there for a while now and nobody's particularly complained that those explanations are inadequate, I think they're as good as they're going to get for the time being. So yes, please, remove the hemming and hawing that I left in those docs; I think your rewrite will make those pages quite a bit better.
        Hide
        Kim Haase added a comment -

        Thanks very much, Bryan! I'm attaching DERBY-5198.diff, DERBY-5198.stat, and DERBY-5198.zip, with a proposed patch modifying the following:

        M src/ref/rrefsysxplain_sort_props.dita
        M src/ref/rrefsysxplain_scan_props.dita
        M src/ref/rrefsysxplain_resultsets.dita
        M src/ref/rrefsysxplain_resultset_timings.dita
        M src/ref/rrefsysxplain_statements.dita

        With the OP_IDENTIFIER row in rrefsysxplain_resultsets.dita, I found that the list of types is not easy to find (it is only in the Derby source code in java/engine/org/apache/derby/impl/sql/execute/xplain/XPLAINUtil.java, as far as I can tell), and it is also pretty long – I'm guessing it's all the strings with an OP_ prefix, 39 in all. But since the output is likely to be fairly self-explanatory I don't think we need to list them.

        With the OP_DETAILS row in the same topic, I left off the part about the "Halloween" problem, which seemed like more detail than necessary – but I can put it back if you think it would be helpful.

        Thanks for your feedback!

        Show
        Kim Haase added a comment - Thanks very much, Bryan! I'm attaching DERBY-5198 .diff, DERBY-5198 .stat, and DERBY-5198 .zip, with a proposed patch modifying the following: M src/ref/rrefsysxplain_sort_props.dita M src/ref/rrefsysxplain_scan_props.dita M src/ref/rrefsysxplain_resultsets.dita M src/ref/rrefsysxplain_resultset_timings.dita M src/ref/rrefsysxplain_statements.dita With the OP_IDENTIFIER row in rrefsysxplain_resultsets.dita, I found that the list of types is not easy to find (it is only in the Derby source code in java/engine/org/apache/derby/impl/sql/execute/xplain/XPLAINUtil.java, as far as I can tell), and it is also pretty long – I'm guessing it's all the strings with an OP_ prefix, 39 in all. But since the output is likely to be fairly self-explanatory I don't think we need to list them. With the OP_DETAILS row in the same topic, I left off the part about the "Halloween" problem, which seemed like more detail than necessary – but I can put it back if you think it would be helpful. Thanks for your feedback!
        Hide
        Bryan Pendleton added a comment -

        Yes, I think it is better not to try to list the entire set of types, it's way too much detail.

        Your changes look great to me. +1

        Regarding the "Halloween problem", I think it's fine to take it out. If you're interested,
        here's a bit of background about the term: http://en.wikipedia.org/wiki/Halloween_Problem

        Show
        Bryan Pendleton added a comment - Yes, I think it is better not to try to list the entire set of types, it's way too much detail. Your changes look great to me. +1 Regarding the "Halloween problem", I think it's fine to take it out. If you're interested, here's a bit of background about the term: http://en.wikipedia.org/wiki/Halloween_Problem
        Hide
        Kim Haase added a comment -

        Thanks, Bryan, for the quick review. And for the info about the Halloween problem!

        Committed patch DERBY-5198.diff to documentation trunk at revision 1095463.
        Merged to 10.8 doc branch at revision 1095466.

        Show
        Kim Haase added a comment - Thanks, Bryan, for the quick review. And for the info about the Halloween problem! Committed patch DERBY-5198 .diff to documentation trunk at revision 1095463. Merged to 10.8 doc branch at revision 1095466.
        Hide
        Kim Haase added a comment -

        Changes appear in latest alpha docs.

        Show
        Kim Haase added a comment - Changes appear in latest alpha docs.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Kim Haase
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development