Derby
  1. Derby
  2. DERBY-5083

Document automatic update and creation of index cardinality statistics (istat)

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.8.1.2
    • Fix Version/s: 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Documentation is needed for the automatic index statistics feature (DERBY-4934). It appears that a change is needed to the Tuning Guide topic "When cardinality statistics are automatically updated", at least.

      1. DERBY-5083.zip
        16 kB
        Kim Haase
      2. DERBY-5083.stat
        0.2 kB
        Kim Haase
      3. DERBY-5083.diff
        14 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Fix version added.

          Show
          Kim Haase added a comment - Fix version added.
          Hide
          Kim Haase added a comment -

          Reopening to add fix version.

          Show
          Kim Haase added a comment - Reopening to add fix version.
          Hide
          Kim Haase added a comment -

          Changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Changes have appeared in Latest Alpha Manuals.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5083.diff to documentation trunk at revision 1307409.

          Show
          Kim Haase added a comment - Committed patch DERBY-5083 .diff to documentation trunk at revision 1307409.
          Hide
          Kim Haase added a comment -

          Thanks, Kristian! Hard to believe these are okay on the first try – the information you provided was very helpful. I'll commit; feel free to reopen if corrections are needed.

          Show
          Kim Haase added a comment - Thanks, Kristian! Hard to believe these are okay on the first try – the information you provided was very helpful. I'll commit; feel free to reopen if corrections are needed.
          Hide
          Kristian Waagan added a comment -

          Thanks, Kim.

          There is an inconsistency regarding the value of indexStats.trace for not tracing anything. The source mentions both "none" and "off", but the latter seems to be the dominant one. I corrected the comment in revision 1307392, and I also removed two TODOs.

          Tracing and logging is completely separate, yes.

          The changes look good to me, +1 to commit.
          There is one trick that may be useful in rare cases, since the properties are static, and that is to generate a stack trace and look for the daemon thread to determine if the daemon is active or not. I don't think it belongs in the docs - hopefully people will find this comment instead

          Show
          Kristian Waagan added a comment - Thanks, Kim. There is an inconsistency regarding the value of indexStats.trace for not tracing anything. The source mentions both "none" and "off", but the latter seems to be the dominant one. I corrected the comment in revision 1307392, and I also removed two TODOs. Tracing and logging is completely separate, yes. The changes look good to me, +1 to commit. There is one trick that may be useful in rare cases, since the properties are static, and that is to generate a stack trace and look for the daemon thread to determine if the daemon is active or not. I don't think it belongs in the docs - hopefully people will find this comment instead
          Hide
          Kim Haase added a comment -

          Any remaining questions can be answered as part of a review, so here is a preliminary draft of the changes, in DERBY-5083.diff, DERBY-5083.stat, and DERBY-5083.zip.

          M src/tuning/ctunstats57373.dita
          A src/ref/rrefproperindexstatsauto.dita
          A src/ref/rrefproperindexstatslog.dita
          A src/ref/rrefproperindexstatstrace.dita
          M src/ref/crefproper22250.dita
          M src/ref/refderby.ditamap

          Please let me know what changes are needed. Thanks very much!

          Show
          Kim Haase added a comment - Any remaining questions can be answered as part of a review, so here is a preliminary draft of the changes, in DERBY-5083 .diff, DERBY-5083 .stat, and DERBY-5083 .zip. M src/tuning/ctunstats57373.dita A src/ref/rrefproperindexstatsauto.dita A src/ref/rrefproperindexstatslog.dita A src/ref/rrefproperindexstatstrace.dita M src/ref/crefproper22250.dita M src/ref/refderby.ditamap Please let me know what changes are needed. Thanks very much!
          Hide
          Kim Haase added a comment -

          Thanks, Kristian, for the info about the properties.

          I was looking in java/engine/org/apache/derby/impl/sql/catalog/DataDictionaryImpl.java, and it suggests that the default for derby.storage.indexStats.trace is "off" rather than "none" – is that correct? It also has a comment saying "// TODO: This property may go away in production code." I gather that has not happened.

          Also, are tracing and logging completely separate? That is, can you set derby.storage.indexStats.trace if derby.storage.indexStats.log is not set to true? The code implies that you can, but I thought I'd better check.

          Show
          Kim Haase added a comment - Thanks, Kristian, for the info about the properties. I was looking in java/engine/org/apache/derby/impl/sql/catalog/DataDictionaryImpl.java, and it suggests that the default for derby.storage.indexStats.trace is "off" rather than "none" – is that correct? It also has a comment saying "// TODO: This property may go away in production code." I gather that has not happened. Also, are tracing and logging completely separate? That is, can you set derby.storage.indexStats.trace if derby.storage.indexStats.log is not set to true? The code implies that you can, but I thought I'd better check.
          Hide
          Kristian Waagan added a comment - - edited

          The properties can be set on both the system-wide and database level (the latter overriding the former).

          The properties are static.

          I believe derby.storage.indexStats.trace should be exposed - it provides valuable information when you have to debug problems with the feature. Take care of the valid values for the trace property: "none" (the default), "stdout", "log", "both".

          Show
          Kristian Waagan added a comment - - edited The properties can be set on both the system-wide and database level (the latter overriding the former). The properties are static. I believe derby.storage.indexStats.trace should be exposed - it provides valuable information when you have to debug problems with the feature. Take care of the valid values for the trace property: "none" (the default), "stdout", "log", "both".
          Hide
          Kim Haase added a comment -

          It's time to work on this at last, I believe. A couple of quick questions:

          From the release note for Derby 10.8, it appears that the properties derby.storage.indexStats.auto and derby.storage.indexStats.log are database properties only and cannot be set at the system-wide level – is that true?

          Also, are these properties dynamic?

          The release notes did not mention derby.storage.indexStats.trace, so I gather we chose not to expose that property?

          Thanks!

          Show
          Kim Haase added a comment - It's time to work on this at last, I believe. A couple of quick questions: From the release note for Derby 10.8, it appears that the properties derby.storage.indexStats.auto and derby.storage.indexStats.log are database properties only and cannot be set at the system-wide level – is that true? Also, are these properties dynamic? The release notes did not mention derby.storage.indexStats.trace, so I gather we chose not to expose that property? Thanks!
          Hide
          Kim Haase added a comment -

          10.9 would be a good time to document the two properties listed in the 10.8 release notes:

          derby.storage.indexStats.auto
          derby.storage.indexStats.log

          It's now time to update the Tuning Derby topic "When cardinality statistics are automatically updated" and correct any other outdated information in this manual.

          If any users see the need for further documentation of this feature, please feel free to comment further on this issue.

          Show
          Kim Haase added a comment - 10.9 would be a good time to document the two properties listed in the 10.8 release notes: derby.storage.indexStats.auto derby.storage.indexStats.log It's now time to update the Tuning Derby topic "When cardinality statistics are automatically updated" and correct any other outdated information in this manual. If any users see the need for further documentation of this feature, please feel free to comment further on this issue.
          Hide
          Kim Haase added a comment -

          For the time being, we are keeping the documentation of this feature in the release notes for 10.8. We'll keep this issue as a placeholder for the future.

          Show
          Kim Haase added a comment - For the time being, we are keeping the documentation of this feature in the release notes for 10.8. We'll keep this issue as a placeholder for the future.

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development