diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 7a0662641..6eb4125bc 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -522,13 +522,23 @@ If the date string does not explicitly declare the value of a component, then th * The month and day default to 1. * The century (when not specified by year) defaults to 19 if year is greater than or equal to 69, or 20 otherwise. * All other numeric components default to 0. -* The time zone defaults to the local local system time zone. +* The time zone defaults to the local system time zone. In cases where the timezone is not specified, the local system time is assumed. For example, `2016-02-07` is equivalent to `2016-02-07T00:00:00` and parsing just `16` as the year is equivalent to `2016-01-01T00:00:00` in the local system time zone. ==== +[NOTE#tzn-date-format] +.TZN Date Format +==== +In addition to the date formats listed <>, {sqlpp} also supports the `TZN` (Time Zone Name) format. +This format parses date strings in the same way as `TZD` but outputs the time zone name instead of the offset. +For example, the `TZN` representation of the "Australia/Darwin" time zone is `ACST`. + +For an example of its usage, refer to the <> function. +==== + [#manipulating-components] == Manipulating Date Components @@ -1236,7 +1246,7 @@ WHERE reviews[0].date BETWEEN "2013-01-01 %" AND "2014-01-01 %"; NOTE: When querying between two dates, you must specify the full date (with time and time zone) or use the wildcard character (%). [#fn-date-format-str] -== DATE_FORMAT_STR(date1, fmt) +== DATE_FORMAT_STR(date1, [input-fmt,] fmt) === Description @@ -1249,6 +1259,13 @@ A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which + If this argument is not a valid date string then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + fmt:: A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> to output the result as. + @@ -1265,7 +1282,8 @@ A date string in the format specified. ---- SELECT DATE_FORMAT_STR('2016-05-15T00:00:23+00:00', '1111-11-11') as full_to_short, DATE_FORMAT_STR('2016-05-15', '1111-11-11T00:00:00+00:00') as short_to_full, - DATE_FORMAT_STR('01:10:05', '1111-11-11T01:01:01Z') as time_to_full; + DATE_FORMAT_STR('01:10:05', '1111-11-11T01:01:01Z') as time_to_full, + DATE_FORMAT_STR('15-MAY-2016', 'DD-MON-YYYY', 'YYYY-MM-DD') as month_to_numeric; ---- .Results @@ -1274,8 +1292,9 @@ SELECT DATE_FORMAT_STR('2016-05-15T00:00:23+00:00', '1111-11-11') as full_to_sho [ { "full_to_short": "2016-05-15", - "short_to_full": "2016-05-15T00:00:00-07:00", - "time_to_full": "0000-01-01T01:10:05-08:00" + "short_to_full": "2016-05-15T00:00:00Z", + "time_to_full": "0000-01-01T01:10:05Z", + "month_to_numeric": "2016-05-15" } ] ---- @@ -1735,15 +1754,15 @@ SELECT DATE_TRUNC_MILLIS(1463284740000, 'day') as day, [ { "day": 1463270400000, - "month": 1462147200000, - "year": 1451696400000 + "month": 1462060800000, + "year": 1451606400000 } ] ---- ==== [#fn-date-trunc-str] -== DATE_TRUNC_STR(date1, part) +== DATE_TRUNC_STR(date1, part [,fmt]) === Description @@ -1763,6 +1782,13 @@ This function accepts the components `millennium`, `century`, `decade`, `year`, + If an invalid part is specified, then `null` is returned. +fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format. + === Return Value A date string representing the truncated date. @@ -1774,7 +1800,8 @@ A date string representing the truncated date. ---- SELECT DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'day') as day, DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'month') as month, - DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'year') as year; + DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'year') as year, + DATE_TRUNC_STR('05/18/2016 03:59:00', 'month', 'MM/DD/YYYY HH24:MI:SS') as month_custom; ---- .Results @@ -1784,7 +1811,8 @@ SELECT DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'day') as day, { "day": "2016-05-18T00:00:00Z", "month": "2016-05-01T00:00:00Z", - "year": "2016-01-01T00:00:00Z" + "year": "2016-01-01T00:00:00Z", + "month_custom": "05/01/2016 00:00:00" } ] ---- @@ -2530,12 +2558,13 @@ AS Milliseconds; ==== [#fn-date-str-to-utc] -== STR_TO_UTC(date1) +== STR_TO_UTC(date1 [, [input-fmt,] fmt]) === Description Converts a date string into the equivalent date in UTC. -The output date format follows the date format of the date passed as input. +By default, the output date format follows the date format of the date passed as input. +However, you can specify a different output format if needed. === Arguments @@ -2545,6 +2574,20 @@ This is the date to convert to UTC. + If this argument is not a valid date format, then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + +fmt:: +The format of the resulting UTC date. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, and must be a <>. ++ +*Optional argument*. +If not specified, the output date format follows the date format of the input string, `date1`. + === Return Value A single date string representing the date string converted to UTC. @@ -2555,7 +2598,8 @@ A single date string representing the date string converted to UTC. [source,sqlpp] ---- SELECT STR_TO_UTC('1111-11-11T00:00:00+08:00') as full_date, -STR_TO_UTC('1111-11-11') as short_date; + STR_TO_UTC('1111-11-11') as short_date, + STR_TO_UTC('1111-11-11', 'YYYY-MM-DD', 'YYYY-MM-DD HH:MI:SS') as utc_date; ---- .Results @@ -2564,19 +2608,21 @@ STR_TO_UTC('1111-11-11') as short_date; [ { "full_date": "1111-11-10T16:00:00Z", - "short_date": "1111-11-11" + "short_date": "1111-11-11", + "utc_date": "1111-11-11 12:00:00" } ] ---- ==== [#fn-date-str-to-tz] -== STR_TO_TZ(date1, tz) +== STR_TO_TZ(date1, tz [, [input-fmt,] fmt]) === Description Converts a date string to its equivalent in the specified timezone. -The output date format follows the date format of the date passed as input. +By default, the output date format follows the date format of the date passed as input. +However, you can specify a different output format if needed. === Arguments @@ -2591,10 +2637,25 @@ A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which + If this argument is not a valid timezone, then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + +fmt:: +The format of the output date. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, and must be a <>. ++ +*Optional argument*. +If not specified, the output date format follows the date format of the input string, `date1`. + === Return Value A single date string representing the date string converted to the specified timezone. +[[ex-str-to-tz]] === Examples ==== @@ -2602,7 +2663,10 @@ A single date string representing the date string converted to the specified tim ---- SELECT STR_TO_TZ('1111-11-11T00:00:00+08:00', 'America/New_York') as est, STR_TO_TZ('1111-11-11T00:00:00+08:00', 'UTC') as utc, - STR_TO_TZ('1111-11-11', 'UTC') as utc_short; + STR_TO_TZ('1111-11-11', 'UTC') as utc_short, + STR_TO_TZ('1111-11-11', 'UTC', 'YYYY-MM-DD', 'YYYY-MM-DD HH:MI:SS') as utc_datetime, + STR_TO_TZ('1111-11-11T00:00:00+07:00', 'Europe/Paris', + "YYYY-MM-DDThh:mm:ssTZD", "YYYY-MM-DDThh:mm:ssTZN") as tzn; ---- .Results @@ -2610,9 +2674,11 @@ SELECT STR_TO_TZ('1111-11-11T00:00:00+08:00', 'America/New_York') as est, ---- [ { - "est": "1111-11-10T11:00:00-05:00", + "est": "1111-11-10T11:03:58-04:56", "utc": "1111-11-10T16:00:00Z", - "utc_short": "1111-11-11" + "utc_short": "1111-11-11", + "utc_datetime": "1111-11-11 12:00:00", + "tzn": "1111-11-10T17:09:21LMT" } ] ----