danny0405 commented on code in PR #2844: URL: https://github.com/apache/calcite/pull/2844#discussion_r913733981
########## core/src/main/java/org/apache/calcite/sql/TableCharacteristic.java: ########## @@ -0,0 +1,333 @@ +/* + * 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 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; + } + + public static TableCharacteristic withRowSemantic( + boolean columnsPassThrough) { + // Tables with row semantics are always effectively prune when empty. Review Comment: Is there any possibility we can add a `Builder` for this clazz ? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
