twalthr commented on code in PR #29864: URL: https://github.com/apache/flink/pull/29864#discussion_r4549733280
########## docs/data/functions/conditional/if.yml: ########## @@ -0,0 +1,101 @@ +# 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 + +name: IF +summary: Returns one of two values, depending on a condition. + +syntax: + sql: IF(condition, true_value, false_value) + java: | + $("condition").then(trueValue, falseValue) + ifThenElse($("condition"), trueValue, falseValue) + python: | + col("condition").then(true_value, false_value) + if_then_else(col("condition"), true_value, false_value) + +arguments: + - name: condition + type: BOOLEAN + required: true + description: The condition to check. + - name: true_value + type: A numeric, character string, BOOLEAN, binary, DATE, TIME, TIMESTAMP or TIMESTAMP_LTZ type Review Comment: Are other vendors this specific in their docs? ########## docs/data/functions/cast/try_cast.yml: ########## @@ -0,0 +1,110 @@ +# 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 + +name: TRY_CAST +summary: Converts a value to another data type, and returns NULL if the value doesn't convert. + +syntax: + sql: TRY_CAST(value AS type) + java: | + $("value").tryCast(DataTypes.INT()) + $("value").tryCast(DataTypes.of("INT")) + python: col("value").try_cast(DataTypes.INT()) + +arguments: + - name: value + type: Any type + required: true + description: The value to convert. + - name: type + type: A data type + required: true + description: "The target type, such as `INT` or `DECIMAL(10, 2)`. The [casting table]({{< ref \"docs/sql/reference/data-types\" >}}#casting) lists the types that each type can be cast to." + +returns: + description: "`value` converted to `type`, like `CAST`." + nulls: Returns NULL if `value` is NULL, if `CAST` returns NULL for it, or if it doesn't convert, where `CAST` fails the job. + type: "`type`, always nullable." + +notes: + - A type pair that the casting table doesn't allow still fails the statement at planning time, as with `CAST`. + - "`TRY_CAST` catches only the errors of its own conversion. An error in `value`, such as a nested `CAST` that fails, still fails the job." + - If one element of an array, a map or a row doesn't convert, the whole value is NULL. + - Casts between numeric types don't fail, so `TRY_CAST` doesn't return NULL for them. `TRY_CAST(300 AS TINYINT)` wraps around to `44`, while `TRY_CAST('300' AS TINYINT)` returns NULL. + - "The result is nullable even when the cast can't fail. Wrap it in `COALESCE` with a default to get a NOT NULL value." Review Comment: Why do some notes have quotes? ########## docs/data/functions/conditional/greatest.yml: ########## @@ -0,0 +1,86 @@ +# 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 + +name: GREATEST +summary: Returns the greatest of its arguments. + +syntax: + sql: GREATEST(value1 [, value2]*) + java: call("GREATEST", $("value1"), $("value2")) + python: call("GREATEST", col("value1"), col("value2")) + +arguments: + - name: value1, value2, ... + type: All numeric types, which can be mixed, or all of one of these kinds. Character strings, BOOLEAN, DATE, TIME, TIMESTAMP, TIMESTAMP_LTZ, year-month intervals or day-time intervals + required: true + description: The values to compare. + +returns: + description: The greatest argument. + nulls: Returns NULL if any argument is NULL. + type: The common type of all arguments, such as `BIGINT` for `INT` and `BIGINT`. Nullable if any argument is nullable. + +notes: + - Every argument is evaluated, even after a NULL. + - Strings compare character by character, so upper-case letters come before lower-case ones. + - For `DOUBLE` and `FLOAT`, `NaN` is greater than every other value. + - Arguments that can't be compared with each other, such as `INT` and `STRING`, fail the statement at planning time. + - Other types aren't supported, such as binary strings, `UUID`, `ARRAY`, `MAP` and `ROW`. Neither are mixed kinds, such as `DATE` with `TIMESTAMP`, or `TIMESTAMP` with `TIMESTAMP_LTZ`. Review Comment: Who wants to use GREATEST on ROW? The "negative docs" should be reasonable to the function and kept minimal. ########## docs/data/functions/conditional/greatest.yml: ########## @@ -0,0 +1,86 @@ +# 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 + +name: GREATEST +summary: Returns the greatest of its arguments. + +syntax: + sql: GREATEST(value1 [, value2]*) + java: call("GREATEST", $("value1"), $("value2")) + python: call("GREATEST", col("value1"), col("value2")) + +arguments: + - name: value1, value2, ... + type: All numeric types, which can be mixed, or all of one of these kinds. Character strings, BOOLEAN, DATE, TIME, TIMESTAMP, TIMESTAMP_LTZ, year-month intervals or day-time intervals + required: true + description: The values to compare. + +returns: + description: The greatest argument. + nulls: Returns NULL if any argument is NULL. + type: The common type of all arguments, such as `BIGINT` for `INT` and `BIGINT`. Nullable if any argument is nullable. + +notes: + - Every argument is evaluated, even after a NULL. + - Strings compare character by character, so upper-case letters come before lower-case ones. + - For `DOUBLE` and `FLOAT`, `NaN` is greater than every other value. + - Arguments that can't be compared with each other, such as `INT` and `STRING`, fail the statement at planning time. + - Other types aren't supported, such as binary strings, `UUID`, `ARRAY`, `MAP` and `ROW`. Neither are mixed kinds, such as `DATE` with `TIMESTAMP`, or `TIMESTAMP` with `TIMESTAMP_LTZ`. + - A bare `NULL` as an argument fails. Cast it to a type instead, such as `CAST(NULL AS INT)`. Review Comment: Isn't this rather framework related and can be removed or put to the Function Basics section. ########## docs/data/functions/conditional/nullif.yml: ########## @@ -0,0 +1,80 @@ +# 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 + +name: NULLIF +summary: Returns NULL if two values are equal, and the first value otherwise. + +syntax: + sql: NULLIF(value1, value2) + +arguments: + - name: value1 + type: Any type that `=` can compare with `value2` + required: true + description: The value to return. + - name: value2 + type: The type of `value1`, or one comparable with it + required: true + description: The value that turns `value1` into NULL. + +returns: + description: NULL if `value1` equals `value2`, else `value1`. + nulls: Returns NULL if `value1` equals `value2` or if `value1` is NULL. A NULL `value2` never equals `value1`, so the function returns `value1`. + type: The type of `value1`, always nullable. + +notes: + - "`NULLIF(value1, value2)` is short for `CASE WHEN value1 = value2 THEN NULL ELSE value1 END`, so `value1` is evaluated twice. With a non-deterministic `value1`, such as `RAND_INTEGER(2)`, the comparison and the result can see different values." + - Types that `=` can't compare, such as `INT` and `STRING`, or `VARIANT`, fail the statement at planning time. A bare `NULL` as `value1` fails too, with `ELSE clause or at least one THEN clause must be non-NULL`. Cast it to a type instead, such as `CAST(NULL AS INT)`. + - There is no Table API method. Use `callSql("NULLIF(a, b)")` in Java or `call_sql("NULLIF(a, b)")` in Python. + +see_also: + - {name: CASE, ref: conditional/case} + - {name: COALESCE, ref: conditional/coalesce} + +examples: + - title: Turn a placeholder into NULL + description: "`-1` marks a missing score:" + sql: | + SELECT score, NULLIF(score, -1) AS known_score + FROM (VALUES (80), (-1)) AS t(score); + result: | + | score | known_score | + |-------|-------------| + | 80 | 80 | + | -1 | NULL | + + - title: Avoid a division by zero + description: "Dividing by NULL returns NULL instead of failing:" Review Comment: This has nothing to do the with function, but how expressions are code generated. This is internal behavior. ########## docs/data/functions/utility/current_database.yml: ########## @@ -0,0 +1,67 @@ +# 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 + +name: CURRENT_DATABASE +summary: Returns the name of the current database. + +syntax: + sql: CURRENT_DATABASE() + java: currentDatabase() + python: current_database() + +returns: + description: The name of the current database of the session, such as `default_database` in a new session. + type: "`STRING NOT NULL`." + +notes: + - The name is read once, when the query is translated, so every row of a query gets the same value. A later `USE` doesn't change it for a query that already runs. + - A view returns the current database of the query that reads it, not the database in which the view was created. + - The parentheses are required. `CURRENT_DATABASE` without them is read as a column name. Review Comment: Isn't this common sense? ########## docs/data/functions/window/ntile.yml: ########## @@ -0,0 +1,73 @@ +# 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 + +name: NTILE +summary: Divides the rows of each partition into a number of buckets and returns the bucket of each row. + +syntax: + sql: NTILE(n) OVER ([PARTITION BY expression [, ...]] [ORDER BY expression [ASC | DESC] [, ...]]) + +arguments: + - name: n + type: INT literal + required: true + description: The number of buckets. It must be greater than 0. + +returns: + description: The bucket of the current row, from 1 to `n`, in the `ORDER BY` of the window. If the rows don't divide evenly, the first buckets get one row more, so 6 rows in 4 buckets give `1, 1, 2, 2, 3, 4`. + type: "`BIGINT NOT NULL`." + +notes: + - If `n` is greater than the number of rows, each row gets a bucket of its own, from 1 up. + - Peers, rows with equal `ORDER BY` values, can land in different buckets. + - "`n` must be a literal. A column, a NULL, a negative number or a decimal fails at planning time. `0` fails when the job runs." + - Without an `ORDER BY`, the rows land in the buckets in an undefined order. + - "`NTILE` runs in batch mode only. In streaming mode, it fails with `NTILE Function is not supported in stream mode.`" Review Comment: ```suggestion - "`NTILE` runs in batch mode only. In streaming mode, ...`" ``` Too specific. We don't need to document the message. "Not supported in streaming mode." is enough ########## docs/data/functions/cast/cast.yml: ########## @@ -0,0 +1,128 @@ +# 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 + +name: CAST +summary: Converts a value to another data type, and fails the job if the value doesn't convert. + +syntax: + sql: CAST(value AS type) + java: | + $("value").cast(DataTypes.INT()) + $("value").cast(DataTypes.of("INT")) + python: col("value").cast(DataTypes.INT()) + +arguments: + - name: value + type: Any type + required: true + description: The value to convert. + - name: type + type: A data type + required: true + description: "The target type, such as `INT` or `DECIMAL(10, 2)`. The [casting table]({{< ref \"docs/sql/reference/data-types\" >}}#casting) lists the types that each type can be cast to." + +returns: + description: "`value` converted to `type`." + nulls: Returns NULL if `value` is NULL, if a `VARIANT` holds a JSON null, or if a number doesn't fit a `DECIMAL` target. Review Comment: > if a number doesn't fit a `DECIMAL` target Sounds very specific? -- 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]
