blob: 8431baf2a3b17e9debe66482de74c4709c3dc652 [file] [log] [blame] [view]
<!---
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.
-->
# Datafusion-Specific Functions
These SQL functions are specific to DataFusion, or they are well known and have functionality which is specific to DataFusion. Specifically, the `to_timestamp_xx()` functions exist due to Arrow's support for multiple timestamp resolutions.
## `to_timestamp`
`to_timestamp()` is similar to the standard SQL function. It performs conversions to type `Timestamp(Nanoseconds, None)`, from:
- Timestamp strings
- `1997-01-31T09:26:56.123Z` # RCF3339
- `1997-01-31T09:26:56.123-05:00` # RCF3339
- `1997-01-31 09:26:56.123-05:00` # close to RCF3339 but with a space er than T
- `1997-01-31T09:26:56.123` # close to RCF3339 but no timezone et specified
- `1997-01-31 09:26:56.123` # close to RCF3339 but uses a space and timezone offset
- `1997-01-31 09:26:56` # close to RCF3339, no fractional seconds
- An Int64 array/column, values are nanoseconds since Epoch UTC
- Other Timestamp() columns or values
Note that conversions from other Timestamp and Int64 types can also be performed using `CAST(.. AS Timestamp)`. However, the conversion functionality here is present for consistency with the other `to_timestamp_xx()` functions.
## `to_timestamp_millis`
`to_timestamp_millis()` does conversions to type `Timestamp(Milliseconds, None)`, from:
- Timestamp strings, the same as supported by the regular timestamp() function (except the output is a timestamp of Milliseconds resolution)
- `1997-01-31T09:26:56.123Z` # RCF3339
- `1997-01-31T09:26:56.123-05:00` # RCF3339
- `1997-01-31 09:26:56.123-05:00` # close to RCF3339 but with a space er than T
- `1997-01-31T09:26:56.123` # close to RCF3339 but no timezone et specified
- `1997-01-31 09:26:56.123` # close to RCF3339 but uses a space and timezone offset
- `1997-01-31 09:26:56` # close to RCF3339, no fractional seconds
- An Int64 array/column, values are milliseconds since Epoch UTC
- Other Timestamp() columns or values
Note that `CAST(.. AS Timestamp)` converts to Timestamps with Nanosecond resolution; this function is the only way to convert/cast to millisecond resolution.
## `to_timestamp_micros`
`to_timestamp_micros()` does conversions to type `Timestamp(Microseconds, None)`, from:
- Timestamp strings, the same as supported by the regular timestamp() function (except the output is a timestamp of microseconds resolution)
- `1997-01-31T09:26:56.123Z` # RCF3339
- `1997-01-31T09:26:56.123-05:00` # RCF3339
- `1997-01-31 09:26:56.123-05:00` # close to RCF3339 but with a space er than T
- `1997-01-31T09:26:56.123` # close to RCF3339 but no timezone et specified
- `1997-01-31 09:26:56.123` # close to RCF3339 but uses a space and timezone offset
- `1997-01-31 09:26:56` # close to RCF3339, no fractional seconds
- An Int64 array/column, values are microseconds since Epoch UTC
- Other Timestamp() columns or values
Note that `CAST(.. AS Timestamp)` converts to Timestamps with Nanosecond resolution; this function is the only way to convert/cast to microsecond resolution.
## `to_timestamp_seconds`
`to_timestamp_seconds()` does conversions to type `Timestamp(Seconds, None)`, from:
- Timestamp strings, the same as supported by the regular timestamp() function (except the output is a timestamp of secondseconds resolution)
- `1997-01-31T09:26:56.123Z` # RCF3339
- `1997-01-31T09:26:56.123-05:00` # RCF3339
- `1997-01-31 09:26:56.123-05:00` # close to RCF3339 but with a space er than T
- `1997-01-31T09:26:56.123` # close to RCF3339 but no timezone et specified
- `1997-01-31 09:26:56.123` # close to RCF3339 but uses a space and timezone offset
- `1997-01-31 09:26:56` # close to RCF3339, no fractional seconds
- An Int64 array/column, values are seconds since Epoch UTC
- Other Timestamp() columns or values
Note that `CAST(.. AS Timestamp)` converts to Timestamps with Nanosecond resolution; this function is the only way to convert/cast to seconds resolution.