TableCharacteristic.java
/*
* 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.
*/
package org.apache.calcite.sql;
import org.checkerframework.checker.nullness.qual.Nullable;
import java.util.Objects;
/**
* A table-valued input parameter of a table function is classified by three
* characteristics.
*
* <p>The first characteristic is semantics. The table has either
* row semantics or set semantics.
*
* <p>Row semantics means that the result of the table function is decided
* on a row-by-row basis.
*
* <p>Example of a table function with row semantics input table parameter:
* We often need to read a CSV file, generally, the first line of the file
* contains a list of column names, and subsequent lines of the file contain
* data. The data in general can be treated as a large VARCHAR.
* However, some of the fields may be numeric or datetime.
*
* <p>A table function named CSVReader is designed to read a file of
* comma-separated values and interpret this file as a table.
* The function has three parameters:
* <ul>
* <li>The first parameter, File, is the name of a file on the query author's
* system. This file must contain the comma-separated values that are to be
* converted to a table. The first line of the file contains the names of
* the resulting columns. Succeeding lines contain the data. Each line after
* the first will result in one row of output, with column names as determined
* by the first line of the input.
* <li>Floats is a descriptor area, which should provide a list of the
* column names that are to be interpreted numerically.
* These columns will be output with the data type FLOAT.
* <li>Dates is a descriptor area, which provides a list of the column
* names that are to be interpreted as datetimes.
* These columns will be output with the data type DATE.
* </ul>
*
* <p>How to use this table function in query?
*
* <p>For a csv file which contents are:
* <blockquote><pre>
* docno,name,due_date,principle,interest
* 123,Mary,01/01/2014,234.56,345.67
* 234,Edgar,01/01/2014,654.32,543.21
* </pre></blockquote>
*
* <p>The query author may write a query such as the following:
* <blockquote><pre>{@code
* SELECT *
* FROM TABLE (
* CSVreader (
* 'abc.csv',
* DESCRIPTOR ("principle", "interest")
* DESCRIPTOR ("due_date")))
* }</pre></blockquote>
*
* <table>
* <caption>Results of the query</caption>
* <tr>
* <th>docno</th>
* <th>name</th>
* <th>due_date</th>
* <th>principle</th>
* <th>interest</th>
* </tr>
* <tr>
* <th>123</th>
* <th>Mary</th>
* <th>01/01/2014</th>
* <th>234.56</th>
* <th>345.67</th>
* </tr>
* <tr>
* <th>234</th>
* <th>Edgar</th>
* <th>01/01/2014</th>
* <th>654.32</th>
* <th>543.21</th>
* </tr>
* </table>
*
* <p>Set semantics means that the outcome of the function depends on how
* the data is partitioned. Set semantics is useful to implement user-defined
* analytics like aggregation or window functions.
* They operate on an entire table or a logical partition of it.
*
* <p>Example of a table function with set semantics input table parameter:
* TopN takes an input table that has been sorted on a numeric column.
* It copies the first n rows through to the output table. Any additional
* rows are summarized in a single output row in which the sort column has
* been summed and all other columns are null.
* TopN function has two parameters:
* <ul>
* <li>The first parameter, Input, is the input table. This table has set
* semantics, meaning that the result depends on the set of data (since the
* last row is a summary row). In addition, the table is marked as PRUNE WHEN
* EMPTY, meaning that the result is necessarily empty if the input is empty.
* The query author must order this input table on a single numeric column
* (syntax below).
* <li>The second parameter, Howmany, specifies how many input rows that the
* user wants to be copied into the output table; all rows after this will
* contribute to the final summary row in the output.
* </ul>
*
* <p>How to use this table function in query?
* <table>
* <caption>Original records of table orders</caption>
* <tr>
* <th>region</th>
* <th>product</th>
* <th>sales</th>
* </tr>
* <tr>
* <th>East</th>
* <th>A</th>
* <th>1234.56</th>
* </tr>
* <tr>
* <th>East</th>
* <th>B</th>
* <th>987.65</th>
* </tr>
* <tr>
* <th>East</th>
* <th>C</th>
* <th>876.54</th>
* </tr>
* <tr>
* <th>East</th>
* <th>D</th>
* <th>765.43</th>
* </tr>
* <tr>
* <th>East</th>
* <th>E</th>
* <th>654.32</th>
* </tr>
* <tr>
* <th>West</th>
* <th>E</th>
* <th>2345.67</th>
* </tr>
* <tr>
* <th>West</th>
* <th>D</th>
* <th>2001.33</th>
* </tr>
* <tr>
* <th>West</th>
* <th>C</th>
* <th>1357.99</th>
* </tr>
* <tr>
* <th>West</th>
* <th>B</th>
* <th>975.35</th>
* </tr>
* <tr>
* <th>West</th>
* <th>A</th>
* <th>864,22</th>
* </tr>
* </table>
*
* <p>The query author may write a query such as the following:
* <blockquote><pre>{@code
* SELECT *
* FROM TABLE(
* Topn(
* TABLE orders PARTITION BY region ORDER BY sales desc,
* 3))
* }</pre></blockquote>
*
* <p>The result will be:
* <table>
* <caption>Original records of table orders</caption>
* <tr>
* <th>region</th>
* <th>product</th>
* <th>sales</th>
* </tr>
* <tr>
* <th>East</th>
* <th>A</th>
* <th>1234.56</th>
* </tr>
* <tr>
* <th>East</th>
* <th>B</th>
* <th>987.65</th>
* </tr>
* <tr>
* <th>East</th>
* <th>C</th>
* <th>876.54</th>
* </tr>
* <tr>
* <th>West</th>
* <th>E</th>
* <th>2345.67</th>
* </tr>
* <tr>
* <th>West</th>
* <th>D</th>
* <th>2001.33</th>
* </tr>
* <tr>
* <th>West</th>
* <th>C</th>
* <th>1357.99</th>
* </tr>
* </table>
*
* <p>The second characteristic of input table parameter only applies to input
* table with set semantics. It specifies whether the table function can
* generate a result row even if the input table is empty.
*
* <p>The third characteristic is whether the input table supports
* pass-through columns or not.
*/
public class TableCharacteristic {
/**
* Input table has either row semantics or set semantics.
*/
public final Semantics semantics;
/**
* If the value is true, meaning that the DBMS can prune virtual processors
* from the query plan if the input table is empty.
* If the value is false, meaning that the DBMS must actually instantiate
* a virtual processor (or more than one virtual processor in the presence
* of other input tables).
*/
public final boolean pruneIfEmpty;
/**
* If the value is true, for each input row, the table function makes the
* entire input row available in the output, qualified by a range variable
* associated with the input table. Otherwise the value is false.
*/
public final boolean passColumnsThrough;
private TableCharacteristic(
Semantics semantics,
boolean pruneIfEmpty,
boolean passColumnsThrough) {
this.semantics = semantics;
this.pruneIfEmpty = pruneIfEmpty;
this.passColumnsThrough = passColumnsThrough;
}
/** Creates a builder. */
public static TableCharacteristic.Builder builder(Semantics semantics) {
return new Builder(semantics);
}
@Override public boolean equals(@Nullable Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
TableCharacteristic that = (TableCharacteristic) o;
return pruneIfEmpty == that.pruneIfEmpty
&& passColumnsThrough == that.passColumnsThrough
&& semantics == that.semantics;
}
@Override public int hashCode() {
return Objects.hash(semantics, pruneIfEmpty, passColumnsThrough);
}
@Override public String toString() {
return "TableCharacteristic{"
+ "semantics=" + semantics
+ ", pruneIfEmpty=" + pruneIfEmpty
+ ", passColumnsThrough=" + passColumnsThrough
+ '}';
}
/**
* Input table has either row semantics or set semantics.
*/
public enum Semantics {
/**
* Row semantics means that the result of the Window TableFunction
* is decided on a row-by-row basis.
* As an extreme example, the DBMS could atomize the input table into
* individual rows, and send each single row to a different virtual
* processor.
*/
ROW,
/**
* Set semantics means that the outcome of the Window TableFunction
* depends on how the data is partitioned.
* A partition may not be split across virtual processors, nor may a
* virtual processor handle more than one partition.
*/
SET
}
/**
* Builder for {@link TableCharacteristic}.
*/
public static class Builder {
private final Semantics semantics;
private boolean pruneIfEmpty = false;
private boolean passColumnsThrough = false;
/** Creates the semantics. */
private Builder(Semantics semantics) {
if (semantics == Semantics.ROW) {
// Tables with row semantics are always effectively prune when empty.
this.pruneIfEmpty = true;
}
this.semantics = semantics;
}
/** DBMS could prune virtual processors if the input table is empty. */
public Builder pruneIfEmpty() {
this.pruneIfEmpty = true;
return this;
}
/** Input table supports pass-through columns. */
public Builder passColumnsThrough() {
this.passColumnsThrough = true;
return this;
}
public TableCharacteristic build() {
return new TableCharacteristic(semantics, pruneIfEmpty, passColumnsThrough);
}
}
}