svn commit: r1711692 - /calcite/site/docs/reference.html

[jh...@apache.org]

Author: jhyde
Date: Sat Oct 31 22:10:09 2015
New Revision: 1711692

URL: http://svn.apache.org/viewvc?rev=1711692&view=rev
Log:
User-defined functions; optional and named parameters

Modified:
    calcite/site/docs/reference.html

Modified: calcite/site/docs/reference.html
URL: http://svn.apache.org/viewvc/calcite/site/docs/reference.html?rev=1711692&r1=1711691&r2=1711692&view=diff
==============================================================================
--- calcite/site/docs/reference.html (original)
+++ calcite/site/docs/reference.html Sat Oct 31 22:10:09 2015
@@ -1910,6 +1910,109 @@ passed to the aggregate function.</p>
   </tbody>
 </table>
 
+<h3 id="user-defined-functions">User-defined functions</h3>
+
+<p>Calcite is extensible. You can define each kind of function using user code.
+For each kind of function there are often several ways to define a function,
+varying from convenient to efficient.</p>
+
+<p>To implement a <em>scalar function</em>, there are 3 options:</p>
+
+<ul>
+  <li>Create a class with a public static <code>eval</code> method. and register the class;</li>
+  <li>Create a class with a public non-static <code>eval</code> method. and a public
+constructor with no arguments, and register the class;</li>
+  <li>Create a class with one or more public static methods, and register 
+each class and method.</li>
+</ul>
+
+<p>To implement an <em>aggregate function</em>:</p>
+
+<ul>
+  <li>Create a class with public static <code>init</code>, <code>add</code> and <code>result</code> methods, and
+register the class;</li>
+  <li>Create a class with public non-static <code>init</code>, <code>add</code> and <code>result</code> methods, and
+a  public constructor with no arguments, and register the class.</li>
+</ul>
+
+<p>Optionally, add a public <code>merge</code> method to the class; this allows Calcite to
+generate code that merges sub-totals.</p>
+
+<p>Optionally, make your class implement the
+<a href="/apidocs/org/apache/calcite/sql/SqlSplittableAggFunction.html">SqlSplittableAggFunction</a>
+interface; this allows Calcite to decompose the function across several stages
+of aggregation, roll up from summary tables, and push it through joins.</p>
+
+<p>To implement a <em>table function</em>:</p>
+
+<ul>
+  <li>Create a class with a static <code>eval</code> method that returns
+<a href="/apidocs/org/apache/calcite/schema/TranslatableTable.html">TranslatableTable</a>
+or
+<a href="/apidocs/org/apache/calcite/schema/QueryableTable.html">QueryableTable</a>,
+and register the class;</li>
+  <li>Create a class with a non-static <code>eval</code> method that returns
+<a href="/apidocs/org/apache/calcite/schema/TranslatableTable.html">TranslatableTable</a>
+or
+<a href="/apidocs/org/apache/calcite/schema/QueryableTable.html">QueryableTable</a>,
+and register the class.</li>
+</ul>
+
+<p>Calcite deduces the parameter types and result type of a function from the
+parameter and return types of the Java method that implements it. Further, you
+can specify the name and optionality of each parameter using the
+<a href="/apidocs/org/apache/calcite/linq4j/function/Parameter.html">Parameter</a>
+annotation.</p>
+
+<h3 id="calling-functions-with-named-and-optional-parameters">Calling functions with named and optional parameters</h3>
+
+<p>Usually when you call a function, you need to specify all of its parameters,
+in order. But if the function has been defined with named and optional
+parameters </p>
+
+<p>Suppose you have a function <code>f</code>, declared as in the following pseudo syntax:</p>
+
+<p><code>FUNCTION f(
+  INTEGER a,
+  INTEGER b DEFAULT NULL,
+  INTEGER c,
+  INTEGER d DEFAULT NULL,
+  INTEGER e DEFAULT NULL) RETURNS INTEGER</code></p>
+
+<p>Note that all parameters have names, and parameters <code>b</code>, <code>d</code> and <code>e</code>
+have a default value of <code>NULL</code> and are therefore optional.
+(In Calcite, <code>NULL</code> is the only allowable default value for optional parameters;
+this may change
+<a href="https://issues.apache.org/jira/browse/CALCITE-947">in future</a>.)</p>
+
+<p>You can omit optional arguments at the end of the list, or use the <code>DEFAULT</code>
+keyword for any optional arguments.
+Here are some examples:</p>
+
+<ul>
+  <li><code>f(1, 2, 3, 4, 5)</code> provides a value to each parameter, in order;</li>
+  <li><code>f(1, 2, 3, 4)</code> omits <code>e</code>, which gets its default value, <code>NULL</code>;</li>
+  <li><code>f(1, DEFAULT, 3)</code> omits <code>d</code> and <code>e</code>,
+and specifies to use the default value of <code>b</code>;</li>
+  <li><code>f(1, DEFAULT, 3, DEFAULT, DEFAULT)</code> has the same effect as the previous
+example;</li>
+  <li><code>f(1, 2)</code> is not legal, because <code>c</code> is not optional;</li>
+  <li><code>f(1, 2, DEFAULT, 4)</code> is not legal, because <code>c</code> is not optional.</li>
+</ul>
+
+<p>You can specify arguments by name using the <code>=&gt;</code> syntax.
+If one argument is named, they all must be.
+Arguments may be in any other, but must not specify any argument more than once,
+and you need to provide a value for every parameter which is not optional.
+Here are some examples:</p>
+
+<ul>
+  <li><code>f(c =&gt; 3, d =&gt; 1, a =&gt; 0)</code> is equivalent to <code>f(0, NULL, 3, 1, NULL)</code>;</li>
+  <li><code>f(c =&gt; 3, d =&gt; 1)</code> is not legal, because you have not specified a value for
+<code>a</code> and <code>a</code> is not optional.</li>
+</ul>
+
+