You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kim Haase (JIRA)" <ji...@apache.org> on 2011/04/19 16:25:05 UTC
[jira] [Created] (DERBY-5198) XPLAIN table documentation needs some
cleanup
XPLAIN table documentation needs some cleanup
---------------------------------------------
Key: DERBY-5198
URL: https://issues.apache.org/jira/browse/DERBY-5198
Project: Derby
Issue Type: Bug
Components: Documentation
Affects Versions: 10.7.1.1
Reporter: Kim Haase
Assignee: Kim Haase
Priority: Minor
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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5198) XPLAIN table documentation needs
some cleanup
Posted by "Bryan Pendleton (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13021887#comment-13021887 ]
Bryan Pendleton commented on DERBY-5198:
----------------------------------------
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.
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Resolved] (DERBY-5198) XPLAIN table documentation needs
some cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase resolved DERBY-5198.
------------------------------
Resolution: Fixed
Fix Version/s: 10.8.1.3
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.
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
> Fix For: 10.8.1.3
>
> Attachments: DERBY-5198.diff, DERBY-5198.stat, DERBY-5198.zip
>
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5198) XPLAIN table documentation needs some
cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5198:
-----------------------------
Attachment: DERBY-5198.zip
DERBY-5198.stat
DERBY-5198.diff
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!
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
> Attachments: DERBY-5198.diff, DERBY-5198.stat, DERBY-5198.zip
>
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5198) XPLAIN table documentation needs
some cleanup
Posted by "Bryan Pendleton (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13022156#comment-13022156 ]
Bryan Pendleton commented on DERBY-5198:
----------------------------------------
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
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
> Attachments: DERBY-5198.diff, DERBY-5198.stat, DERBY-5198.zip
>
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5198) XPLAIN table documentation needs
some cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13021606#comment-13021606 ]
Kim Haase commented on DERBY-5198:
----------------------------------
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?
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5198) XPLAIN table documentation needs some
cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5198:
-----------------------------
Fix Version/s: 10.9.0.0
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
> Fix For: 10.8.1.3, 10.9.0.0
>
> Attachments: DERBY-5198.diff, DERBY-5198.stat, DERBY-5198.zip
>
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Closed] (DERBY-5198) XPLAIN table documentation needs some
cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5198?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase closed DERBY-5198.
----------------------------
Changes appear in latest alpha docs.
> XPLAIN table documentation needs some cleanup
> ---------------------------------------------
>
> Key: DERBY-5198
> URL: https://issues.apache.org/jira/browse/DERBY-5198
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.7.1.1
> Reporter: Kim Haase
> Assignee: Kim Haase
> Priority: Minor
> Fix For: 10.8.1.3, 10.9.0.0
>
> Attachments: DERBY-5198.diff, DERBY-5198.stat, DERBY-5198.zip
>
>
> 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.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira