1245 lines
38 KiB
Plaintext
1245 lines
38 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[sql-functions-datetime]]
|
|
=== Date/Time and Interval Functions and Operators
|
|
|
|
{es-sql} offers a wide range of facilities for performing date/time manipulations.
|
|
|
|
[[sql-functions-datetime-interval]]
|
|
==== Intervals
|
|
|
|
A common requirement when dealing with date/time in general revolves around
|
|
the notion of `interval`, a topic that is worth exploring in the context of {es} and {es-sql}.
|
|
|
|
{es} has comprehensive support for <<date-math, date math>> both inside <<date-math-index-names, index names>> and <<mapping-date-format, queries>>.
|
|
Inside {es-sql} the former is supported as is by passing the expression in the table name, while the latter is supported through the standard SQL `INTERVAL`.
|
|
|
|
The table below shows the mapping between {es} and {es-sql}:
|
|
|
|
[cols="^m,^m"]
|
|
|==========================
|
|
s|{es}
|
|
s|{es-sql}
|
|
2+h| Index/Table datetime math
|
|
2+|<index-{now/M{YYYY.MM}}>
|
|
2+h| Query date/time math
|
|
| 1y | INTERVAL 1 YEAR
|
|
| 2M | INTERVAL 2 MONTH
|
|
| 3w | INTERVAL 21 DAY
|
|
| 4d | INTERVAL 4 DAY
|
|
| 5h | INTERVAL 5 HOUR
|
|
| 6m | INTERVAL 6 MINUTE
|
|
| 7s | INTERVAL 7 SECOND
|
|
|==========================
|
|
|
|
`INTERVAL` allows either `YEAR` and `MONTH` to be mixed together _or_ `DAY`, `HOUR`, `MINUTE` and `SECOND`.
|
|
|
|
TIP: {es-sql} accepts also the plural for each time unit (e.g. both `YEAR` and `YEARS` are valid).
|
|
|
|
Example of the possible combinations below:
|
|
|
|
[cols="^,^"]
|
|
|
|
|===
|
|
s|Interval
|
|
s|Description
|
|
| `INTERVAL '1-2' YEAR TO MONTH` | 1 year and 2 months
|
|
| `INTERVAL '3 4' DAYS TO HOURS` | 3 days and 4 hours
|
|
| `INTERVAL '5 6:12' DAYS TO MINUTES` | 5 days, 6 hours and 12 minutes
|
|
| `INTERVAL '3 4:56:01' DAY TO SECOND` | 3 days, 4 hours, 56 minutes and 1 second
|
|
| `INTERVAL '2 3:45:01.23456789' DAY TO SECOND` | 2 days, 3 hours, 45 minutes, 1 second and 234567890 nanoseconds
|
|
| `INTERVAL '123:45' HOUR TO MINUTES` | 123 hours and 45 minutes
|
|
| `INTERVAL '65:43:21.0123' HOUR TO SECONDS` | 65 hours, 43 minutes, 21 seconds and 12300000 nanoseconds
|
|
| `INTERVAL '45:01.23' MINUTES TO SECONDS` | 45 minutes, 1 second and 230000000 nanoseconds
|
|
|===
|
|
|
|
==== Operators
|
|
|
|
Basic arithmetic operators (`+`, `-`, `*`) support date/time parameters as indicated below:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtIntervalPlusInterval]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtDateTimePlusInterval]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtMinusInterval]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtIntervalMinusInterval]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtDateTimeMinusInterval]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dtIntervalMul]
|
|
--------------------------------------------------
|
|
|
|
==== Functions
|
|
|
|
Functions that target date/time.
|
|
|
|
[[sql-functions-current-date]]
|
|
==== `CURRENT_DATE/CURDATE`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
CURRENT_DATE
|
|
CURRENT_DATE()
|
|
CURDATE()
|
|
--------------------------------------------------
|
|
|
|
*Input*: _none_
|
|
|
|
*Output*: date
|
|
|
|
*Description*: Returns the date (no time part) when the current query reached the server.
|
|
It can be used both as a keyword: `CURRENT_DATE` or as a function with no arguments: `CURRENT_DATE()`.
|
|
|
|
[NOTE]
|
|
Unlike CURRENT_DATE, `CURDATE()` can only be used as a function with no arguments and not as a keyword.
|
|
|
|
This method always returns the same value for its every occurrence within the same query.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[currentDate]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[currentDateFunction]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[curDateFunction]
|
|
--------------------------------------------------
|
|
|
|
Typically, this function (as well as its twin <<sql-functions-today,TODAY())>> function
|
|
is used for relative date filtering:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[filterToday]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-current-time]]
|
|
==== `CURRENT_TIME/CURTIME`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
CURRENT_TIME
|
|
CURRENT_TIME([precision]) <1>
|
|
CURTIME
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> fractional digits; optional
|
|
|
|
*Output*: time
|
|
|
|
*Description*: Returns the time when the current query reached the server.
|
|
As a function, `CURRENT_TIME()` accepts _precision_ as an optional
|
|
parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3,
|
|
meaning a milliseconds precision current time will be returned.
|
|
|
|
This method always returns the same value for its every occurrence within the same query.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[currentTime]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[currentTimeFunction]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[curTimeFunction]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[currentTimeFunctionPrecision]
|
|
--------------------------------------------------
|
|
|
|
Typically, this function is used for relative date/time filtering:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[filterCurrentTime]
|
|
--------------------------------------------------
|
|
|
|
[IMPORTANT]
|
|
Currently, using a _precision_ greater than 3 doesn't make any difference to the output of the
|
|
function as the maximum number of second fractional digits returned is 3 (milliseconds).
|
|
|
|
[[sql-functions-current-timestamp]]
|
|
==== `CURRENT_TIMESTAMP`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
CURRENT_TIMESTAMP
|
|
CURRENT_TIMESTAMP([precision]) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> fractional digits; optional
|
|
|
|
*Output*: date/time
|
|
|
|
*Description*: Returns the date/time when the current query reached the server.
|
|
As a function, `CURRENT_TIMESTAMP()` accepts _precision_ as an optional
|
|
parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3,
|
|
meaning a milliseconds precision current date/time will be returned.
|
|
|
|
This method always returns the same value for its every occurrence within the same query.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[curTs]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[curTsFunction]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[curTsFunctionPrecision]
|
|
--------------------------------------------------
|
|
|
|
Typically, this function (as well as its twin <<sql-functions-now,NOW())>> function is used for
|
|
relative date/time filtering:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[filterNow]
|
|
--------------------------------------------------
|
|
|
|
[IMPORTANT]
|
|
Currently, using a _precision_ greater than 3 doesn't make any difference to the output of the
|
|
function as the maximum number of second fractional digits returned is 3 (milliseconds).
|
|
|
|
[[sql-functions-datetime-add]]
|
|
==== `DATE_ADD/DATEADD/TIMESTAMP_ADD/TIMESTAMPADD`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATE_ADD(
|
|
string_exp, <1>
|
|
integer_exp, <2>
|
|
datetime_exp) <3>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> string expression denoting the date/time unit to add to the date/datetime
|
|
<2> integer expression denoting how many times the above unit should be added to/from the date/datetime,
|
|
if a negative value is used it results to a subtraction from the date/datetime
|
|
<3> date/datetime expression
|
|
|
|
*Output*: datetime
|
|
|
|
*Description*: Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from
|
|
the date/datetime. If any of the three arguments is `null` a `null` is returned.
|
|
|
|
[WARNING]
|
|
If the second argument is a long there is possibility of truncation since an integer value will be extracted and
|
|
used from that long.
|
|
|
|
[cols="^,^"]
|
|
|===
|
|
2+h|Datetime units to add/subtract
|
|
|
|
s|unit
|
|
s|abbreviations
|
|
|
|
| year | years, yy, yyyy
|
|
| quarter | quarters, qq, q
|
|
| month | months, mm, m
|
|
| dayofyear | dy, y
|
|
| day | days, dd, d
|
|
| week | weeks, wk, ww
|
|
| weekday | weekdays, dw
|
|
| hour | hours, hh
|
|
| minute | minutes, mi, n
|
|
| second | seconds, ss, s
|
|
| millisecond | milliseconds, ms
|
|
| microsecond | microseconds, mcs
|
|
| nanosecond | nanoseconds, ns
|
|
|===
|
|
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateAddDateTimeYears]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateAddDateTimeWeeks]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateAddDateTimeSeconds]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateAddDateQuarters]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateAddDateMinutes]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-diff]]
|
|
==== `DATE_DIFF/DATEDIFF/TIMESTAMP_DIFF/TIMESTAMPDIFF`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATE_DIFF(
|
|
string_exp, <1>
|
|
datetime_exp, <2>
|
|
datetime_exp) <3>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> string expression denoting the date/time unit difference between the following two date/datetime expressions
|
|
<2> start date/datetime expression
|
|
<3> end date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Subtract the second argument from the third argument and return their difference in multiples of the unit
|
|
specified in the first argument. If the second argument (start) is greater than the third argument (end),
|
|
then negative values are returned. If any of the three arguments is `null`, a `null` is returned.
|
|
|
|
[cols="^,^"]
|
|
|===
|
|
2+h|Datetime difference units
|
|
|
|
s|unit
|
|
s|abbreviations
|
|
|
|
| year | years, yy, yyyy
|
|
| quarter | quarters, qq, q
|
|
| month | months, mm, m
|
|
| dayofyear | dy, y
|
|
| day | days, dd, d
|
|
| week | weeks, wk, ww
|
|
| weekday | weekdays, dw
|
|
| hour | hours, hh
|
|
| minute | minutes, mi, n
|
|
| second | seconds, ss, s
|
|
| millisecond | milliseconds, ms
|
|
| microsecond | microseconds, mcs
|
|
| nanosecond | nanoseconds, ns
|
|
|===
|
|
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateTimeYears]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateTimeWeeks]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateTimeSeconds]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateQuarters]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
For `hour` and `minute`, `DATEDIFF` doesn't do any rounding, but instead first truncates
|
|
the more detailed time fields on the 2 dates to zero and then calculates the subtraction.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateTimeHours]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateTimeMinutes]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateDiffDateMinutes]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-dateparse]]
|
|
==== `DATE_PARSE`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATE_PARSE(
|
|
string_exp, <1>
|
|
string_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date expression as a string
|
|
<2> parsing pattern
|
|
|
|
*Output*: date
|
|
|
|
*Description*: Returns a date by parsing the 1st argument using the format specified in the 2nd argument. The parsing
|
|
format pattern used is the one from
|
|
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
|
|
If any of the two arguments is `null` or an empty string, then `null` is returned.
|
|
|
|
[NOTE]
|
|
If the parsing pattern does not contain all valid date units (e.g. 'HH:mm:ss', 'dd-MM HH:mm:ss', etc.) an error is returned
|
|
as the function needs to return a value of `date` type which will contain date part.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateParse1]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
====
|
|
The resulting `date` will have the time zone specified by the user through the
|
|
<<sql-rest-fields-timezone,`time_zone`>>/<<jdbc-cfg-timezone,`timezone`>> REST/driver parameters
|
|
with no conversion applied.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateParse2]
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[[sql-functions-datetime-datetimeformat]]
|
|
==== `DATETIME_FORMAT`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATETIME_FORMAT(
|
|
date_exp/datetime_exp/time_exp, <1>
|
|
string_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime/time expression
|
|
<2> format pattern
|
|
|
|
*Output*: string
|
|
|
|
*Description*: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting
|
|
pattern used is the one from
|
|
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
|
|
If any of the two arguments is `null` or the pattern is an empty string `null` is returned.
|
|
|
|
[NOTE]
|
|
If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units
|
|
(e.g. 'dd', 'MM', 'YYYY', etc.). If it contains such units an error is returned.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeFormatDate]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeFormatDateTime]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeFormatTime]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-datetimeparse]]
|
|
==== `DATETIME_PARSE`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATETIME_PARSE(
|
|
string_exp, <1>
|
|
string_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> datetime expression as a string
|
|
<2> parsing pattern
|
|
|
|
*Output*: datetime
|
|
|
|
*Description*: Returns a datetime by parsing the 1st argument using the format specified in the 2nd argument. The parsing
|
|
format pattern used is the one from
|
|
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
|
|
If any of the two arguments is `null` or an empty string `null` is returned.
|
|
|
|
|
|
[NOTE]
|
|
If the parsing pattern contains only date or only time units (e.g. 'dd/MM/uuuu', 'HH:mm:ss', etc.) an error is returned
|
|
as the function needs to return a value of `datetime` type which must contain both.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeParse1]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeParse2]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
====
|
|
If timezone is not specified in the datetime string expression and the parsing pattern, the resulting `datetime` will have the
|
|
time zone specified by the user through the <<sql-rest-fields-timezone,`time_zone`>>/<<jdbc-cfg-timezone,`timezone`>> REST/driver parameters
|
|
with no conversion applied.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dateTimeParse3]
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[[sql-functions-datetime-timeparse]]
|
|
==== `TIME_PARSE`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
TIME_PARSE(
|
|
string_exp, <1>
|
|
string_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> time expression as a string
|
|
<2> parsing pattern
|
|
|
|
*Output*: time
|
|
|
|
*Description*: Returns a time by parsing the 1st argument using the format specified in the 2nd argument. The parsing
|
|
format pattern used is the one from
|
|
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
|
|
If any of the two arguments is `null` or an empty string `null` is returned.
|
|
|
|
[NOTE]
|
|
If the parsing pattern contains only date units (e.g. 'dd/MM/uuuu') an error is returned
|
|
as the function needs to return a value of `time` type which will contain only time.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[timeParse1]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[timeParse2]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
====
|
|
If timezone is not specified in the time string expression and the parsing pattern,
|
|
the resulting `time` will have the offset of the time zone specified by the user through the
|
|
<<sql-rest-fields-timezone,`time_zone`>>/<<jdbc-cfg-timezone,`timezone`>> REST/driver
|
|
parameters at the Unix epoch date (`1970-01-01`) with no conversion applied.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[timeParse3]
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[[sql-functions-datetime-part]]
|
|
==== `DATE_PART/DATEPART`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATE_PART(
|
|
string_exp, <1>
|
|
datetime_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> string expression denoting the unit to extract from the date/datetime
|
|
<2> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned.
|
|
It's similar to <<sql-functions-datetime-extract>> but with different names and aliases for the units and
|
|
provides more options (e.g.: `TZOFFSET`).
|
|
|
|
[cols="^,^"]
|
|
|===
|
|
2+h|Datetime units to extract
|
|
|
|
s|unit
|
|
s|abbreviations
|
|
|
|
| year | years, yy, yyyy
|
|
| quarter | quarters, qq, q
|
|
| month | months, mm, m
|
|
| dayofyear | dy, y
|
|
| day | days, dd, d
|
|
| week | weeks, wk, ww
|
|
| weekday | weekdays, dw
|
|
| hour | hours, hh
|
|
| minute | minutes, mi, n
|
|
| second | seconds, ss, s
|
|
| millisecond | milliseconds, ms
|
|
| microsecond | microseconds, mcs
|
|
| nanosecond | nanoseconds, ns
|
|
| tzoffset | tz
|
|
|===
|
|
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateTimeYears]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateTimeMinutes]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateQuarter]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateMonth]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
For `week` and `weekday` the unit is extracted using the non-ISO calculation, which means
|
|
that a given week is considered to start from Sunday, not Monday.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateTimeWeek]
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
The `tzoffset` returns the total number of minutes (signed) that represent the time zone's offset.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateTimeTzOffsetPlus]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[datePartDateTimeTzOffsetMinus]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-trunc]]
|
|
==== `DATE_TRUNC/DATETRUNC`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DATE_TRUNC(
|
|
string_exp, <1>
|
|
datetime_exp/interval_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> string expression denoting the unit to which the date/datetime/interval should be truncated to
|
|
<2> date/datetime/interval expression
|
|
|
|
*Output*: datetime/interval
|
|
|
|
*Description*: Truncate the date/datetime/interval to the specified unit by setting all fields that are less significant than the specified
|
|
one to zero (or one, for day, day of week and month). If any of the two arguments is `null` a `null` is returned.
|
|
If the first argument is `week` and the second argument is of `interval` type, an error is thrown since the `interval` data type doesn't support a `week` time unit.
|
|
|
|
[cols="^,^"]
|
|
|===
|
|
2+h|Datetime truncation units
|
|
|
|
s|unit
|
|
s|abbreviations
|
|
|
|
| millennium | millennia
|
|
| century | centuries
|
|
| decade | decades
|
|
| year | years, yy, yyyy
|
|
| quarter | quarters, qq, q
|
|
| month | months, mm, m
|
|
| week | weeks, wk, ww
|
|
| day | days, dd, d
|
|
| hour | hours, hh
|
|
| minute | minutes, mi, n
|
|
| second | seconds, ss, s
|
|
| millisecond | milliseconds, ms
|
|
| microsecond | microseconds, mcs
|
|
| nanosecond | nanoseconds, ns
|
|
|===
|
|
|
|
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateDateTimeMillennium]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateDateTimeWeek]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateDateTimeMinutes]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateDateDecades]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateDateQuarter]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateIntervalCenturies]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateIntervalHour]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[truncateIntervalDay]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-format]]
|
|
==== `FORMAT`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
FORMAT(
|
|
date_exp/datetime_exp/time_exp, <1>
|
|
string_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime/time expression
|
|
<2> format pattern
|
|
|
|
*Output*: string
|
|
|
|
*Description*: Returns the date/datetime/time as a string using the
|
|
https://docs.microsoft.com/en-us/sql/t-sql/functions/format-transact-sql#arguments[format] specified in the 2nd argument. The formatting
|
|
pattern used is the one from
|
|
https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings[Microsoft SQL Server Format Specification].
|
|
If any of the two arguments is `null` or the pattern is an empty string `null` is returned.
|
|
|
|
[NOTE]
|
|
If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units
|
|
(e.g. 'dd', 'MM', 'YYYY', etc.). If it contains such units an error is returned.
|
|
|
|
*Special Cases*
|
|
|
|
- Format specifier `F` will be working similar to format specifier `f`.
|
|
It will return the fractional part of seconds, and the number of digits will be same as of the number of `Fs` provided as input (up to 9 digits).
|
|
Result will contain `0` appended in the end to match with number of `F` provided.
|
|
e.g.: for a time part `10:20:30.1234` and pattern `HH:mm:ss.FFFFFF`, the output string of the function would be: `10:20:30.123400`.
|
|
- Format Specifier `y` will return year-of-era instead of one/two low-order digits.
|
|
eg.: For year `2009`, `y` will be returning `2009` instead of `9`. For year `43`, `y` format specifier will return `43`.
|
|
- Special characters like `"` , `\` and `%` will be returned as it is without any change. eg.: formatting date `17-sep-2020` with `%M` will return `%9`
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[formatDate]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[formatDateTime]
|
|
--------------------------------------------------
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[formatTime]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-day]]
|
|
==== `DAY_OF_MONTH/DOM/DAY`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DAY_OF_MONTH(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the day of the month from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dayOfMonth]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-dow]]
|
|
==== `DAY_OF_WEEK/DAYOFWEEK/DOW`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DAY_OF_WEEK(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dayOfWeek]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-doy]]
|
|
==== `DAY_OF_YEAR/DOY`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DAY_OF_YEAR(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the day of the year from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dayOfYear]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-dayname]]
|
|
==== `DAY_NAME/DAYNAME`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
DAY_NAME(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: string
|
|
|
|
*Description*: Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`...).
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dayName]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-hour]]
|
|
==== `HOUR_OF_DAY/HOUR`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
HOUR_OF_DAY(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the hour of the day from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[hourOfDay]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-isodow]]
|
|
==== `ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ISO_DAY_OF_WEEK(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the day of the week from a date/datetime, following the {wikipedia}/ISO_week_date[ISO 8601 standard].
|
|
Monday is `1`, Tuesday is `2`, etc.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[isoDayOfWeek]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-isoweek]]
|
|
==== `ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ISO_WEEK_OF_YEAR(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the week of the year from a date/datetime, following {wikipedia}/ISO_week_date[ISO 8601 standard]. The first week
|
|
of a year is the first week with a majority (4 or more) of its days in January.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[isoWeekOfYear]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-minuteofday]]
|
|
==== `MINUTE_OF_DAY`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
MINUTE_OF_DAY(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the minute of the day from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[minuteOfDay]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-minute]]
|
|
==== `MINUTE_OF_HOUR/MINUTE`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
MINUTE_OF_HOUR(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the minute of the hour from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[minuteOfHour]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-month]]
|
|
==== `MONTH_OF_YEAR/MONTH`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
MONTH(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the month of the year from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[monthOfYear]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-monthname]]
|
|
==== `MONTH_NAME/MONTHNAME`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
MONTH_NAME(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: string
|
|
|
|
*Description*: Extract the month from a date/datetime in text format (`January`, `February`...).
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[monthName]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-now]]
|
|
==== `NOW`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
NOW()
|
|
--------------------------------------------------
|
|
|
|
*Input*: _none_
|
|
|
|
*Output*: datetime
|
|
|
|
*Description*: This function offers the same functionality as <<sql-functions-current-timestamp,CURRENT_TIMESTAMP()>> function: returns
|
|
the datetime when the current query reached the server. This method always returns the same value for its every
|
|
occurrence within the same query.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[nowFunction]
|
|
--------------------------------------------------
|
|
|
|
Typically, this function (as well as its twin <<sql-functions-current-timestamp,CURRENT_TIMESTAMP())>> function is used
|
|
for relative date/time filtering:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[filterNow]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-second]]
|
|
==== `SECOND_OF_MINUTE/SECOND`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
SECOND_OF_MINUTE(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the second of the minute from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[secondOfMinute]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-quarter]]
|
|
==== `QUARTER`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
QUARTER(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the year quarter the date/datetime falls in.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[quarter]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-today]]
|
|
==== `TODAY`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
TODAY()
|
|
--------------------------------------------------
|
|
|
|
*Input*: _none_
|
|
|
|
*Output*: date
|
|
|
|
*Description*: This function offers the same functionality as <<sql-functions-current-date,CURRENT_DATE()>> function: returns
|
|
the date when the current query reached the server. This method always returns the same value for its every occurrence
|
|
within the same query.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[todayFunction]
|
|
--------------------------------------------------
|
|
|
|
Typically, this function (as well as its twin <<sql-functions-current-timestamp,CURRENT_TIMESTAMP())>> function is used
|
|
for relative date filtering:
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[filterToday]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-week]]
|
|
==== `WEEK_OF_YEAR/WEEK`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
WEEK_OF_YEAR(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the week of the year from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[weekOfYear]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-year]]
|
|
==== `YEAR`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
YEAR(datetime_exp) <1>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract the year from a date/datetime.
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[year]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-datetime-extract]]
|
|
==== `EXTRACT`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
EXTRACT(
|
|
datetime_function <1>
|
|
FROM datetime_exp) <2>
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> date/time function name
|
|
<2> date/datetime expression
|
|
|
|
*Output*: integer
|
|
|
|
*Description*: Extract fields from a date/datetime by specifying the name of a <<sql-functions-datetime,datetime function>>.
|
|
The following
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[extractDayOfYear]
|
|
--------------------------------------------------
|
|
|
|
is the equivalent to
|
|
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/docs.csv-spec[dayOfYear]
|
|
--------------------------------------------------
|