diff --git a/docs/functions/README.md b/docs/functions/README.md index 2b87a10..ba6a387 100644 --- a/docs/functions/README.md +++ b/docs/functions/README.md @@ -21,7 +21,7 @@ function differs from the DataFusion built-in of the same name, if there is one. - [Conditional Functions](scalar/conditional.md) (2) - [String Functions](scalar/string.md) (17) - [Binary String Functions](scalar/binary_string.md) (5) -- [Time and Date Functions](scalar/time_and_date.md) (26) +- [Time and Date Functions](scalar/time_and_date.md) (27) - [Array Functions](scalar/array.md) (10) - [Hashing Functions](scalar/hashing.md) (4) - [Other Functions](scalar/other.md) (6) @@ -100,6 +100,7 @@ function differs from the DataFusion built-in of the same name, if there is one. - [length](scalar/string.md#length) - [like](scalar/string.md#like) - [luhn_check](scalar/string.md#luhn_check) +- [make_date](scalar/time_and_date.md#make_date) - [make_dt_interval](scalar/time_and_date.md#make_dt_interval) - [make_interval](scalar/time_and_date.md#make_interval) - [make_time](scalar/time_and_date.md#make_time) diff --git a/docs/functions/scalar/array.md b/docs/functions/scalar/array.md index bcec6e2..91f1af5 100644 --- a/docs/functions/scalar/array.md +++ b/docs/functions/scalar/array.md @@ -168,7 +168,7 @@ array_repeat(element, count) ### Arguments - **element**: Value to repeat, of any type. NULL is repeated. -- **count**: Integer number of times to repeat `element`. Non-integer types are an error. NULL returns NULL. +- **count**: Number of times to repeat `element`, cast to INT. Non-integer types are an error. NULL returns NULL. ### Example diff --git a/docs/functions/scalar/time_and_date.md b/docs/functions/scalar/time_and_date.md index 2880b8c..58a2c82 100644 --- a/docs/functions/scalar/time_and_date.md +++ b/docs/functions/scalar/time_and_date.md @@ -28,6 +28,7 @@ Part of the [datafusion-spark function reference](../README.md). - [from_utc_timestamp](#from_utc_timestamp) - [hour](#hour) - [last_day](#last_day) +- [make_date](#make_date) - [make_dt_interval](#make_dt_interval) - [make_interval](#make_interval) - [make_time](#make_time) @@ -352,6 +353,31 @@ last_day(date) NULL ``` +## `make_date` + +Creates a date from `year`, `month` and `day` fields. Years from -999999999 to 999999999 are accepted (year 0 is 1 BC), as long as the date fits the DATE range. When the fields do not form a valid date (for example month 13 or February 29 in a non-leap year), the function returns NULL, or raises DATETIME_FIELD_OUT_OF_BOUNDS when `datafusion.execution.enable_ansi_mode` is true. A valid date outside the DATE range (before -5877641-06-23 or after +5881580-07-11) raises ARITHMETIC_OVERFLOW in both modes, as in Spark. Other numeric and string inputs are cast to INT first, which truncates fractions and raises an error if the value is out of the INT range or is not a valid number. These errors match Spark with ANSI mode enabled. With ANSI mode disabled, Spark wraps an out-of-range BIGINT or DECIMAL, truncates a string with a fractional part, returns NULL for a malformed string or a floating-point value out of the INT range, and casts NaN to 0, while this function still errors (see https://github.com/apache/datafusion-spark/issues/88). Returns NULL if any input is NULL. DataFusion's built-in `make_date` differs: it raises an error for an invalid date regardless of ANSI mode, accepts only integer and string arguments, and is limited to years -262143 to 262142. + +```sql +make_date(year, month, day) +``` + +### Arguments + +- **year**: The year, from -999999999 to 999999999, as an INT. Other integer, floating-point, decimal and string inputs are cast to INT. NULL returns NULL. +- **month**: The month of the year, from 1 (January) to 12 (December), as an INT. NULL returns NULL. +- **day**: The day of the month, from 1 to 31, as an INT. NULL returns NULL. + +### Example + +```sql +> SELECT make_date(2013, 7, 15); +2013-07-15 +> SELECT make_date(2019, 7, NULL); +NULL +> SELECT make_date(2023, 2, 29); +NULL +``` + ## `make_dt_interval` Returns a day-time interval built from days, hours, minutes and seconds. DataFusion has no built-in equivalent. All arguments are optional from the right and default to 0, so `make_dt_interval()` is a zero interval. Components can be negative and are added together, so `make_dt_interval(1, -24)` is zero. The result is a `Duration(Microsecond)` rather than an Arrow interval, because Arrow's day-time interval only has millisecond precision while Spark's has microsecond precision. Returns NULL if any argument is NULL or `secs` is NaN or infinite. Overflow returns NULL, where Spark raises an error ([#20](https://github.com/apache/datafusion-spark/issues/20)). Unlike Spark, where `secs` is a DECIMAL(18, 6), `secs` is cast to DOUBLE and the fraction is rounded to microseconds.