db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r578086 - in /db/derby/docs/trunk/src: devguide/ ref/ tuning/
Date Fri, 21 Sep 2007 12:54:04 GMT
Author: rhillegas
Date: Fri Sep 21 05:54:03 2007
New Revision: 578086

URL: http://svn.apache.org/viewvc?rev=578086&view=rev
Log:
DERBY-3072: User documentation for Derby-style table functions, incorporating Kim's feedback.

Added:
    db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita   (with props)
    db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita   (with props)
Modified:
    db/derby/docs/trunk/src/devguide/cdevspecial.dita
    db/derby/docs/trunk/src/devguide/derbydev.ditamap
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
    db/derby/docs/trunk/src/ref/rrefsqlj33215.dita
    db/derby/docs/trunk/src/ref/rreftableexpression.dita
    db/derby/docs/trunk/src/tuning/ctunperf25864.dita
    db/derby/docs/trunk/src/tuning/tuningderby.ditamap

Modified: db/derby/docs/trunk/src/devguide/cdevspecial.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecial.dita?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecial.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevspecial.dita Fri Sep 21 05:54:03 2007
@@ -21,7 +21,7 @@
 <title>Derby server-side programming</title>
 <shortdesc>This section discusses special programming for <ph conref="../conrefs.dita#prod/productshortname"></ph>.</shortdesc>
 <conbody>
-<p>These features include such programming as database-side JDBC procedures
-and triggers.</p>
+<p>In particular, this section discusses how to program database-side JDBC procedures,
+triggers, and table functions.</p>
 </conbody>
 </concept>

Added: db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtabfuncs" xml:lang="en-us">
+<title>Programming Derby-style table functions</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> lets
+you create table functions. Table functions are functions which 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 <i>ResultSet</i>.
+</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>programming table functions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>Derby-style table functions let you efficiently import foreign data into Derby tables.
+Table functions let you join Derby tables with any of
+the following data sources:
+</p>
+<ul>
+<li>XML-formatted reports and logs</li>
+<li>Queries that run in foreign databases</li>
+<li>Streaming data from sensors</li>
+<li>RSS feeds</li>
+</ul>
+<p>See "CREATE FUNCTION statement" in the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for
+the complete syntax needed to declare Derby-style table functions.
+The following topics
+provide information on how to write Java methods which wrap
+foreign data sources inside <i>ResultSet</i>s.</p>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtabfuncs.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfbasic" xml:lang="en-us">
+<title>Overview of Derby-style table functions</title>
+<shortdesc>A Derby-style table function is a method which returns a JDBC <i>ResultSet</i>.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>table function overview</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>Most of the <i>ResultSet</i> methods can be
+written as stubs which simply raise exceptions. However, the Derby-style table function
+must implement the following <i>ResultSet</i> methods:</p>
+<ul>
+<li><i>next()</i></li>
+<li><i>close()</i></li>
+<li><i>wasNull()</i></li>
+<li><i>getXXX()</i> - When invoking a Derby-style table function at runtime, Derby calls a <i>getXXX()</i>
+        method on each referenced column. The particular <i>getXXX()</i>
+        method is based on the column's data type
+        as declared in the <codeph>CREATE FUNCTION</codeph> statement.
+<xref href="cdevspecialtfgetxxx.dita#cdevspecialtfgetxxx"></xref>
+explains how Derby selects an appropriate <i>getXXX()</i> method.
+However, nothing prevents application code from calling other <i>getXXX()</i>
+        methods on the <i>ResultSet</i>. The returned <i>ResultSet</i>
+needs to implement the <i>getXXX()</i> methods which Derby will call as well
+        as all <i>getXXX()</i> methods which the application will call.
+</li>
+</ul>
+
+<p>
+A Derby-style table function is materialized by a public static method which returns a <i>ResultSet</i>:
+</p>
+
+<codeblock>
+public static ResultSet read() {...}
+</codeblock>
+
+<p>
+The public static method is then bound to a Derby function name:
+</p>
+
+<codeblock>
+CREATE FUNCTION externalEmployees
+()
+RETURNS TABLE
+(
+  employeeId    INT,
+  lastName      VARCHAR( 50 ),
+  firstName     VARCHAR( 50 ),
+  birthday      DATE
+)
+LANGUAGE JAVA
+PARAMETER STYLE DERBY_JDBC_RESULT_SET
+NO SQL
+EXTERNAL NAME 'com.acme.hrSchema.EmployeesTable.read'
+</codeblock>
+
+<p>
+To invoke a table function, wrap it in a TABLE constructor in the FROM list of a query.
+Note that the table alias (in this example "s") is a required part of the syntax:
+</p>
+
+<codeblock>
+INSERT INTO employees
+  SELECT s.*
+    FROM TABLE (externalEmployees() ) s;
+</codeblock>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfbasic.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfexample" xml:lang="en-us">
+<title>Example Derby-style table function</title>
+<shortdesc>The following simple table function selects rows from a foreign database.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>table function example</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+
+<codeblock>
+package com.acme.hrSchema;
+
+import java.sql.*;
+
+/**
+ * Sample Table Function for reading the employee table in an
+ * external database.
+ */
+public class EmployeeTable
+{
+    public  static  ResultSet   read()
+        throws SQLException
+    {
+        Connection          conn = getConnection();
+        PreparedStatement   ps = conn.prepareStatement( "select * from hrSchema.EmployeeTable" );
+
+        return ps.executeQuery();
+    }
+
+    protected  static  Connection    getConnection()
+        throws SQLException
+    {
+        String  EXTERNAL_DRIVER = "com.mysql.jdbc.Driver";
+
+        try { Class.forName( EXTERNAL_DRIVER ); }
+        catch (ClassNotFoundException e) { throw new SQLException( "Could not find class " + EXTERNAL_DRIVER ); }
+
+        Connection          conn = DriverManager.getConnection
+            ( "jdbc:mysql://localhost/hr?user=root&amp;password=mysql-passwd" );
+
+        return conn;
+    }
+}
+</codeblock>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfexample.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfgetxxx" xml:lang="en-us">
+<title>Preferred <i>getXXX()</i> methods for Derby-style table functions</title>
+<shortdesc>While scanning a Derby-style table function, Derby
+calls a preferred <i>getXXX()</i> method for each column, based on the
+column's data type.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>table function getXXX() methods</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>The following table lists the preferred <i>getXXX()</i> method for each Derby data type.</p>
+
+<table id="cdevspecialtftab1" rowheader="firstcol">
+
+<title>
+<b><i>getXXX()</i> Methods Called for Declared SQL Types</b>
+</title>
+
+<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="60*"/>
+<colspec colname="2" colnum="2" colwidth="40*"/>
+
+<thead>
+<row>
+<entry align="left" colname="1" valign="bottom">Column Type Declared by CREATE FUNCTION</entry>
+<entry align="left" colname="2" valign="bottom"><i>getXXX()</i> Method Called by Derby</entry>
+</row>
+</thead>
+
+
+<tbody>
+
+<row>
+<entry colname="1">BIGINT</entry>
+<entry colname="2" ><i>getLong()</i></entry>
+</row>
+
+<row>
+<entry colname="1">BLOB</entry>
+<entry colname="2"><i>getBlob()</i></entry>
+</row>
+
+<row>
+<entry colname="1">CHAR</entry>
+<entry colname="2"><i>getString()</i></entry>
+</row>
+
+<row>
+<entry colname="1">CHAR FOR BIT DATA</entry>
+<entry colname="2"><i>getBytes()</i></entry>
+</row>
+
+<row>
+<entry colname="1">CLOB</entry>
+<entry colname="2"><i>getClob()</i></entry>
+</row>
+
+<row>
+<entry colname="1">DATE</entry>
+<entry colname="2"><i>getDate()</i></entry>
+</row>
+
+<row>
+<entry colname="1">DECIMAL</entry>
+<entry colname="2"><i>getBigDecimal()</i></entry>
+</row>
+
+<row>
+<entry colname="1">DOUBLE</entry>
+<entry colname="2"><i>getDouble()</i></entry>
+</row>
+
+<row>
+<entry colname="1">DOUBLE PRECISION</entry>
+<entry colname="2"><i>getDouble()</i></entry>
+</row>
+
+<row>
+<entry colname="1">FLOAT</entry>
+<entry colname="2"><i>getDouble()</i></entry>
+</row>
+
+<row>
+<entry colname="1">INTEGER</entry>
+<entry colname="2"><i>getInt()</i></entry>
+</row>
+
+<row>
+<entry colname="1">LONG VARCHAR</entry>
+<entry colname="2"><i>getString()</i></entry>
+</row>
+
+<row>
+<entry colname="1">LONG VARCHAR FOR BIT DATA</entry>
+<entry colname="2"><i>getBytes()</i></entry>
+</row>
+
+<row>
+<entry colname="1">NUMERIC</entry>
+<entry colname="2"><i>getBigDecimal()</i></entry>
+</row>
+
+<row>
+<entry colname="1">REAL</entry>
+<entry colname="2"><i>getFloat()</i></entry>
+</row>
+
+<row>
+<entry colname="1">SMALLINT</entry>
+<entry colname="2"><i>getShort()</i></entry>
+</row>
+
+<row>
+<entry colname="1">TIME</entry>
+<entry colname="2"><i>getTime()</i></entry>
+</row>
+
+<row>
+<entry colname="1">TIMESTAMP</entry>
+<entry colname="2"><i>getTimestamp()</i></entry>
+</row>
+
+<row>
+<entry colname="1">VARCHAR</entry>
+<entry colname="2"><i>getString()</i></entry>
+</row>
+
+<row>
+<entry colname="1">VARCHAR FOR BIT DATA</entry>
+<entry colname="2"><i>getBytes()</i></entry>
+</row>
+
+<row>
+<entry colname="1">XML</entry>
+<entry colname="2"><b>Not supported.</b></entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfgetxxx.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfoptexample" xml:lang="en-us">
+<title>Example VTICosting implementation</title>
+<shortdesc>Once you have measured your table function's cost, you can write
+the <i>VTICosting</i> methods.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>VTICosting example</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+
+<p>Optimizer fine-tuning can be added to the <i>EmployeeTable</i>
+table function shown before in
+<xref href="cdevspecialtfexample.dita#cdevspecialtfexample"></xref>:
+</p>
+
+<codeblock>
+package com.acme.hrSchema;
+
+import java.io.Serializable;
+import java.sql.*;
+
+import org.apache.derby.vti.VTICosting;
+import org.apache.derby.vti.VTIEnvironment;
+
+/**
+ * Tuned table function.
+ */
+public class TunedEmployeeTable extends EmployeeTable implements VTICosting
+{
+    public TunedEmployeeTable() {}
+
+    public double getEstimatedRowCount( VTIEnvironment optimizerState ) throws SQLException
+    {
+        return getRowCount( optimizerState );
+    }
+
+    public double getEstimatedCostPerInstantiation( VTIEnvironment optimizerState ) throws SQLException
+    {
+        double      I = 100.0;  // optimizer imprecision
+        double      P = 10.0;   // cost per row in milliseconds
+        double      E = 0.0;    // cost of instantiating the external ResultSet
+        double      N = getRowCount( optimizerState );
+
+        return I * ( ( P * N ) + E );
+    }
+    
+    public boolean supportsMultipleInstantiations( VTIEnvironment optimizerState ) throws SQLException
+    {
+        return true;
+    }
+
+    //////////////////////////////////////////////////////////////////////////////
+
+    private double  getRowCount( VTIEnvironment optimizerState )
+        throws SQLException
+    {
+        String            ROW_COUNT_KEY = "rowCountKey";
+        Double          estimatedRowCount = (Double) getSharedState( optimizerState, ROW_COUNT_KEY );
+        
+        if ( estimatedRowCount == null )
+        {
+            Connection                  conn = getConnection();
+            PreparedStatement       ps = conn.prepareStatement( "select count(*) from hrSchema.EmployeeTable" );
+            ResultSet                      rs = ps.executeQuery();
+
+            rs.next();
+            estimatedRowCount = new Double( rs.getDouble( 1 ) );
+            
+            setSharedState( optimizerState, ROW_COUNT_KEY, estimatedRowCount );
+
+            rs.close();
+            ps.close();
+            conn.close();
+        }
+
+        return estimatedRowCount.doubleValue();
+    }
+
+    private Serializable  getSharedState( VTIEnvironment optimizerState, String key )
+    { return (Serializable) optimizerState.getSharedState( key ); }
+    private void    setSharedState( VTIEnvironment optimizerState, String key, Serializable value )
+    { optimizerState.setSharedState( key, value ); }
+}
+</codeblock>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfoptexample.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfoptimizer" xml:lang="en-us">
+<title>Optimizer support for Derby-style table functions</title>
+<shortdesc>This topic explains how to fine-tune the Derby
+optimizer's decision about where to place a table function in the
+join order.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>costing table functions</indexterm></indexterm>
+<indexterm>Optimizer<indexterm>costing table functions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+
+<p>
+By default, the Derby optimizer makes the following assumptions about
+a table function:
+</p>
+
+<ul>
+<li><b>Expensive</b> - It is expensive to create and loop through the
+        rows of the table function. This makes it likely that the optimizer will
+      place the table function in an outer slot of the join
+        order so that it will not be looped through often.</li>
+<li><b>Repeatable</b> - The table function can be instantiated
+        multiple times with the same results. This is probably true
+        for most table functions. However, some
+table functions may open read-once streams. If the optimizer knows that a
+        table function is repeatable, then the optimizer can place
+        the table function in an inner slot where the function can be
+        invoked multiple times. If a table function is not
+        repeatable, then the optimizer must either place it in the
+        outermost slot or invoke the function once and store its contents in
+        a temporary table.</li>
+</ul>
+
+<p>
+The user can override this optimizer behavior by giving the optimizer
+      more information. Here's how to do this:
+</p>
+
+<ul>
+<li><b>No-arg constructor</b> - The table function's class
+        must have a public constructor whose signature has no arguments.</li>
+<li><b>VTICosting</b> - The class must also implement
+<i>org.apache.derby.vti.VTICosting</i>. This involves
+implementing the following methods as described in
+<xref href="cdevspecialtfopttune.dita#cdevspecialtfopttune">Measuring the cost of Derby-style table functions</xref>
+and
+<xref href="cdevspecialtfoptexample.dita#cdevspecialtfoptexample">Example VTICosting implementation</xref>:
+  <ul>
+  <li><i>getEstimatedCostPerInstantiation()</i> - This method estimates the
+            cost of invoking the table function and looping
+            through its rows. The returned value adds together
+            two estimates:
+    <ul>
+    <li>Empty table - This is the cost of invoking the
+    table function, even if it contains 0 rows. See the description of variable <b>E</b>
+    in <xref href="cdevspecialtfopttune.dita#cdevspecialtfopttune">Measuring the cost of Derby-style table functions</xref>.</li>
+    <li>Scanning - This is the cost of looping through all of the
+    rows returned by the table function. See the calculation of <b>P*N</b>
+    in <xref href="cdevspecialtfopttune.dita#cdevspecialtfopttune">Measuring the cost of Derby-style table functions</xref>.</li>
+    </ul>
+  </li>
+  <li><i>getEstimatedRowCount()</i> - This guesses the number of rows
+            returned by invoking the table function.</li>
+  <li><i>supportsMultipleInstantiations()</i> - This returns false if
+            the table function
+returns different results when invoked more than once.
+  </li>
+  </ul>
+</li>
+</ul>
+
+<p>
+For more information, see:
+</p>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfoptimizer.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevspecialtfopttune" xml:lang="en-us">
+<title>Measuring the cost of Derby-style table functions</title>
+<shortdesc>This topic shows how to measure the cost of a Derby-style
+table function.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>calculating table function costs</indexterm></indexterm>
+<indexterm>Optimizer<indexterm>calculating table function costs</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+
+<p>
+The following formula describes how to estimate the value returned
+by  <i>VTICosting.getEstimatedCostPerInstantiation()</i>:
+</p>
+
+<p><b>
+C = I * A
+</b></p>
+
+<p>where</p>
+
+<ul>
+<li><b>C</b> = The estimated <b>C</b>ost for creating and running the
+        table function. That is, the value returned by
+<i>VTICosting.getEstimatedCostPerInstantiation()</i>.
+        In general, <b>C</b>ost is a measure of time in milliseconds.</li>
+<li><b>I</b> = The  optimizer's <b>I</b>mprecision. A measure of how skewed the optimizer's estimates tend
+        to be in your particular environment. See below for instructions on how to estimate this <b>I</b>mprecision.</li>
+<li><b>A</b> = The <b>A</b>ctual time in milliseconds which it takes
+        to create and run this table function.</li>
+</ul>
+
+<section> <title>Calculating the optimizer's imprecision</title>
+
+<p>
+We treat optimizer <b>I</b>mprecision as a constant across the
+        runtime environment. The following formula describes it:
+</p>
+
+<p><b>
+I = O / T
+</b></p>
+
+<p>where</p>
+
+<ul>
+<li><b>O</b> = The <b>O</b>ptimizer's estimated cost for a plan.</li>
+<li><b>T</b> = The <b>T</b>otal runtime in milliseconds for the plan.</li>
+</ul>
+
+<p>
+To estimate these values, turn on Derby statistics collection and run
+        the following experiment several times, averaging the results:
+</p>
+
+<ul>
+<li><b>Select</b> = Select all of the rows from a big table.</li>
+<li><b>Record</b> = In the statistics output, look for the ResultSet
+          which represents the table scan. That scan has a field
+          labelled "optimizer estimated cost". That's <b>O</b>. Now
+          look for the fields in that ResultSet's statistics labelled
+"constructor time", "open time", "next time", and "close time". Add up
+          all of those fields. That total is <b>T</b>.
+</li>
+</ul>
+
+<p>
+For example:
+</p>
+
+<codeblock>
+MAXIMUMDISPLAYWIDTH 7000;
+
+CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(1);
+CALL SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING(1);
+
+select * from T;
+
+values SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS();
+</codeblock>
+
+</section>
+
+<section> <title>Calculating the actual runtime cost of a table function</title>
+
+<p>
+The following formula explains how to compute the <b>A</b>ctual
+        runtime cost for the table function:
+</p>
+
+<p><b>
+A =  ( P * N ) + E
+</b></p>
+
+<p>where</p>
+
+<ul>
+<li><b>P</b> = The runtime spent <b>P</b>er row (in milliseconds).</li>
+<li><b>N</b> = The <b>N</b>umber of rows in the table function.</li>
+<li><b>E</b> = The time spent creating an <b>E</b>mpty instance of the
+          table function which has no rows in it. Usually, <b>P * N</b> dwarfs
+          <b>E</b>. That is, the table function instantiation cost is very
+          small compared to the actual cost of looping through the
+          rows. However, for some table functions, <b>E</b> may be significant
+          and may dominate the table function's cost when <b>N</b> is small.</li>
+</ul>
+
+<p>
+You may know that <b>E</b> is basically 0. If so, you can skip this step.
+Otherwise, to estimate <b>E</b>, turn on Derby statistics collection and run
+        the following experiment several times, averaging the results:
+</p>
+
+<ul>
+<li><b>Short-circuit</b> = Short-circuit the next() method of the
+<i>ResultSet</i>
+returned by your Derby-style Table Function so that it returns
+          <i>false</i> the first time it is called. This makes it
+          appear that the
+<i>ResultSet</i>
+has no rows.
+</li>
+<li><b>Select</b> = Select all of the rows from the table function.</li>
+<li><b>Record</b> = In the statistics output, look for the VTIResultSet
+          which represents the table function scan. Add up
+          the values of the fields in that VTIResultSet's statistics labelled
+"constructor time", "open time", "next time", and "close time".
+          That total is <b>E</b>.
+</li>
+</ul>
+
+<p>
+To estimate <b>P</b>, turn on Derby statistics collection and run
+        the following experiment several times, averaging the results:
+</p>
+
+<ul>
+<li><b>Select</b> = Select all of the rows from the table function.</li>
+<li><b>Record</b> = In the statistics output, look for the VTIResultSet
+          which represents the table function scan. Add up
+          the values of the fields in that VTIResultSet's statistics labelled
+"constructor time", "open time", "next time", and "close
+          time". Subtract <b>E</b> from the result. Now divide by the
+          value of the field "Rows seen".
+          The result is <b>P</b>.
+</li>
+</ul>
+
+</section>
+
+<section> <title>Computing the value returned by <i>getEstimatedCostPerInstantiation()</i></title>
+
+<p>
+Putting all of this together, the following formula describes the
+        value returned by your
+table function's
+<i>VTICosting.getEstimatedCostPerInstantiation()</i>
+method.
+</p>
+
+<p><b>
+C = O/T * [ ( P * N ) + E ]
+</b></p>
+
+</section>
+
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfopttune.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Fri Sep 21 05:54:03 2007
@@ -2074,6 +2074,20 @@
 </topicref>
 </topicref>
 </topicref>
+<topicref href="cdevspecialtabfuncs.dita" navtitle="Programming Derby-style table functions">
+<topicref href="cdevspecialtfbasic.dita" navtitle="Overview of Derby-style table functions">
+<topicref href="cdevspecialtfgetxxx.dita" navtitle="Preferred getXXX() methods for Derby-style table functions">
+</topicref>
+</topicref>
+<topicref href="cdevspecialtfexample.dita" navtitle="Example Derby-style table function">
+</topicref>
+<topicref href="cdevspecialtfoptimizer.dita" navtitle="Optimizer support for Derby-style table functions">
+<topicref href="cdevspecialtfopttune.dita" navtitle="Measuring the cost of Derby-style table functions">
+</topicref>
+<topicref href="cdevspecialtfoptexample.dita" navtitle="Example VTICosting implementation">
+</topicref>
+</topicref>
+</topicref>
 </topicref>
 <topicref href="cdevconcepts19524.dita" navtitle="Controlling Derby application behavior">
 <topicref href="cdevconcepts38375.dita" navtitle="The JDBC Connection and Transaction Model">

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Sep 21 05:54:03 2007
@@ -183,7 +183,9 @@
 <topicref collection-type="family" href="rrefsqlj19433.dita" navtitle="SQL expressions">
 <topicref href="rrefselectexpression.dita" navtitle="SelectExpression"></topicref>
 <topicref collection-type="family" href="rreftableexpression.dita" navtitle="TableExpression">
-<topicref href="rrefsqlj33215.dita" navtitle="TableOrViewExpression"></topicref>
+<topicref href="rrefsqlj33215.dita" navtitle="TableViewOrFunctionExpression">
+<topicref href="rrefsqljtfinvoke.dita" navtitle="TableFunctionInvocation"></topicref>
+</topicref>
 </topicref>
 <topicref href="rrefsqlj11277.dita" navtitle="VALUES expression"></topicref>
 <topicref href="rrefsqlj1080779.dita" navtitle="Expression precedence"></topicref>

Modified: db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita Fri Sep 21 05:54:03 2007
@@ -37,7 +37,7 @@
 <refsyn><title>Syntax</title> <codeblock><b>CREATE FUNCTION <i><xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionname"
 >function-name</xref></i> ( [ <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref
 > 
-   [, <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref>] ] * ) RETURNS DataType [ <xref
+   [, <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref>] ] * ) RETURNS <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctionreturntype">ReturnDataType</xref> [ <xref
 href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionelement">FunctionElement</xref> ] *</b></codeblock></refsyn>
 <example id="rrefcrprofunctionname"><title>function-Name</title><codeblock><b>[ <i><xref
 href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
@@ -50,10 +50,30 @@
 of <i>DataType</i> is described in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p><note>Data-types
 such as BLOB, CLOB, LONG VARCHAR, LONG VARCHAR FOR BIT DATA, and XML are not
 allowed as parameters in a CREATE FUNCTION statement.</note></section>
+
+<example id="rrefcrfunctionreturntype"><title>ReturnDataType</title>
+<codeblock><b><xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctiontabletype">TableType</xref> | <i>DataType</i></b></codeblock></example>
+<section><p>The syntax
+of <i>DataType</i> is described in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p></section>
+
+<example id="rrefcrfunctiontabletype"><title>TableType</title>
+<codeblock><b>TABLE( <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctioncolelement">ColumnElement</xref> [, <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctioncolelement">ColumnElement</xref> ]* )</b></codeblock></example>
+<section><p>This is the return type of a table function. Currently, only Derby-style table functions are supported.
+They are functions which return JDBC <i>ResultSet</i>s. For more information, see
+"Programming Derby-style table functions" in the
+<cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>.
+</p></section>
+
+<example id="rrefcrfunctioncolelement"><title>ColumnElement</title>
+<codeblock><b><i><xref href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i> <i>DataType</i></b></codeblock></example>
+<section><p>The syntax
+of <i>DataType</i> is described in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p><note>XML is not
+allowed as the type of a column in the dataset returned by a table function.</note></section>
+
 <example id="rrefcrprofunctionelement"> <title>FunctionElement</title><codeblock><b> {
 | LANGUAGE { JAVA }
 | EXTERNAL NAME <i>string</i>
-| PARAMETER STYLE JAVA
+| PARAMETER STYLE <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctionparameterstyle">ParameterStyle</xref>
 | { NO SQL | CONTAINS SQL | READS SQL DATA }
 | { RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT }
  }</b></codeblock></example>
@@ -63,14 +83,25 @@
 the Java method to be called when the function is executed, and takes the
 following form: <codeblock>class_name.method_name</codeblock>The External
 Name cannot have any extraneous spaces.</p></section>
-<section><title>PARAMETER STYLE</title><p><b>JAVA</b> - The function will
+
+<example id="rrefcrfunctionparameterstyle"><title>ParameterStyle</title>
+<codeblock><b>JAVA | DERBY_JDBC_RESULT_SET</b></codeblock></example>
+<section><p>The function will
 use a parameter-passing convention that conforms to the Java language and
 SQL Routines specification. INOUT and OUT parameters will be passed as single
-entry arrays to facilitate returning values. Result sets are returned through
+entry arrays to facilitate returning values. Result sets can be returned through
 additional parameters to the Java method of type java.sql.ResultSet[] that
 are passed single entry arrays.</p><p><ph conref="../conrefs.dita#prod/productshortname"></ph> does
 not support long column types (for example Long Varchar, BLOB, and so on).
-An error will occur if you try to use one of these long column types. </p></section>
+An error will occur if you try to use one of these long column types. </p>
+<p>The PARAMETER STYLE is DERBY_JDBC_RESULT_SET if and only if this
+is a Derby-style table function, that is, a function which returns
+<xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctiontabletype">TableType</xref>
+and which is mapped to a method which returns a JDBC
+<i>ResultSet</i>. Otherwise, the PARAMETER STYLE must be JAVA.
+</p>
+</section>
+
 <section><title>NO SQL, CONTAINS SQL, READS SQL DATA</title> <p>Indicates
 whether the function issues any SQL statements and, if so, what type.</p> <dl>
 <dlentry>

Modified: db/derby/docs/trunk/src/ref/rrefsqlj33215.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj33215.dita?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj33215.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj33215.dita Fri Sep 21 05:54:03 2007
@@ -19,10 +19,9 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
  "../dtd/reference.dtd">
 <reference id="rrefsqlj33215" xml:lang="en-us">
-<title>TableOrViewExpression</title>
+<title>TableViewOrFunctionExpression</title>
 <refbody>
-<example> <codeblock><b>{<i> <xref href="rreftablename.dita#rreftablename">table-Name</xref></i> |<i> <xref
-href="rrefviewname.dita#rrefviewname">view-Name</xref></i>}
+<example> <codeblock><b>{<i> <xref href="rreftablename.dita#rreftablename">table-Name</xref></i> |<i> <xref href="rrefviewname.dita#rrefviewname">view-Name</xref></i> | <i><xref href="rrefsqljtfinvoke.dita#rrefsqljtfinvoke">TableFunctionInvocation</xref></i>}
     [ [ AS ] <i><xref href="rrefcorrelationname.dita#rrefcorrelationname">correlation-Name</xref></i>
         [ (<i><xref href="rrefsimplecolumnname.dita#rrefsimplecolumnname">Simple-column-Name</xref></i> [ , <i><xref
 href="rrefsimplecolumnname.dita#rrefsimplecolumnname">Simple-column-Name</xref></i>]* ) ] ] ]

Added: db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rrefsqljtfinvoke" xml:lang="en-us">
+<title>TableFunctionInvocation</title>
+<refbody>
+<example>
+<codeblock>
+<b>TABLE <i>function-name</i>( [ [ function-arg ] [, function-arg ]* ] )
+</b></codeblock></example>
+
+<section>
+<p>
+Note that when you invoke a table function, you must bind it to a
+correlation name. For example:
+</p>
+</section>
+
+<example>
+<codeblock>
+<b>
+SELECT s.*
+FROM TABLE( externalEmployees( 42 ) ) s
+</b></codeblock></example>
+
+</refbody>
+</reference>
+

Propchange: db/derby/docs/trunk/src/ref/rrefsqljtfinvoke.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/ref/rreftableexpression.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rreftableexpression.dita?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rreftableexpression.dita (original)
+++ db/derby/docs/trunk/src/ref/rreftableexpression.dita Fri Sep 21 05:54:03 2007
@@ -24,8 +24,8 @@
 </metadata>
 </prolog><refbody>
 <section>
-<p>A <i>TableExpression</i> specifies a table or
-view in a <xref href="rrefsqlj21583.dita#rrefsqlj21583">FROM clause</xref>. It is the source from which
+<p>A <i>TableExpression</i> specifies a table, view, or
+function in a <xref href="rrefsqlj21583.dita#rrefsqlj21583">FROM clause</xref>. It is the source from which
 a <i><xref href="rrefselectexpression.dita#rrefselectexpression">SelectExpression</xref></i> selects
 a result.</p>
 <p>A correlation name can be applied to a table in a <i>TableExpression</i> so that its columns can be qualified with that name.
@@ -51,7 +51,7 @@
 can specify, see <cite><ph conref="../conrefs.dita#pub/cittuning"></ph></cite>.</p></section>
 <refsyn><title>Syntax</title>
 <codeblock><b>{
-TableOrViewExpression | JOIN operation 
+TableViewOrFunctionExpression | JOIN operation 
 }
 </b></codeblock>
 </refsyn>

Modified: db/derby/docs/trunk/src/tuning/ctunperf25864.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperf25864.dita?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperf25864.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunperf25864.dita Fri Sep 21 05:54:03 2007
@@ -40,6 +40,8 @@
 directory. </li>
 <li><i><xref href="ctunperf16800.dita#ctunperf16800">Avoid inserts in autocommit mode if possible</xref></i>. Speed
 up insert performance.</li>
+<li><i><xref href="ctunperftablefunctions.dita#ctunperftablefunctions">Customize the optimizer methods for table functions</xref></i>. Force
+more efficient join orders for queries which use table functions.</li>
 </ul>
 <p>These tips might solve your particular performance problem. Be sure to
 visit the Support section of <ph conref="../conrefs.dita#prod/productshortname"></ph>'s Web site for up-to-date performance

Added: db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita?rev=578086&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita (added)
+++ db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita Fri Sep 21 05:54:03 2007
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="ctunperftablefunctions" xml:lang="en-us">
+<title>Customize the optimizer methods for table functions</title>
+<prolog><metadata>
+<keywords><indexterm>Functions<indexterm>table function cost</indexterm></indexterm>
+<indexterm>Optimizer<indexterm>table function cost</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>The optimizer makes hard-coded guesses about how to calculate the cost of a
+user-written Derby-style table function. For this reason, the
+optimizer may place a table function in an inefficient position in the
+join order. You can give the optimizer more information so that it
+makes better choices. See
+"Programming Derby-style table functions" in the
+<cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>.
+</p>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/tuning/ctunperftablefunctions.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/tuning/tuningderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/tuningderby.ditamap?rev=578086&r1=578085&r2=578086&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/tuningderby.ditamap (original)
+++ db/derby/docs/trunk/src/tuning/tuningderby.ditamap Fri Sep 21 05:54:03 2007
@@ -94,6 +94,8 @@
 </topicref>
 <topicref href="ctunperf16800.dita" navtitle="Avoid inserts in autocommit mode if possible">
 </topicref>
+<topicref href="ctunperftablefunctions.dita" navtitle="Customize the optimizer methods for table functions">
+</topicref>
 </topicref>
 <topicref collection-type="family" href="ctunperf31086.dita" navtitle="More tips">
 <topicref href="ctunperf17936.dita" navtitle="Shut down the system properly">



Mime
View raw message