You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by twalthr <gi...@git.apache.org> on 2017/01/16 10:29:01 UTC
[GitHub] flink pull request #3126: [FLINK-5447] [table] Sync documentation of built-i...
GitHub user twalthr opened a pull request:
https://github.com/apache/flink/pull/3126
[FLINK-5447] [table] Sync documentation of built-in functions for Table API with SQL
This PR restructures the documentation of built-in functions. It ensures:
- All supported functions are documented
- Functions of Java/Scala Table API and SQL have same order and sections
- All methods in Scala Expression API have a Scala doc.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/twalthr/flink FLINK-5447
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/flink/pull/3126.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #3126
----
commit 68745cb1d3557447ab591b1d2a13fb10f141694a
Author: twalthr <tw...@apache.org>
Date: 2017-01-13T14:22:25Z
[FLINK-5447] [table] Sync documentation of built-in functions for Table API with SQL
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] flink issue #3126: [FLINK-5447] [table] Sync documentation of built-in funct...
Posted by twalthr <gi...@git.apache.org>.
Github user twalthr commented on the issue:
https://github.com/apache/flink/pull/3126
Thanks @fhueske. I will perform your changes, solve the build issue and merge this.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] flink pull request #3126: [FLINK-5447] [table] Sync documentation of built-i...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/flink/pull/3126
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] flink pull request #3126: [FLINK-5447] [table] Sync documentation of built-i...
Posted by fhueske <gi...@git.apache.org>.
Github user fhueske commented on a diff in the pull request:
https://github.com/apache/flink/pull/3126#discussion_r96255434
--- Diff: docs/dev/table_api.md ---
@@ -1508,522 +1508,601 @@ Both the Table API and SQL come with a set of built-in functions for data transf
<table class="table table-bordered">
<thead>
<tr>
- <th class="text-left" style="width: 40%">Function</th>
+ <th class="text-left" style="width: 40%">Comparison functions</th>
<th class="text-center">Description</th>
</tr>
</thead>
<tbody>
+
<tr>
<td>
{% highlight java %}
-ANY.as(name [, name ]* )
+ANY === ANY
{% endhighlight %}
</td>
<td>
- <p>Specifies a name for an expression i.e. a field. Additional names can be specified if the expression expands to multiple fields.</p>
+ <p>Equals.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-ANY.isNull
+ANY !== ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given expression is null.</p>
+ <p>Not equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-ANY.isNotNull
+ANY > ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given expression is not null.</p>
+ <p>Greater than.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isTrue
+ANY >= ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given boolean expression is true. False otherwise (for null and false).</p>
+ <p>Greater than or equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isFalse
+ANY < ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if given boolean expression is false. False otherwise (for null and true).</p>
+ <p>Less than.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isNotTrue
+ANY <= ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given boolean expression is not true (for null and false). False otherwise.</p>
+ <p>Less than or equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isNotFalse
+ANY.isNull
{% endhighlight %}
</td>
<td>
- <p>Returns true if given boolean expression is not false (for null and true). False otherwise.</p>
+ <p>Returns true if the given expression is null.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.exp()
+ANY.isNotNull
{% endhighlight %}
</td>
<td>
- <p>Calculates the Euler's number raised to the given power.</p>
+ <p>Returns true if the given expression is not null.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.log10()
+STRING.like(STRING)
{% endhighlight %}
</td>
<td>
- <p>Calculates the base 10 logarithm of given value.</p>
+ <p>Returns true, if a string matches the specified LIKE pattern. E.g. "Jo_n%" matches all strings that start with "Jo(arbitrary letter)n".</p>
</td>
</tr>
-
<tr>
<td>
{% highlight java %}
-NUMERIC.ln()
+STRING.similar(STRING)
{% endhighlight %}
</td>
<td>
- <p>Calculates the natural logarithm of given value.</p>
+ <p>Returns true, if a string matches the specified SQL regex pattern. E.g. "A+" matches all strings that consist of at least one "A".</p>
</td>
</tr>
+ </tbody>
+</table>
+
+<table class="table table-bordered">
+ <thead>
+ <tr>
+ <th class="text-left" style="width: 40%">Logical functions</th>
+ <th class="text-center">Description</th>
+ </tr>
+ </thead>
+
+ <tbody>
+
<tr>
<td>
{% highlight java %}
-NUMERIC.power(NUMERIC)
+boolean1 || boolean2
{% endhighlight %}
</td>
<td>
- <p>Calculates the given number raised to the power of the other value.</p>
+ <p>Whether <i>boolean1</i> is true or <i>boolean2</i> is true.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.sqrt()
+boolean1 && boolean2
{% endhighlight %}
</td>
<td>
- <p>Calculates the square root of a given value.</p>
+ <p>Whether <i>boolean1</i> and <i>boolean2</i> are both true.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.abs()
+!BOOLEAN
{% endhighlight %}
</td>
<td>
- <p>Calculates the absolute value of given value.</p>
+ <p>Whether boolean expression is not true; returns null if boolean is null.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.floor()
+BOOLEAN.isTrue
{% endhighlight %}
</td>
<td>
- <p>Calculates the largest integer less than or equal to a given number.</p>
+ <p>Returns true if the given boolean expression is true. False otherwise (for null and false).</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.ceil()
+BOOLEAN.isFalse
{% endhighlight %}
</td>
<td>
- <p>Calculates the smallest integer greater than or equal to a given number.</p>
+ <p>Returns true if given boolean expression is false. False otherwise (for null and true).</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.substring(INT, INT)
+BOOLEAN.isNotTrue
{% endhighlight %}
</td>
<td>
- <p>Creates a substring of the given string at the given index for the given length. The index starts at 1 and is inclusive, i.e., the character at the index is included in the substring. The substring has the specified length or less.</p>
+ <p>Returns true if the given boolean expression is not true (for null and false). False otherwise.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.substring(INT)
+BOOLEAN.isNotFalse
{% endhighlight %}
</td>
<td>
- <p>Creates a substring of the given string beginning at the given index to the end. The start index starts at 1 and is inclusive.</p>
+ <p>Returns true if given boolean expression is not false (for null and true). False otherwise.</p>
</td>
</tr>
+ </tbody>
+</table>
+
+
+<table class="table table-bordered">
+ <thead>
<tr>
+ <th class="text-left" style="width: 40%">Arithmetic functions</th>
+ <th class="text-center">Description</th>
+ </tr>
+ </thead>
+
+ <tbody>
+
+ <tr>
<td>
{% highlight java %}
-STRING.trim(LEADING, STRING)
-STRING.trim(TRAILING, STRING)
-STRING.trim(BOTH, STRING)
-STRING.trim(BOTH)
-STRING.trim()
++ numeric
{% endhighlight %}
</td>
<td>
- <p>Removes leading and/or trailing characters from the given string. By default, whitespaces at both sides are removed.</p>
+ <p>Returns <i>numeric</i>.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.charLength()
+- numeric
{% endhighlight %}
</td>
<td>
- <p>Returns the length of a String.</p>
+ <p>Returns negative <i>numeric</i>.</p>
</td>
</tr>
-
+
<tr>
<td>
{% highlight java %}
-STRING.upperCase()
+numeric1 + numeric2
{% endhighlight %}
</td>
<td>
- <p>Returns all of the characters in a string in upper case using the rules of the default locale.</p>
+ <p>Returns <i>numeric1</i> plus <i>numeric2</i>.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.lowerCase()
+numeric1 - numeric2
{% endhighlight %}
</td>
<td>
- <p>Returns all of the characters in a string in lower case using the rules of the default locale.</p>
+ <p>Returns <i>numeric1</i> minus <i>numeric2</i>.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.initCap()
+numeric1 * numeric2
{% endhighlight %}
</td>
-
<td>
- <p>Converts the initial letter of each word in a string to uppercase. Assumes a string containing only [A-Za-z0-9], everything else is treated as whitespace.</p>
+ <p>Returns <i>numeric1</i> multiplied by <i>numeric2</i>.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.like(STRING)
+numeric1 / numeric2
{% endhighlight %}
</td>
<td>
- <p>Returns true, if a string matches the specified LIKE pattern. E.g. "Jo_n%" matches all strings that start with "Jo(arbitrary letter)n".</p>
+ <p>Returns <i>numeric1</i> divided by <i>numeric2</i>.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-STRING.similar(STRING)
+NUMERIC.power(NUMERIC)
{% endhighlight %}
</td>
<td>
- <p>Returns true, if a string matches the specified SQL regex pattern. E.g. "A+" matches all strings that consist of at least one "A".</p>
+ <p>Calculates the given number raised to the power of the other value.</p>
--- End diff --
use `numeric1` and `numeric2` to refer to the parameters?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] flink pull request #3126: [FLINK-5447] [table] Sync documentation of built-i...
Posted by fhueske <gi...@git.apache.org>.
Github user fhueske commented on a diff in the pull request:
https://github.com/apache/flink/pull/3126#discussion_r96254835
--- Diff: docs/dev/table_api.md ---
@@ -1508,522 +1508,601 @@ Both the Table API and SQL come with a set of built-in functions for data transf
<table class="table table-bordered">
<thead>
<tr>
- <th class="text-left" style="width: 40%">Function</th>
+ <th class="text-left" style="width: 40%">Comparison functions</th>
<th class="text-center">Description</th>
</tr>
</thead>
<tbody>
+
<tr>
<td>
{% highlight java %}
-ANY.as(name [, name ]* )
+ANY === ANY
{% endhighlight %}
</td>
<td>
- <p>Specifies a name for an expression i.e. a field. Additional names can be specified if the expression expands to multiple fields.</p>
+ <p>Equals.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-ANY.isNull
+ANY !== ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given expression is null.</p>
+ <p>Not equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-ANY.isNotNull
+ANY > ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given expression is not null.</p>
+ <p>Greater than.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isTrue
+ANY >= ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given boolean expression is true. False otherwise (for null and false).</p>
+ <p>Greater than or equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isFalse
+ANY < ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if given boolean expression is false. False otherwise (for null and true).</p>
+ <p>Less than.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isNotTrue
+ANY <= ANY
{% endhighlight %}
</td>
<td>
- <p>Returns true if the given boolean expression is not true (for null and false). False otherwise.</p>
+ <p>Less than or equal.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-BOOLEAN.isNotFalse
+ANY.isNull
{% endhighlight %}
</td>
<td>
- <p>Returns true if given boolean expression is not false (for null and true). False otherwise.</p>
+ <p>Returns true if the given expression is null.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.exp()
+ANY.isNotNull
{% endhighlight %}
</td>
<td>
- <p>Calculates the Euler's number raised to the given power.</p>
+ <p>Returns true if the given expression is not null.</p>
</td>
</tr>
<tr>
<td>
{% highlight java %}
-NUMERIC.log10()
+STRING.like(STRING)
{% endhighlight %}
</td>
<td>
- <p>Calculates the base 10 logarithm of given value.</p>
+ <p>Returns true, if a string matches the specified LIKE pattern. E.g. "Jo_n%" matches all strings that start with "Jo(arbitrary letter)n".</p>
</td>
</tr>
-
<tr>
<td>
{% highlight java %}
-NUMERIC.ln()
+STRING.similar(STRING)
{% endhighlight %}
</td>
<td>
- <p>Calculates the natural logarithm of given value.</p>
+ <p>Returns true, if a string matches the specified SQL regex pattern. E.g. "A+" matches all strings that consist of at least one "A".</p>
</td>
</tr>
+ </tbody>
+</table>
+
+<table class="table table-bordered">
+ <thead>
+ <tr>
+ <th class="text-left" style="width: 40%">Logical functions</th>
+ <th class="text-center">Description</th>
+ </tr>
+ </thead>
+
+ <tbody>
+
<tr>
<td>
{% highlight java %}
-NUMERIC.power(NUMERIC)
+boolean1 || boolean2
{% endhighlight %}
</td>
<td>
- <p>Calculates the given number raised to the power of the other value.</p>
+ <p>Whether <i>boolean1</i> is true or <i>boolean2</i> is true.</p>
--- End diff --
I think `returns true if` is more explicit than`Whether`.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---