Derby
  1. Derby
  2. DERBY-1160

Document use of SPACE_TABLE to tell for tables and indexes: a) the number of pages allocated b) the number of empty pages

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Very active systems would benefit from a documented way to determine how many empty pages are allocated to an index or table in order to determine whether a COMPRESS_TABLE is worth running.

      1. docs.diff
        1 kB
        Bryan Pendleton
      2. cadminspace21579.html
        7 kB
        Bryan Pendleton
      3. docs2.diff
        5 kB
        Bryan Pendleton
      4. rrefsyscsdiagtables.html
        22 kB
        Bryan Pendleton

        Activity

        Hide
        Bryan Pendleton added a comment -

        Once such a technique is made available, here would be a good place in the documentation to describe it:
        http://db.apache.org/derby/docs/10.1/adminguide/cadminspace21579.html

        Show
        Bryan Pendleton added a comment - Once such a technique is made available, here would be a good place in the documentation to describe it: http://db.apache.org/derby/docs/10.1/adminguide/cadminspace21579.html
        Hide
        Bryan Pendleton added a comment -

        I took a closer look at the output from SYSCS_DIAG.SPACE_TABLE, and I think it already
        includes this information. See the references to NUMFREEPAGES and ESTIMSPACESAVING
        in the description at
        http://db.apache.org/derby/javadoc/engine/org/apache/derby/diag/SpaceTable.html

        I tried running SYSCS_DIAG.SPACE_TABLE on a few sample tables, and it looks like
        the output in these columns is legitimate.

        So perhaps all that is needed here is to update the documentation for the compress
        table discussion (http://db.apache.org/derby/docs/10.5/adminguide/cadminspace21579.html)
        to provide some text suggesting that SPACE_TABLE can be used to estimate whether
        a COMPRESS_TABLE is worth running?

        Show
        Bryan Pendleton added a comment - I took a closer look at the output from SYSCS_DIAG.SPACE_TABLE, and I think it already includes this information. See the references to NUMFREEPAGES and ESTIMSPACESAVING in the description at http://db.apache.org/derby/javadoc/engine/org/apache/derby/diag/SpaceTable.html I tried running SYSCS_DIAG.SPACE_TABLE on a few sample tables, and it looks like the output in these columns is legitimate. So perhaps all that is needed here is to update the documentation for the compress table discussion ( http://db.apache.org/derby/docs/10.5/adminguide/cadminspace21579.html ) to provide some text suggesting that SPACE_TABLE can be used to estimate whether a COMPRESS_TABLE is worth running?
        Hide
        Knut Anders Hatlen added a comment -

        Sounds like a good way to resolve this issue. I agree that NUMFREEPAGES and ESTIMSPACESAVING give the information requested by the reporter.

        Show
        Knut Anders Hatlen added a comment - Sounds like a good way to resolve this issue. I agree that NUMFREEPAGES and ESTIMSPACESAVING give the information requested by the reporter.
        Hide
        Bryan Pendleton added a comment -

        Reclassified as a documentation issue.

        Show
        Bryan Pendleton added a comment - Reclassified as a documentation issue.
        Hide
        Bryan Pendleton added a comment -

        I'm uncertain about whether the pages in the doc set should contain direct references to the internal javadoc, so for now I simply added some text to the admin guide page showing how to use SPACE_TABLE to estimate the space
        that could be reclaimed.

        Is it reasonable for the doc pages to contain a direct XREF to
        http://db.apache.org/derby/javadoc/engine/org/apache/derby/diag/SpaceTable.html ?

        Show
        Bryan Pendleton added a comment - I'm uncertain about whether the pages in the doc set should contain direct references to the internal javadoc, so for now I simply added some text to the admin guide page showing how to use SPACE_TABLE to estimate the space that could be reclaimed. Is it reasonable for the doc pages to contain a direct XREF to http://db.apache.org/derby/javadoc/engine/org/apache/derby/diag/SpaceTable.html ?
        Hide
        Knut Anders Hatlen added a comment -

        I think it would be best not to have links to the javadoc because the URL may change and the content is not stable (the URL points to the development sources which may not match the version documented by the manual). It would be good, though, to capture the information from the javadoc in the reference manual. As far as I can see, only the javadoc documents the columns in the space table.

        Show
        Knut Anders Hatlen added a comment - I think it would be best not to have links to the javadoc because the URL may change and the content is not stable (the URL points to the development sources which may not match the version documented by the manual). It would be good, though, to capture the information from the javadoc in the reference manual. As far as I can see, only the javadoc documents the columns in the space table.
        Hide
        Knut Anders Hatlen added a comment -

        The patch looks good to me. I'm not sure if the codeblock section is supposed to be inside the p section, or if there should be a closing tag </p> right before the codeblock section, and an opening <p> rigth after it. The other occurrences of codeblock sections in that file do terminate the p section before starting the codeblock section.

        Show
        Knut Anders Hatlen added a comment - The patch looks good to me. I'm not sure if the codeblock section is supposed to be inside the p section, or if there should be a closing tag </p> right before the codeblock section, and an opening <p> rigth after it. The other occurrences of codeblock sections in that file do terminate the p section before starting the codeblock section.
        Hide
        Kim Haase added a comment -

        A codeblock can be either inside a paragraph or outside. So this is fine unless you feel the need to be totally consistent. Thanks, Bryan!

        Show
        Kim Haase added a comment - A codeblock can be either inside a paragraph or outside. So this is fine unless you feel the need to be totally consistent. Thanks, Bryan!
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim and Knut.

        I like the suggestion to include the column descriptions into the
        main documentation, as it seems very useful for users of the
        SYSCS_DIAG.SPACE_TABLE funtion. I think that information goes
        nicely into the SYSCS_DIAG page in the Reference guide, so attached
        is a second version of the patch, and an updated version of the ref
        guide page in HTML.

        Show
        Bryan Pendleton added a comment - Thanks Kim and Knut. I like the suggestion to include the column descriptions into the main documentation, as it seems very useful for users of the SYSCS_DIAG.SPACE_TABLE funtion. I think that information goes nicely into the SYSCS_DIAG page in the Reference guide, so attached is a second version of the patch, and an updated version of the ref guide page in HTML.
        Hide
        Kim Haase added a comment -

        The added table looks great from the docs perspective.

        Show
        Kim Haase added a comment - The added table looks great from the docs perspective.
        Hide
        Bryan Pendleton added a comment -

        Committed to the documentation trunk as revision 887826.

        Show
        Bryan Pendleton added a comment - Committed to the documentation trunk as revision 887826.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Stan Bradbury
          • Votes:
            1 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development