Update docs.md

documentation20/en/12.taos-sql/docs.md

@@ -1408,15 +1408,15 @@ TDengine supports aggregations over data, they are listed below:
     ```mysql
     SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_name [WHERE clause];
     ```
-    Function：Returns count of data points in user-specified ranges.
+    Function: Returns count of data points in user-specified ranges.
 
-    Return Data Type：Double or INT64, depends on normalized parameter settings.
+    Return Data Type: Double or INT64, depends on normalized parameter settings.
 
-    Applicable Fields：Numerical types.
+    Applicable Fields: Numerical types.
 
     Applied to: **table stable**.
 
-    Note：
+    Note:
     1. This function is supported since 2.6.0.0.
     2. bin_type: parameter to indicate the bucket type, valid inputs are: "user_input", "linear_bin", "log_bin"。
     3）bin_description: parameter to describe how to generate buckets，can be in the following JSON formats for each bin_type respectively:
@@ -1438,7 +1438,7 @@ TDengine supports aggregations over data, they are listed below:
        The above "log_bin" descriptor generates a set of bins:[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf].
     4）normalized: setting to 1/0 to turn on/off result normalization.
 
-    Example：
+    Example:
     ```mysql
      taos> SELECT HISTOGRAM(voltage, "user_input", "[1,3,5,7]", 1) FROM meters;
          histogram(voltage, "user_input", "[1,3,5,7]", 1) |
@@ -1465,7 +1465,259 @@ TDengine supports aggregations over data, they are listed below:
      {"lower_bin":9, "upper_bin":27, "count":3}                       |
      {"lower_bin":27, "upper_bin":inf, "count":1}                     |
     ```
+### Time Functions
+
+Starting from version 2.6.0.0, TDengine supports following time related functions:
+
+- **NOW**
+    ```mysql
+    SELECT NOW() FROM { tb_name | stb_name } [WHERE clause];
+    SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW();
+    INSERT INTO tb_name VALUES (NOW(), ...);
+    ```
+    Function: Returns current time of client.
+
+    Returned Data Type: TIMESTAMP type.
+
+    Applicable Fields: Can only be applied to TIMESTAMP field when used in WHERE or INSERT clause.
+
+    Applied to: **table stable**.
+
+    Note:
+      1）Support arithmetic operations，e.g. NOW() + 1s. Valid time unit:
+         b(nanosecond)、u(microsecond)、a(millisecond)、s(second)、m(minute)、h(hour)、d(day)、w(week).
+      2）Returned timestamp precision is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT NOW() FROM meters;
+              now()          |
+    ==========================
+      2022-02-02 02:02:02.456 |
+    Query OK, 1 row(s) in set (0.002093s)
+      
+    taos> SELECT NOW() + 1h FROM meters;
+           now() + 1h         |
+    ==========================
+      2022-02-02 03:02:02.456 |
+    Query OK, 1 row(s) in set (0.002093s)
+    
+    taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW();
+            count(voltage)       |
+    =============================
+                               5 |
+    Query OK, 5 row(s) in set (0.004475s)
+    
+    taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32);
+    Query OK, 1 of 1 row(s) in database (0.002210s)
+    ```
+
+- **TODAY**
+    ```mysql
+    SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause];
+    SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()];
+    INSERT INTO tb_name VALUES (TODAY(), ...);
+    ```
+    Function: Returns current date of client.
+
+    Returned Data Type: TIMESTAMP type。
+
+    Applicable Fields: Can only be applied to TIMESTAMP field when used in WHERE or INSERT clause.
+
+    Applied to: **table stable**.
+
+    Note:
+      1）Support arithmetic operations, e.g. TODAY() + 1s. Valid time unit:
+         b(nanosecond)、u(microsecond)、a(millisecond)、s(second)、m(minute)、h(hour)、d(day)、w(week).
+      2）Returned timestamp precision is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT TODAY() FROM meters;
+             today()          |
+    ==========================
+      2022-02-02 00:00:00.000 |
+    Query OK, 1 row(s) in set (0.002093s)
+      
+    taos> SELECT TODAY() + 1h FROM meters;
+          today() + 1h        |
+    ==========================
+      2022-02-02 01:00:00.000 |
+    Query OK, 1 row(s) in set (0.002093s)
+    
+    taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY();
+            count(voltage)       |
+    =============================
+                               5 |
+    Query OK, 5 row(s) in set (0.004475s)
+    
+    taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32);
+    Query OK, 1 of 1 row(s) in database (0.002210s)
+    ```
+
+- **TIMEZONE**
+    ```mysql
+    SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause];
+    ```
+    Function: Returns current timezone information of client.
+
+    Returned Data Type: BINARY type.
+
+    Applicable Fields: N/A.
+
+    Applied to: **table stable**.
+
+    Example:
+    ```mysql
+    taos> SELECT TODAY() FROM meters;
+               timezone()           |
+    =================================
+     UTC (UTC, +0000)               |
+    Query OK, 1 row(s) in set (0.002093s)
+    ```
+
+- **TO_ISO8601**
+    ```mysql
+    SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause];
+    ```
+    Function: Convert UNIX timestamp to ISO8601 standard date-time format string, with client timezone infomation attached.
+
+    Returned Data Type: BINARY type.
+
+    Applicable Fields: UNIX timestamp constant and TIMESTAMP type columns.
+
+    Applied to: **table stable**.
+    
+    Note: If input is UNIX timestamp constant，returned ISO8601 format precision is determined by input timestap digits. If input is TIMSTAMP type column, returned ISO8601 format precision is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT TO_ISO8601(1643738400) FROM meters;
+       to_iso8601(1643738400)    |
+    ==============================
+     2022-02-02T02:00:00+0800    |
+     
+    taos> SELECT TO_ISO8601(ts) FROM meters;
+           to_iso8601(ts)        |
+    ==============================
+     2022-02-02T02:00:00+0800    |
+     2022-02-02T02:00:00+0800    |
+     2022-02-02T02:00:00+0800    |
+    ```
+
+ - **TO_UNIXTIMESTAMP**
+    ```mysql
+    SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause];
+    ```
+    Function: Convert date-time format string to UNIX timestamp.
+
+    Returned Data Type: INT64.
+
+    Applicable Fields: String literal or BINARY/NCHAR type columns.
+
+    Applied to: **table stable**.
+    
+    Note:
+    1）Input date-time string format should conform ISO8601/RFC3339 standard，otherwise conversion will fail and 0 is returned.
+    2）Returned timestamp precision is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters;
+    to_unixtimestamp("2022-02-02T02:00:00.000Z") |
+    ==============================================
+                                   1643767200000 |
+     
+    taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters;
+          to_unixtimestamp(col_binary)     |
+    ========================================
+                             1643767200000 |
+                             1643767200000 |
+                             1643767200000 |
+    ```
+
+ - **TIMETRUNCATE**
+    ```mysql
+    SELECT TIMEDIFF(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause];
+    ```
+    Function: Truncate timestamp by time_unit.
+
+    Returned Data Type: TIMESTAMP type.
 
+    Applicable Fields: UNIX timestamp, date-time format string, and TIMESTAMP type columns.
+
+    Applied to: **table stable**.
+    
+    Note:
+    1）Supported time_unit:
+         1u(microsecond)，1a(millisecond)，1s(second)，1m(minute)，1h(hour)，1d(day)。
+    2）Returned timestamp precision is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters;
+      timetruncate(1643738522000, 1h) |
+    ===================================
+          2022-02-02 02:00:00.000     |
+    Query OK, 1 row(s) in set (0.001499s)
+    
+    taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters;
+      timetruncate("2022-02-02 02:02:02", 1h) |
+    ===========================================
+          2022-02-02 02:00:00.000             |
+    Query OK, 1 row(s) in set (0.003903s)
+    
+    taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters;
+      timetruncate(ts, 1h)   |
+    ==========================
+     2022-02-02 02:00:00.000 |
+     2022-02-02 02:00:00.000 |
+     2022-02-02 02:00:00.000 |
+    Query OK, 3 row(s) in set (0.003903s)
+    ```
+
+ - **TIMEDIFF**
+    ```mysql
+    SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause];
+    ```
+    Function: Calculate duration between two timestamps with time_unit precision。
+
+    Returned Data Type: INT64.
+
+    Applicable Fields: UNIX timestamp, date-time format string, and TIMESTAMP type columns.
+
+    Applied to: **table stable**.
+    
+    Note:
+    1）Supported time_unit:
+         1u(microsecond)，1a(millisecond)，1s(second)，1m(minute)，1h(hour)，1d(day)。
+    2）If time_unit is unspecified, returned time duration unit is consist with current DATABASE precision settings.
+
+    Example:
+    ```mysql
+    taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters;
+     timediff(1643738400000, 1643742000000) |
+    =========================================
+                                    3600000 |
+    Query OK, 1 row(s) in set (0.002553s)
+    taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters;
+     timediff(1643738400000, 1643742000000, 1h) |
+    =============================================
+                                              1 |
+    Query OK, 1 row(s) in set (0.003726s)
+    
+    taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters;
+     timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) |
+    =============================================================
+                                                              1 |
+    Query OK, 1 row(s) in set (0.001937s)
+    
+    taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters;
+       timediff(ts_col1, ts_col2, 1h) |
+    ===================================
+                                    1 |
+    Query OK, 1 row(s) in set (0.001937s)
+    ```
 
 ## <a class="anchor" id="aggregation"></a> Time-dimension Aggregation