Skip to content

[DOC-11152] Changes to date functions #383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jul 30, 2025
Merged

[DOC-11152] Changes to date functions #383

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
74af3e4
Updates to DATE_FORMAT_STR()
rakhi-prathap Jun 13, 2025
4b1a8a6
Updates to DATE_TRUNC_STR()
rakhi-prathap Jun 13, 2025
48abfb6
Changes to str_to_utc and str_to_tz
rakhi-prathap Jun 13, 2025
c3aad9f
Correct the date_trunc_millis example
rakhi-prathap Jun 13, 2025
4d55a6d
Add a note about TZN
rakhi-prathap Jul 16, 2025
c9f9254
Add a note about TZN
rakhi-prathap Jul 24, 2025
c9e1f20
update content
rakhi-prathap Jul 26, 2025
7d38347
Update content
rakhi-prathap Jul 28, 2025
b711fa9
a minor tweak
rakhi-prathap Jul 28, 2025
90fd9c5
Add examples for TZN and update the note
rakhi-prathap Jul 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 85 additions & 19 deletions modules/n1ql/pages/n1ql-language-reference/datefun.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<date-string,here>>, {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 <<ex-str-to-tz,STR_TO_TZ()>> function.
====

[#manipulating-components]
== Manipulating Date Components

Expand Down Expand Up @@ -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

Expand All @@ -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 <<date-string,supported date format>> to output the result as.
+
Expand All @@ -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
Expand All @@ -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"
}
]
----
Expand Down Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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"
}
]
----
Expand Down Expand Up @@ -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

Expand All @@ -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 <<date-string,supported date format>>.
+
*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.
Expand All @@ -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
Expand All @@ -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

Expand All @@ -2591,28 +2637,48 @@ 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 <<date-string,supported date format>>.
+
*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

====
[source,sqlpp]
----
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
[source,json]
----
[
{
"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"
}
]
----
Expand Down