From 74af3e4e8fb0b2b22be5fd792e855a80f98bc164 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 13 Jun 2025 11:15:35 +0530 Subject: [PATCH 01/10] Updates to DATE_FORMAT_STR() --- .../pages/n1ql-language-reference/datefun.adoc | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 7a0662641..aeae589c5 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -1236,7 +1236,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 +1249,12 @@ 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:: +A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> that the `date1` argument is in. ++ +*Optional argument*. +Only required if the desired output format does not match the input format and `date1` isn't in a standard format. + 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 +1271,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 +1281,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" } ] ---- From 4b1a8a6a53c6614be16f0205763b246ab58ef752 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 13 Jun 2025 13:03:58 +0530 Subject: [PATCH 02/10] Updates to DATE_TRUNC_STR() --- .../pages/n1ql-language-reference/datefun.adoc | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index aeae589c5..afeea5a23 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -1751,7 +1751,7 @@ SELECT DATE_TRUNC_MILLIS(1463284740000, 'day') as day, ==== [#fn-date-trunc-str] -== DATE_TRUNC_STR(date1, part) +== DATE_TRUNC_STR(date1, part [,fmt]) === Description @@ -1771,6 +1771,12 @@ This function accepts the components `millennium`, `century`, `decade`, `year`, + If an invalid part is specified, then `null` is returned. +fmt:: +A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> that the `date1` argument is in. ++ +*Optional argument*. +Only required if `date1` is not in a standard format. + === Return Value A date string representing the truncated date. @@ -1782,7 +1788,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 @@ -1792,7 +1799,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" } ] ---- From 48abfb661cabc240102424ff055d3258558c68b8 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 13 Jun 2025 14:59:54 +0530 Subject: [PATCH 03/10] Changes to str_to_utc and str_to_tz --- .../n1ql-language-reference/datefun.adoc | 54 +++++++++++++++---- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index afeea5a23..8e9b0c729 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -1250,10 +1250,11 @@ 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:: -A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> that the `date1` argument is in. +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 the desired output format does not match the input format and `date1` isn't in a standard format. +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. @@ -1772,7 +1773,8 @@ This function accepts the components `millennium`, `century`, `decade`, `year`, If an invalid part is specified, then `null` is returned. fmt:: -A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> that the `date1` argument is in. +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. @@ -2546,7 +2548,7 @@ AS Milliseconds; ==== [#fn-date-str-to-utc] -== STR_TO_UTC(date1) +== STR_TO_UTC(date1 [, [input-fmt,] fmt]) === Description @@ -2561,6 +2563,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. @@ -2571,7 +2587,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 @@ -2580,14 +2597,15 @@ 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 @@ -2607,6 +2625,20 @@ 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. @@ -2618,7 +2650,8 @@ 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; ---- .Results @@ -2626,9 +2659,10 @@ 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" } ] ---- From c3aad9fedce768a51eb0916ab894bd95e6d15329 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 13 Jun 2025 15:05:33 +0530 Subject: [PATCH 04/10] Correct the date_trunc_millis example --- modules/n1ql/pages/n1ql-language-reference/datefun.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 8e9b0c729..9e1bd66c0 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -1744,8 +1744,8 @@ SELECT DATE_TRUNC_MILLIS(1463284740000, 'day') as day, [ { "day": 1463270400000, - "month": 1462147200000, - "year": 1451696400000 + "month": 1462060800000, + "year": 1451606400000 } ] ---- From 4d55a6d4a90c9c46aa3df8d1ccaa09a510dae61a Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 16 Jul 2025 19:52:58 +0530 Subject: [PATCH 05/10] Add a note about TZN --- .../n1ql/pages/n1ql-language-reference/datefun.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 9e1bd66c0..9e72f5b71 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -515,8 +515,9 @@ For example, `%Y %m %d` parses `2021-06-28`, `2021/06/28`, `2021.06.28`, and so ==== [NOTE#default-values] -.Default Values ==== +*Default Values* + If the date string does not explicitly declare the value of a component, then the following default values are assumed: * The month and day default to 1. @@ -527,8 +528,16 @@ If the date string does not explicitly declare the value of a component, then th 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. + +--- +*TZN Date Format* + +In addition to the date formats listed previously, {sqlpp} also supports the `TZN` date format that parses strings just as `TZD` but outputs the time zone name rather than the offset. + ==== +// NOTE: In addition to the above date formats, {sqlpp} also supports the `TZN`date format that parses strings just as `TZD` but outputs the time zone name rather than the offset. + [#manipulating-components] == Manipulating Date Components From c9f9254ead9218090f3fbcc88dbfee6fcc8422fe Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 24 Jul 2025 16:56:10 +0530 Subject: [PATCH 06/10] Add a note about TZN --- .../pages/n1ql-language-reference/datefun.adoc | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 9e72f5b71..14e68d104 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -515,9 +515,8 @@ For example, `%Y %m %d` parses `2021-06-28`, `2021/06/28`, `2021.06.28`, and so ==== [NOTE#default-values] +.Default Values ==== -*Default Values* - If the date string does not explicitly declare the value of a component, then the following default values are assumed: * The month and day default to 1. @@ -528,15 +527,14 @@ If the date string does not explicitly declare the value of a component, then th 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. - ---- -*TZN Date Format* - -In addition to the date formats listed previously, {sqlpp} also supports the `TZN` date format that parses strings just as `TZD` but outputs the time zone name rather than the offset. - ==== -// NOTE: In addition to the above date formats, {sqlpp} also supports the `TZN`date format that parses strings just as `TZD` but outputs the time zone name rather than the offset. +[NOTE#tzn-date-format] +.TZN Date Format +==== +In addition to the previously listed date formats, {sqlpp} also supports the `TZN` date format. +This format parses date strings like the `TZD` format but outputs the time zone name instead of the offset. +==== [#manipulating-components] == Manipulating Date Components From c9e1f20fe3fb9989bc8a8c42432c8e5b72b19c27 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Sat, 26 Jul 2025 13:17:06 +0530 Subject: [PATCH 07/10] update content --- modules/n1ql/pages/n1ql-language-reference/datefun.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 14e68d104..8c58db8d2 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -2560,7 +2560,8 @@ AS Milliseconds; === 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 From 7d38347a43b7ef1ebf0d26cd4a9763a2e50c4919 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 28 Jul 2025 09:36:38 +0530 Subject: [PATCH 08/10] Update content --- modules/n1ql/pages/n1ql-language-reference/datefun.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 8c58db8d2..3dd5a1cd1 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -2618,7 +2618,8 @@ SELECT STR_TO_UTC('1111-11-11T00:00:00+08:00') as full_date, === 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 From b711fa96c5f767f6989cacb929baf01365a996e4 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 28 Jul 2025 09:56:46 +0530 Subject: [PATCH 09/10] a minor tweak --- modules/n1ql/pages/n1ql-language-reference/datefun.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 3dd5a1cd1..07c09b513 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -533,7 +533,7 @@ For example, `2016-02-07` is equivalent to `2016-02-07T00:00:00` and parsing jus .TZN Date Format ==== In addition to the previously listed date formats, {sqlpp} also supports the `TZN` date format. -This format parses date strings like the `TZD` format but outputs the time zone name instead of the offset. +This format parses date strings like `TZD` but outputs the time zone name instead of the offset. ==== [#manipulating-components] From 90fd9c5f078184547a33c13ce00a065a471f1f1b Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 29 Jul 2025 20:28:52 +0530 Subject: [PATCH 10/10] Add examples for TZN and update the note --- .../pages/n1ql-language-reference/datefun.adoc | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 07c09b513..6eb4125bc 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -522,7 +522,7 @@ 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. @@ -532,8 +532,11 @@ For example, `2016-02-07` is equivalent to `2016-02-07T00:00:00` and parsing jus [NOTE#tzn-date-format] .TZN Date Format ==== -In addition to the previously listed date formats, {sqlpp} also supports the `TZN` date format. -This format parses date strings like `TZD` but outputs the time zone name instead of the offset. +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] @@ -2652,6 +2655,7 @@ If not specified, the output date format follows the date format of the input st A single date string representing the date string converted to the specified timezone. +[[ex-str-to-tz]] === Examples ==== @@ -2660,7 +2664,9 @@ 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', 'YYYY-MM-DD', 'YYYY-MM-DD HH:MI:SS') as utc_datetime; + 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 @@ -2671,7 +2677,8 @@ SELECT STR_TO_TZ('1111-11-11T00:00:00+08:00', 'America/New_York') as est, "est": "1111-11-10T11:03:58-04:56", "utc": "1111-11-10T16:00:00Z", "utc_short": "1111-11-11", - "utc_datetime": "1111-11-11 12:00:00" + "utc_datetime": "1111-11-11 12:00:00", + "tzn": "1111-11-10T17:09:21LMT" } ] ----