db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-3072) User documentation for Table Functions
Date Wed, 19 Sep 2007 16:30:12 GMT

    [ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12528810

Kim Haase commented on DERBY-3072:

This is great work, Rick -- you've structured the new topics very well, and they are clear
and well written. The tuning topics are amazingly clear for such complex material. Here are
some suggestions for improvement. Any topic with no comments is just fine.

Global nit: According to the rules about restrictive and nonrestrictive clauses as I learned
them, "which" should be "that" in every location where it is used in these topics. (Briefly,
if the sentence would be meaningless without the clause, use "that"; if the clause adds nonessential
information, use "which" and set it off with commas.)

Tuning Guide comments:

I think you may need to change one more file, the parent file of the new performance tips
file. The parent file is "The tips," ctunperf25864.dita. It contains a manually created list
of subtopics, with additional verbiage, in addition to the autogenerated list at the bottom.
So you'd need to add your new topic there.


I'm wondering about "to cost" as a verb, from the point of view of translation. Maybe "how
to cost a ..." could be "how to calculate the cost of a ..." You could also make the index
terms similar to the ones for cdevspecialtfopttune.dita.

I think we try to talk about topics rather than sections, but to avoid the whole issue you
could just say 

See "Programming Derby-style table functions" in the Derby Developer's Guide.

Developer's Guide comments:


Paragraph 1: In the second sentence, "These" lacks a referent; when you are introducing a
topic it helps to be crystal clear. (This rule doesn't matter much, since the meaning is clear
regardless; it's just an FYI.) In the third sentence, "xml" should be "XML". So I'd suggest
the following:

Derby lets you create table functions. Table functions are functions that package up external
data to look like Derby tables. The external data can be an XML file, a table in a foreign
database, a live data feed--in short, any information source that can be presented as a JDBC

Paragraph 2: It seems awkward to have a clause in between "the following data sources" and
the list of the data sources. It might be clearer to swap them and use a sub-bullet list,
like this:

For example, Derby-style table functions let you do the following:

  * Perform a bulk import of foreign data into local Derby tables
  * Join Derby tables with any of the following data sources:
    * XML-formatted reports and logs
    * Queries that have been run in foreign databases
    * Streaming data from sensors
    * RSS feeds

(I don't know that "bulk import" is a well-known verb -- in the Tools guide, it is a noun;
list items that aren't sentences shouldn't end with periods; "XML" again; and "run" can be
either a participle or a verb, so it should be disambiguated.)

Paragraph 3: The following might be clearer:

See "CREATE FUNCTION statement" in the Derby Reference Manual for the complete syntax needed
to declare Derby-style table functions. The following topics provide information on how to
write Java methods that wrap foreign data sources inside ResultSets.


Paragraph 2: Do you think "may be stubbed out and simply raise exceptions" will be completely
clear even to non-native speakers of English? I'm wondering if the following (or something
similar) would be clearer:

Most of the ResultSet methods can be written as stubs that do nothing but throw exceptions.

4th bullet: It's not clear what the XXX in getXXX means until you look at the linked-to topic.
Would it be helpful to say the following?

...Derby calls a getXXX() method on each referenced column, where XXX is the column's data

In the example, you might line up the table data types vertically if you can.

Elsewhere we say "FROM list" instead of "from-list"; also, the passive verbs in this sentence
make it rather convoluted, so how about the following?

To invoke the table function, wrap it with [in??] a TABLE constructor in the FROM list of
a query.


I think "data type" is the more common form. Also, in text you'd want to put "getXXX()" in
italics as you do in the parent topic. And in the second sentence, add "method":

While scanning a Derby-style table function, Derby calls a preferred getXXX() method for each
column, based on the column's data type.

The following table lists the preferred getXXX() method for each Derby data type.


The first sentence is not very substantive. It might be more economical to have just one sentence
saying something like

The following simple table function selects rows from a foreign database.


Paragraph 1: I think we usually say "topic" rather than "section".

Bullet item 1: From the point of view of the translator or non-native speaker of English,
"inclines" may be a somewhat unusual word. How about 

Therefore, the optimizer is likely to place ...

Bullet item 2: Participial and gerund phrases (such as "Knowing ...") are often ambiguous.
How about 

If it knows that a table function is repeatable, the optimizer can place ...

I'm not sure about "siphoning" -- is "putting" incorrect or too boring?

Bullet item 1 (new bullet list): You might spell out "no-argument".

Bullet item 2: Are there javadocs for the VTICosting interface? I'm not sure they would be
available in the commonest (bin) distribution of Derby, since that has only the JDBC javadocs
as far as I know. If they are reachable somewhere, you might provide a pointer. I think you've
done a great job providing all the information people need, though.

It might be helpful to add xref links in the second sentence as follows:

This involves implementing the following methods, as described in Measuring the cost of Derby-style
table functions and Example VTICosting implementation:

Even though the generated HTML includes links to those subtopics at the end of this topic,
it would still be reassuring to clarify that the needed info is available there.

In the three sub-bullets, you might want to change "This" to "This method".

First sub-bullet: I don't see any mention of STARTUP and SCAN in the two subtopics. What is
the relationship between these terms and the values mentioned in "Measuring the cost of Derby-style
table functions"? The value returned by getEstimatedCostPerInstantiation() doesn't look like
a sum of two values to me, so I'm a bit confused.


You might want to create some sections within this topic, because right now the transitions
from one part to another are not entirely clear. For example, you might put the part beginning
"We treat optimizer Imprecision as a constant ..." in a section called "Calculating the optimizer's
Imprecision", and you might put the part beginning "The following formula explains how to
compute the Actual runtime cost ..." in a section called "Calculating the Actual run time
for the table function". Finally. you might put the part beginning "Putting all of this together
..." in a section called "Computing the value returned by getEstimatedCostPerInstantiation()".

"Short-circuit" bullet: Would it be helpful to give an example of how to do this? Would all
of your audience know? Also, I think "next()" should be in italics. And "table function" is
not capitalized elsewhere in this topic, so should it be capitalized here?

"Record" bullet" (two occurrences): Should VTIResultSet be in italics?

At the end, since you've broken down the A value, wouldn't it be consistent to break down
the I value too? That would make the formula

C = O/T * [ ( P * N ) + E ]


Paragraph 1: Again, saying that something is easy is not very substantive (and may not have
the reassuring effect that was probably intended). Maybe something like

Once you have measured your table function's cost, you can write the VTICosting methods.

Reference Manual comments:


In the TableType section, again, you might want to cut "the section on" and just say 

For more information, see "Programming Derby-style table functions" in the Derby Developer's

In the third paragraph of the ParameterStyle section, I don't think DERBY_JDBC_RESULT_SET
and JAVA need to be in italics here.


I assume you made a deliberate decision to place this new topic as a subtopic of "TableViewOrFunctionExpression"
rather than to move it up to the "SQL identifiers" topic, where all the other xrefs in the
syntax statement can be found (table-Name, view-Name, etc.). If the parent topic will always
be the only topic that refers to this topic, that makes sense, I guess. However, I believe
this is a deeper level of topic nesting than occurs anywhere else in this manual.

DITA note: I believe an example element can contain paragraphs, so you don't have to structure
the topic example/section/example; it can be all one example with a paragraph in the middle.
Unimportant, though; doesn't affect the look of the output.

> User documentation for Table Functions
> --------------------------------------
>                 Key: DERBY-3072
>                 URL: https://issues.apache.org/jira/browse/DERBY-3072
>             Project: Derby
>          Issue Type: New Feature
>          Components: Documentation
>            Reporter: Rick Hillegas
>            Assignee: Rick Hillegas
>         Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
> This issue tracks changes to the user guides to describe table functions. This is the
work needed for the  "Documentation" section of the functional spec attached to DERBY-716.

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message