This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new d81c82de44 Improve to_timestamp docs (#8981)
d81c82de44 is described below
commit d81c82de44a5b907667fbdf5e3fac6f8fad55273
Author: Bruce Ritchie <[email protected]>
AuthorDate: Wed Jan 24 15:13:42 2024 -0500
Improve to_timestamp docs (#8981)
* Updated documentation concerning to_timestamp scalar function including
adding missing link in the datafusion-examples/README file. Resolves #8980
* Fix example url.
* Applied prettier.
---
datafusion-examples/README.md | 1 +
.../{dataframe_to_timestamp.rs => to_timestamp.rs} | 37 ++++++-
docs/source/user-guide/sql/scalar_functions.md | 107 ++++++++++++++++++++-
3 files changed, 140 insertions(+), 5 deletions(-)
diff --git a/datafusion-examples/README.md b/datafusion-examples/README.md
index eecb63d3be..298ee9364e 100644
--- a/datafusion-examples/README.md
+++ b/datafusion-examples/README.md
@@ -64,6 +64,7 @@ cargo run --example csv_sql
- [`simple_udaf.rs`](examples/simple_udaf.rs): Define and invoke a User
Defined Aggregate Function (UDAF)
- [`advanced_udaf.rs`](examples/advanced_udaf.rs): Define and invoke a more
complicated User Defined Aggregate Function (UDAF)
- [`simple_udfw.rs`](examples/simple_udwf.rs): Define and invoke a User
Defined Window Function (UDWF)
+- [`to_timestamp.rs`](examples/to_timestamp.rs): Examples of using the
to_timestamp functions
- [`advanced_udwf.rs`](examples/advanced_udwf.rs): Define and invoke a more
complicated User Defined Window Function (UDWF)
## Distributed
diff --git a/datafusion-examples/examples/dataframe_to_timestamp.rs
b/datafusion-examples/examples/to_timestamp.rs
similarity index 70%
rename from datafusion-examples/examples/dataframe_to_timestamp.rs
rename to datafusion-examples/examples/to_timestamp.rs
index 8caa924559..a07dbaefb7 100644
--- a/datafusion-examples/examples/dataframe_to_timestamp.rs
+++ b/datafusion-examples/examples/to_timestamp.rs
@@ -24,7 +24,8 @@ use datafusion::error::Result;
use datafusion::prelude::*;
use datafusion_common::assert_contains;
-/// This example demonstrates how to use the to_timestamp function in the
DataFrame API as well as via sql.
+/// This example demonstrates how to use the to_timestamp series
+/// of functions in the DataFrame API as well as via sql.
#[tokio::main]
async fn main() -> Result<()> {
// define a schema.
@@ -61,7 +62,8 @@ async fn main() -> Result<()> {
// use to_timestamp function to convert col 'a' to timestamp type using
the default parsing
let df = df.with_column("a", to_timestamp(vec![col("a")]))?;
- // use to_timestamp_seconds function to convert col 'b' to
timestamp(Seconds) type using a list of chrono formats to try
+ // use to_timestamp_seconds function to convert col 'b' to
timestamp(Seconds) type using a list
+ // of chrono formats
(https://docs.rs/chrono/latest/chrono/format/strftime/index.html) to try
let df = df.with_column(
"b",
to_timestamp_seconds(vec
- [datepart](#datepart)
- [extract](#extract)
-- [to_timestamp](#to_timestamp)
- [today](#today)
+- [to_timestamp](#to_timestamp)
- [to_timestamp_millis](#to_timestamp_millis)
- [to_timestamp_micros](#to_timestamp_micros)
- [to_timestamp_seconds](#to_timestamp_seconds)
@@ -1526,6 +1526,27 @@ to_timestamp(expression[, ..., format_n])
[chrono format]:
https://docs.rs/chrono/latest/chrono/format/strftime/index.html
+#### Example
+
+```
+❯ select to_timestamp('2023-01-31T09:26:56.123456789-05:00');
++-----------------------------------------------------------+
+| to_timestamp(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
++-----------------------------------------------------------+
+| 2023-01-31T14:26:56.123456789 |
++-----------------------------------------------------------+
+❯ select to_timestamp('03:59:00.123456789 05-17-2023', '%c', '%+',
'%H:%M:%S%.f %m-%d-%Y');
++--------------------------------------------------------------------------------------------------------+
+| to_timestamp(Utf8("03:59:00.123456789
05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
++--------------------------------------------------------------------------------------------------------+
+| 2023-05-17T03:59:00.123456789
|
++--------------------------------------------------------------------------------------------------------+
+```
+
+Additional examples can be found [here]
+
+[here]:
https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs
+
### `to_timestamp_millis`
Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`).
@@ -1546,6 +1567,27 @@ to_timestamp_millis(expression[, ..., format_n])
they appear with the first successful one being returned. If none of the
formats successfully parse the expression
an error will be returned.
+#### Example
+
+```
+❯ select to_timestamp_millis('2023-01-31T09:26:56.123456789-05:00');
++------------------------------------------------------------------+
+| to_timestamp_millis(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
++------------------------------------------------------------------+
+| 2023-01-31T14:26:56.123 |
++------------------------------------------------------------------+
+❯ select to_timestamp_millis('03:59:00.123456789 05-17-2023', '%c', '%+',
'%H:%M:%S%.f %m-%d-%Y');
++---------------------------------------------------------------------------------------------------------------+
+| to_timestamp_millis(Utf8("03:59:00.123456789
05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
++---------------------------------------------------------------------------------------------------------------+
+| 2023-05-17T03:59:00.123
|
++---------------------------------------------------------------------------------------------------------------+
+```
+
+Additional examples can be found [here]
+
+[here]:
https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs
+
### `to_timestamp_micros`
Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000Z`).
@@ -1566,6 +1608,27 @@ to_timestamp_micros(expression[, ..., format_n])
they appear with the first successful one being returned. If none of the
formats successfully parse the expression
an error will be returned.
+#### Example
+
+```
+❯ select to_timestamp_micros('2023-01-31T09:26:56.123456789-05:00');
++------------------------------------------------------------------+
+| to_timestamp_micros(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
++------------------------------------------------------------------+
+| 2023-01-31T14:26:56.123456 |
++------------------------------------------------------------------+
+❯ select to_timestamp_micros('03:59:00.123456789 05-17-2023', '%c', '%+',
'%H:%M:%S%.f %m-%d-%Y');
++---------------------------------------------------------------------------------------------------------------+
+| to_timestamp_micros(Utf8("03:59:00.123456789
05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
++---------------------------------------------------------------------------------------------------------------+
+| 2023-05-17T03:59:00.123456
|
++---------------------------------------------------------------------------------------------------------------+
+```
+
+Additional examples can be found [here]
+
+[here]:
https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs
+
### `to_timestamp_nanos`
Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000000Z`).
@@ -1586,6 +1649,27 @@ to_timestamp_nanos(expression[, ..., format_n])
they appear with the first successful one being returned. If none of the
formats successfully parse the expression
an error will be returned.
+#### Example
+
+```
+❯ select to_timestamp_nanos('2023-01-31T09:26:56.123456789-05:00');
++-----------------------------------------------------------------+
+| to_timestamp_nanos(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
++-----------------------------------------------------------------+
+| 2023-01-31T14:26:56.123456789 |
++-----------------------------------------------------------------+
+❯ select to_timestamp_nanos('03:59:00.123456789 05-17-2023', '%c', '%+',
'%H:%M:%S%.f %m-%d-%Y');
++--------------------------------------------------------------------------------------------------------------+
+| to_timestamp_nanos(Utf8("03:59:00.123456789
05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
++--------------------------------------------------------------------------------------------------------------+
+| 2023-05-17T03:59:00.123456789
|
++---------------------------------------------------------------------------------------------------------------+
+```
+
+Additional examples can be found [here]
+
+[here]:
https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs
+
### `to_timestamp_seconds`
Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`).
@@ -1606,6 +1690,27 @@ to_timestamp_seconds(expression[, ..., format_n])
they appear with the first successful one being returned. If none of the
formats successfully parse the expression
an error will be returned.
+#### Example
+
+```
+❯ select to_timestamp_seconds('2023-01-31T09:26:56.123456789-05:00');
++-------------------------------------------------------------------+
+| to_timestamp_seconds(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
++-------------------------------------------------------------------+
+| 2023-01-31T14:26:56 |
++-------------------------------------------------------------------+
+❯ select to_timestamp_seconds('03:59:00.123456789 05-17-2023', '%c', '%+',
'%H:%M:%S%.f %m-%d-%Y');
++----------------------------------------------------------------------------------------------------------------+
+| to_timestamp_seconds(Utf8("03:59:00.123456789
05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
++----------------------------------------------------------------------------------------------------------------+
+| 2023-05-17T03:59:00
|
++----------------------------------------------------------------------------------------------------------------+
+```
+
+Additional examples can be found [here]
+
+[here]:
https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs
+
### `from_unixtime`
Converts an integer to RFC3339 timestamp format
(`YYYY-MM-DDT00:00:00.000000000Z`).
