Merge pull request #7265 from soyeric128/new-time-formats

docs: new time formats

docs/doc/30-reference/10-data-types/20-data-type-time-date-types.md

@@ -15,13 +15,13 @@ description: Basic Date and Time data type.
 See [Date & Time Functions](/doc/reference/functions/datetime-functions).
 
 ## Example
-```sql
-CREATE TABLE test_dt
-(
-    date DATE,
-    ts TIMESTAMP 
-);
 
+```sql
+CREATE TABLE test_dt 
+  ( 
+     date DATE, 
+     ts   TIMESTAMP 
+  ); 
 
 DESC test_dt;
 +-------+--------------+------+---------+-------+
@@ -31,13 +31,95 @@ DESC test_dt;
 | ts    | TIMESTAMP(6) | NO   | 0       |       |
 +-------+--------------+------+---------+-------+
 
-INSERT INTO test_dt VALUES ('2022-04-07', '2022-04-07 01:01:01.123456'), ('2022-04-08', '2022-04-08 01:01:01');
+-- A TIMESTAMP value can optionally include a trailing fractional seconds part in up to microseconds (6 digits) precision.
+
+INSERT INTO test_dt 
+VALUES      ('2022-04-07', 
+             '2022-04-07 01:01:01.123456'), 
+            ('2022-04-08', 
+             '2022-04-08 01:01:01'); 
 
-SELECT * FROM TEST_DT;
+SELECT * 
+FROM   test_dt; 
 +------------+----------------------------+
 | date       | ts                         |
 +------------+----------------------------+
 | 2022-04-07 | 2022-04-07 01:01:01.123456 |
 | 2022-04-08 | 2022-04-08 01:01:01.000000 |
 +------------+----------------------------+
-```
+
+-- Databend recognizes TIMESTAMP values in several formats.
+
+CREATE TABLE test_formats 
+  ( 
+     id INT, 
+     a  TIMESTAMP 
+  ); 
+
+INSERT INTO test_formats 
+VALUES      (1, 
+             '2022-01-01 02:00:11'), 
+            (2, 
+             '2022-01-02T02:00:22'), 
+            (3, 
+             '2022-02-02T04:00:03+00:00'), 
+            (4, 
+             '2022-02-03'); 
+
+SELECT * 
+FROM   test_formats; 
+
+ ----
+ 1  2022-01-01 02:00:11.000000
+ 2  2022-01-02 02:00:22.000000
+ 3  2022-02-02 04:00:03.000000
+ 4  2022-02-03 00:00:00.000000
+
+-- Databend automatically adjusts and shows TIMESTAMP values based on your current timezone.
+
+CREATE TABLE test_tz 
+  ( 
+     id INT, 
+     t  TIMESTAMP 
+  ); 
+
+SET timezone='UTC';
+
+INSERT INTO test_tz 
+VALUES      (1, 
+             '2022-02-03T03:00:00'), 
+            (2, 
+             '2022-02-03T03:00:00+08:00'), 
+            (3, 
+             '2022-02-03T03:00:00-08:00'), 
+            (4, 
+             '2022-02-03'), 
+            (5, 
+             '2022-02-03T03:00:00+09:00'), 
+            (6, 
+             '2022-02-03T03:00:00+06:00'); 
+
+SELECT * 
+FROM   test_tz; 
+
+ ----
+ 1  2022-02-03 03:00:00.000000
+ 2  2022-02-02 19:00:00.000000
+ 3  2022-02-03 11:00:00.000000
+ 4  2022-02-03 00:00:00.000000
+ 5  2022-02-02 18:00:00.000000
+ 6  2022-02-02 21:00:00.000000
+
+SET timezone='Asia/Shanghai';
+
+SELECT * 
+FROM   test_tz; 
+
+ ----
+ 1  2022-02-03 11:00:00.000000
+ 2  2022-02-03 03:00:00.000000
+ 3  2022-02-03 19:00:00.000000
+ 4  2022-02-03 08:00:00.000000
+ 5  2022-02-03 02:00:00.000000
+ 6  2022-02-03 05:00:00.000000
+```

docs/doc/30-reference/20-functions/30-datetime-functions/timezone.md

@@ -0,0 +1,35 @@
+---
+title: TIMEZONE
+---
+
+Returns the timezone for the current connection. 
+
+Databend uses UTC (Coordinated Universal Time) as the default timezone and allows you to change the timezone to your current geographic location. For the available values you can assign to the `timezone` setting, refer to https://docs.rs/chrono-tz/latest/chrono_tz/enum.Tz.html. See the examples below for details.
+
+## Syntax
+
+```
+SELECT TIMEZONE();
+```
+
+## Examples
+
+```sql
+-- Return the current timezone
+SELECT TIMEZONE();
++-----------------+
+| TIMEZONE('UTC') |
++-----------------+
+| UTC             |
++-----------------+
+
+-- Set the timezone to China Standard Time
+SET timezone='Asia/Shanghai';
+
+SELECT TIMEZONE();
++---------------------------+
+| TIMEZONE('Asia/Shanghai') |
++---------------------------+
+| Asia/Shanghai             |
++---------------------------+
+```